Implementation:Vespa engine Vespa LogSetup InitVespaLogging

LogSetup.initVespaLogging

API Signature

public static void initVespaLogging(String programName)

Source Location

File: vespalog/src/main/java/com/yahoo/log/LogSetup.java
Lines: L81-129
Class: public class LogSetup
Package: com.yahoo.log

Description

initVespaLogging is the primary entry point for initializing Vespa's logging framework in Java processes. It resolves log configuration from system properties and environment variables, sets up the log target, creates the level controller, and installs the custom VespaLogHandler on the root JUL logger.

This method must be called exactly once at process startup before any logging occurs. It is a static method that sets global state.

Key Fields

Field	Type	Purpose
`taskRunner`	`Timer`	Schedules periodic tasks (e.g., control file re-check)
`logHandler`	`VespaLogHandler`	The installed JUL handler for Vespa-format logging
`zooKeeperFilter`	`ZooKeeperFilter`	Filters ZooKeeper client log messages to a separate target
`isInitialized`	`boolean`	Guard flag preventing double initialization

Parameters

Parameter	Type	Description
`programName`	`String`	The name of the program (e.g., `"configserver"`, `"container"`). Must be non-null and non-empty.

Return Value

void -- This method has no return value. It modifies global logging state as a side effect.

Exceptions

Exception	Condition
`RuntimeException`	If `programName` is null or empty
`RuntimeException`	If the log target file cannot be opened (wraps `FileNotFoundException`)

Full Method Source

public static void initVespaLogging(String programName) {
    if (isInitialized) {
        System.err.println("WARNING: initVespaLogging called twice");
    }
    isInitialized = true;

    String logLevel = System.getProperty("vespa.log.level");
    String logTarget = System.getProperty("vespa.log.target");
    String logService = System.getProperty("vespa.service.name");
    String logControlDir = System.getProperty("vespa.log.control.dir");
    String logControlFile = System.getProperty("vespa.log.control.file");

    if (programName == null || programName.equals("")) {
        throw new RuntimeException("invalid programName: " + programName);
    }

    if (logTarget == null) logTarget = System.getenv("VESPA_LOG_TARGET");
    if (logService == null) logService = System.getenv("VESPA_SERVICE_NAME");
    if (logControlDir == null) logControlDir = System.getenv("VESPA_LOG_CONTROL_DIR");
    if (logControlFile == null) logControlFile = System.getenv("VESPA_LOG_CONTROL_FILE");
    if (logLevel == null) logLevel = System.getenv("VESPA_LOG_LEVEL");

    if (logTarget == null) logTarget = "fd:2";
    if (logLevel == null) logLevel = "all -debug -spam";

    if (logControlFile == null && logControlDir != null && logService != null
        && !logService.equals("") && !logService.equals("-")) {
        logControlFile = logControlDir + "/" + logService + ".logcontrol";
    }

    if (logService == null) logService = System.getProperty("config.id");
    if (logService == null) logService = "-";

    System.setProperty("vespa.service.name", logService);
    System.setProperty("vespa.program.name", programName);

    try {
        initInternal(logTarget, logService, logControlFile, programName, logLevel);
    } catch (FileNotFoundException e) {
        throw new RuntimeException("Unable to initialize logging", e);
    }
}

Configuration Resolution Logic

The method resolves each configuration value through a three-tier precedence chain:

Step 1: Read System Properties

String logLevel = System.getProperty("vespa.log.level");
String logTarget = System.getProperty("vespa.log.target");
String logService = System.getProperty("vespa.service.name");
String logControlDir = System.getProperty("vespa.log.control.dir");
String logControlFile = System.getProperty("vespa.log.control.file");

System properties have the highest precedence. They are typically set via JVM flags like -Dvespa.log.target=file:/var/log/vespa.log.

Step 2: Fall Back to Environment Variables

if (logTarget == null) logTarget = System.getenv("VESPA_LOG_TARGET");
if (logService == null) logService = System.getenv("VESPA_SERVICE_NAME");
if (logControlDir == null) logControlDir = System.getenv("VESPA_LOG_CONTROL_DIR");
if (logControlFile == null) logControlFile = System.getenv("VESPA_LOG_CONTROL_FILE");
if (logLevel == null) logLevel = System.getenv("VESPA_LOG_LEVEL");

If a system property was not set, the corresponding environment variable is checked. These are typically set by the Vespa process launcher (vespa-start-services).

Step 3: Apply Defaults

if (logTarget == null) logTarget = "fd:2";
if (logLevel == null) logLevel = "all -debug -spam";

If neither system property nor environment variable is set, hardcoded defaults are used:

Log target defaults to stderr (fd:2)
Log level defaults to all except debug and spam (all -debug -spam)

Step 4: Derive Control File Path

if (logControlFile == null && logControlDir != null && logService != null
    && !logService.equals("") && !logService.equals("-")) {
    logControlFile = logControlDir + "/" + logService + ".logcontrol";
}

If no explicit control file was specified but both a control directory and a valid service name exist, the control file path is derived as <dir>/<service>.logcontrol.

Step 5: Final Service Name Fallback

if (logService == null) logService = System.getProperty("config.id");
if (logService == null) logService = "-";

The service name has an additional fallback to config.id (the Vespa config identity), and then to the literal "-".

Environment Variables

Variable	System Property	Default	Purpose
`VESPA_LOG_TARGET`	`vespa.log.target`	`fd:2`	Log output destination
`VESPA_LOG_LEVEL`	`vespa.log.level`	`all -debug -spam`	Default log levels
`VESPA_SERVICE_NAME`	`vespa.service.name`	`-`	Service identity
`VESPA_LOG_CONTROL_DIR`	`vespa.log.control.dir`	(none)	Control file directory
`VESPA_LOG_CONTROL_FILE`	`vespa.log.control.file`	(derived)	Explicit control file path

Usage Example

public class MyVespaService {
    public static void main(String[] args) {
        // Must be called before any logging
        LogSetup.initVespaLogging("my-vespa-service");

        // Now logging works with Vespa format
        Logger logger = Logger.getLogger(MyVespaService.class.getName());
        logger.info("Service started successfully");
    }
}

Behavior Notes

Double initialization warning: If called twice, a warning is printed to stderr but initialization proceeds. The isInitialized flag is set to true immediately, not after successful completion.
System property side effects: The method sets vespa.service.name and vespa.program.name as system properties, making them available to downstream components like the VespaFormatter.
Delegation to initInternal: The actual handler installation, level controller creation, and JUL configuration happen inside initInternal(), which is called at the end.

Implements Principle

Log Target and Level Configuration

Related Implementations

VespaLevelControllerRepo Constructor -- Creates the level controller using the resolved control file path
VespaLogHandler Constructor -- Installs the handler using the resolved log target and level controller

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment