Implementation:Vespa engine Vespa VespaLevelControllerRepo Constructor

VespaLevelControllerRepo Constructor

Logging Observability

API Signature

VespaLevelControllerRepo(String logCtlFn, String logLevel, String applicationPrefix)

Source Location

• File: vespalog/src/main/java/com/yahoo/log/VespaLevelControllerRepo.java
• Lines: L58-63
• Class: class VespaLevelControllerRepo implements LevelControllerRepo
• Package: com.yahoo.log

Description

The VespaLevelControllerRepo constructor initializes the memory-mapped level control subsystem. It stores the control file path and application prefix, creates a default level controller from the level string, and then opens (or creates) the control file via openCtlFile().

This class implements LevelControllerRepo, which provides the interface for looking up per-component level controllers. The repository is the bridge between the memory-mapped control file on disk and the level-checking logic used by the VespaLogHandler.

Key Fields

Field	Type	Purpose
ctlFile	RandomAccessFile	Handle to the log control file opened in read-write mode
mapBuf	MappedByteBuffer	Memory-mapped view of the control file contents
levelControllerRepo	MappedLevelControllerRepo	Repository backed by the mapped buffer for per-component lookups
logControlFilename	String	Absolute path to the log control file
appPrefix	String	Application prefix prepended to component names in the control file
defaultLevelCtrl	DefaultLevelController	Fallback level controller used when no per-component entry exists

Constants

Constant	Value	Purpose
maxPrefix	64	Maximum length of the application prefix in the control file
CFHEADER	"Vespa log control file version 1\n"	Header string written to and validated in the control file
numLevels	8	Number of log levels supported (fatal, error, warning, config, info, event, debug, spam)

Parameters

Parameter	Type	Description
logCtlFn	String	Absolute path to the log control file. Derived from VESPA_LOG_CONTROL_DIR and VESPA_SERVICE_NAME, or set explicitly via VESPA_LOG_CONTROL_FILE.
logLevel	String	Default log level string (e.g., "all -debug -spam"). Used by the DefaultLevelController for components without explicit entries.
applicationPrefix	String	The application prefix (e.g., the program name) written to the control file header and used to scope component entries.

Constructor Source

VespaLevelControllerRepo(String logCtlFn, String logLevel, String applicationPrefix) {
    this.logControlFilename = logCtlFn;
    this.appPrefix = applicationPrefix;
    defaultLevelCtrl = new DefaultLevelController(logLevel);
    openCtlFile();
}

Initialization Sequence

Step 1: Store Configuration

this.logControlFilename = logCtlFn;
this.appPrefix = applicationPrefix;

The control file path and application prefix are stored for use by openCtlFile() and subsequent component registration.

Step 2: Create Default Level Controller

defaultLevelCtrl = new DefaultLevelController(logLevel);

The DefaultLevelController parses the level string (e.g., "all -debug -spam") and creates a level controller that can answer shouldLog(level) queries. This serves as the fallback for any component that does not have an explicit entry in the control file.

Step 3: Open the Control File

openCtlFile();

The openCtlFile() method performs the heavy lifting:

1. Opens (or creates) the file at logControlFilename using RandomAccessFile in "rw" mode.
2. If the file is newly created, writes the CFHEADER and the application prefix.
3. If the file exists, validates the header string.
4. Maps the file into memory via FileChannel.map(MapMode.READ_WRITE, ...).
5. Creates a MappedLevelControllerRepo from the MappedByteBuffer.

LevelControllerRepo Interface

The class implements the LevelControllerRepo interface, which provides:

public interface LevelControllerRepo {
    LevelController getLevelController(String component);
    void close();
}

When getLevelController(component) is called:

1. It first checks the MappedLevelControllerRepo for an existing entry.
2. If no entry exists, it creates a new entry in the memory-mapped file for that component.
3. If the control file is not available, it returns the defaultLevelCtrl.

Error Handling

• If the control file cannot be opened or created, the repository falls back to using only the defaultLevelCtrl. Runtime level control is disabled in this case.
• If the file header does not match CFHEADER, the file is treated as corrupt and a warning is logged.

Usage Context

The constructor is called from within LogSetup.initInternal() after the control file path and log level have been resolved:

// Inside LogSetup.initInternal():
LevelControllerRepo repo;
if (logControlFile != null) {
    repo = new VespaLevelControllerRepo(logControlFile, logLevel, programName);
} else {
    repo = new DefaultLevelControllerRepo(logLevel);
}

Implements Principle

Control File Initialization

Related Implementations

• LogSetup.initVespaLogging -- Resolves the control file path and calls this constructor
• vespa-logctl -- The CLI tool that reads and modifies the same control file at runtime

Related Pages

• Principle:Vespa_engine_Vespa_Control_File_Initialization
• Environment:Vespa_engine_Vespa_POSIX_Mmap_Log_Control
• Heuristic:Vespa_engine_Vespa_Log_Level_Inheritance_Polling