Jump to content

Connect Leeroopedia MCP: Equip your AI agents to search best practices, build plans, verify code, diagnose failures, and look up hyperparameter defaults.

Principle:Vespa engine Vespa Log Target and Level Configuration

From Leeroopedia


Log Target and Level Configuration

Logging Observability

Overview

Log target and level configuration establishes the logging infrastructure at process startup in Vespa. It determines where logs are routed (stderr, file, or stdout), which log levels are active, and how runtime level control is configured. This is a one-time initialization that must happen before any logging calls are made by the application.

The initialization is the entry point of Vespa's entire logging framework. Without it, all log output would fall through to the default Java Util Logging (JUL) behavior, bypassing Vespa's structured format, level control files, and centralized log aggregation.

Motivation

Vespa runs as a distributed system composed of many Java and C++ processes across potentially hundreds of nodes. Each process must:

  1. Output logs in a uniform, tab-delimited format that can be parsed by centralized log collectors.
  2. Route log output to a configurable target -- typically a file or file descriptor -- so that log aggregation infrastructure can collect it.
  3. Respect per-component log level settings that can be changed at runtime without restarting the process.
  4. Handle the case where no explicit configuration is provided by falling back to sensible defaults.

Without a dedicated initialization step, each component would need to configure logging independently, leading to inconsistent formats, missed log output, and inability to control verbosity at runtime.

Core Concepts

Log Target

The log target specifies where log output is written. Vespa supports several target types:

Target Prefix Description Example
fd: File descriptor (0=stdin, 1=stdout, 2=stderr) fd:2 (default)
file: Direct file path file:/var/log/vespa/vespa.log
(none) Treated as file path /var/log/vespa/vespa.log

The default target is fd:2 (stderr), which ensures that even unconfigured processes produce visible log output.

Log Level

The log level string is a space-separated list of level specifiers that controls which levels are enabled by default. The syntax supports both inclusion and exclusion: 

all -debug -spam       # Enable all levels except debug and spam (default)
all                    # Enable everything including debug and spam
fatal error warning    # Only enable these three levels

Vespa defines the following log levels, ordered by severity:

Level Numeric Value Typical Use
fatal Highest Unrecoverable errors
error High Errors requiring attention
warning Medium-High Potential problems
config Medium Configuration changes
info Medium-Low Normal operational messages
event Low Structured events for metrics
debug Lower Development diagnostics
spam Lowest Extremely verbose tracing

Configuration Precedence

The initialization method follows a strict precedence order when resolving configuration values:

  1. Java system properties (e.g., -Dvespa.log.target=...) -- highest priority
  2. Environment variables (e.g., VESPA_LOG_TARGET) -- used when system properties are not set
  3. Hardcoded defaults -- used when neither system properties nor environment variables are set

This design allows process launchers to set environment variables as defaults while still permitting individual processes to override via system properties.

Control File Path

The log control file path is derived from the combination of VESPA_LOG_CONTROL_DIR and VESPA_SERVICE_NAME when no explicit control file is specified: 

<logControlDir>/<serviceName>.logcontrol

This file is a memory-mapped binary file used for runtime level control. If neither a control directory nor a service name is available, runtime level control is disabled and only the default level string applies.

Environment Variables

Variable System Property Default Purpose
VESPA_LOG_TARGET vespa.log.target fd:2 Where to write log output
VESPA_LOG_LEVEL vespa.log.level all -debug -spam Default active log levels
VESPA_SERVICE_NAME vespa.service.name - Service identity in log lines
VESPA_LOG_CONTROL_DIR vespa.log.control.dir (none) Directory for log control files
VESPA_LOG_CONTROL_FILE vespa.log.control.file (derived) Explicit control file path

Design Constraints

  • Single initialization: The initVespaLogging method must be called exactly once. A second call produces a warning on stderr but still proceeds, as some legacy code paths may trigger it.
  • Program name is mandatory: A null or empty program name causes a RuntimeException, since the program name is embedded in every log line and in the control file.
  • Service name fallback: If no service name is provided, the system falls back to config.id (the Vespa config server identity) and then to "-".
  • Thread safety: Initialization sets shared static state and must complete before any concurrent logging begins. In practice, this is ensured by calling it early in main().

Interaction with Other Components

The log target and level configuration phase feeds into several downstream components:

  • Control File Initialization: The resolved control file path is used to create or open the memory-mapped level control file.
  • Logger Handler Installation: The resolved log target and level controller are used to construct the VespaLogHandler.
  • Runtime Level Control: The control file created during initialization is the shared-memory channel that vespa-logctl uses to change levels.

References

Related Pages

Implemented By

Page Connections

Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment
Retrieved from "https://leeroopedia.com/index.php?title=Principle:Vespa_engine_Vespa_Log_Target_and_Level_Configuration&oldid=24396"