Environment:Vespa engine Vespa POSIX Mmap Log Control

Knowledge Sources	Vespa Engine control-file.cpp VespaLevelControllerRepo.java
Domains	Infrastructure, Logging
Last Updated	2026-02-09 00:00 GMT

Overview

POSIX-compliant environment with memory-mapped file support for shared log level control between Java and C++ processes.

Description

This environment provides the memory-mapped file I/O context required by the Vespa logging framework. Log level control files are shared between Java (via MappedByteBuffer) and C++ (via POSIX mmap) processes on the same host. The control file format stores 8 log levels per component as 4-byte integers (" ON"/"\ OFF" literals). The C++ side pre-allocates anonymous mmap regions and overlays the file using MAP_FIXED for stable addresses.

Usage

Use this environment for all log level control operations. It is the mandatory prerequisite for the VespaLevelControllerRepo_Constructor, VespaLogHandler_Constructor, and Vespa_Logctl implementations. Any Vespa process that reads or writes log control files requires POSIX mmap support.

System Requirements

Category	Requirement	Notes
OS	POSIX-compliant (Linux)	Requires `mmap`, `msync`, `MAP_FIXED`
Filesystem	Shared filesystem	Control files must be accessible by all Vespa processes
Disk	Minimal (200KB max per control file)	Hard limit in C++ implementation

Dependencies

System Packages

POSIX mmap support (sys/mman.h)
Java NIO (MappedByteBuffer for Java processes)

Runtime Configuration

Control file directory: writable by all Vespa services
File format: "Vespa log control file version 1" header
Max file size: 200KB
Max application prefix: 64 characters

Credentials

The following environment variables control log file placement:

VESPA_LOG_CONTROL_DIR: Directory for .logcontrol files
VESPA_LOG_CONTROL_FILE: Explicit control file path (overrides dir+service)
VESPA_SERVICE_NAME: Service identifier (used in control file path)
VESPA_LOG_TARGET: Log output target (fd:2 for stderr, file:/path for file)
VESPA_LOG_LEVEL: Default log level string (default: all -debug -spam)

Quick Install

# POSIX mmap is available on all Linux systems
# Ensure the log control directory exists and is writable:
mkdir -p /opt/vespa/var/db/vespa/logcontrol
chmod 775 /opt/vespa/var/db/vespa/logcontrol

Code Evidence

C++ mmap pre-allocation from control-file.cpp:

static const int _maxMapSize = 200000;  // Max 200KB control file

void ControlFile::ensureMapping() {
    int flags = MAP_PRIVATE | MAP_ANON;
    size_t length = pageAlign(_maxMapSize + 1);
    void *addr = mmap(nullptr, length, prot, flags, fd, 0);
    // Then overlay actual file using MAP_FIXED for stable address
}

Java MappedByteBuffer from VespaLevelControllerRepo.java:58-63:

private RandomAccessFile ctlFile;
private MappedByteBuffer mapBuf;
private static final int maxPrefix = 64;
private static final String CFHEADER = "Vespa log control file version 1\n";

Level encoding from MappedLevelController.java:

private static final int ONVAL  = 0x20204f4e;  // "  ON" in ASCII/big-endian
private static final int OFFVAL = 0x204f4646;  // " OFF" in ASCII/big-endian

Common Errors

Error Message	Cause	Solution
`msync of log control file failed`	Filesystem issue	Check disk space and permissions on control file directory
`runtime log-control is therefore disabled`	Neither VESPA_LOG_CONTROL_FILE nor VESPA_LOG_CONTROL_DIR + VESPA_SERVICE_NAME set	Set `VESPA_LOG_CONTROL_DIR` and `VESPA_SERVICE_NAME`
Stale log levels	Control file not synced	C++ uses MS_SYNC for critical updates; check filesystem caching

Compatibility Notes

Java side: Uses READ_ONLY MappedByteBuffer; changes written by C++ are automatically visible via OS kernel.
C++ side: Uses MAP_SHARED for file writes visible to Java; MAP_PRIVATE|MAP_ANON for pre-allocation.
4-byte alignment: Required for level access (atomic 32-bit reads across processes).
200KB limit: Hard maximum for control files in the C++ implementation.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment