Configuration JSON

JSON Configuration Format

The logme library supports loading its configuration from a JSON file. This page describes the structure, semantics, and validation rules of that JSON configuration.

The JSON-based configuration is an alternative to programmatic configuration from C++ code and is especially useful for long-running services where restarting the process to apply new settings is undesirable.

---

Top-level sections

A JSON configuration may contain the following sections:

• control
• home-directory
• flags
• channels
• subsystems

All sections are optional unless explicitly stated otherwise.

---

home-directory

The home directory defines a base directory on disk that is used to resolve relative log file paths.

The path parameter specifies a directory path valid for the current operating system. Like many other path-related strings in logme, it supports environment variable expansion and special placeholders such as {pid}, {date}, etc.

See Logme::EnvSetVar() and Logme::ProcessTemplate() for details.

Watch-dog

The watch-dog sub-object enables a background thread that monitors the total size of log files on disk. When the configured limit is exceeded, the oldest log files are removed.

Only files with extensions listed in file-extension are considered log files and may be deleted.

Parameters

• enable
  Enables or disables the watchdog thread.

• max-size
  Maximum allowed total size of log files. May be specified as:

  • an integer (bytes), or
  • a string with size suffixes (KB, MB, GB, ...).

  Supported suffixes are defined in ByteSizeValue.cpp.

• check-periodicity
  Interval between size checks. May be specified as:

  • an integer (milliseconds), or
  • a string with time suffixes (sec, min, hours, ...).

  Supported suffixes are defined in TimeIntervalValue.cpp.

• file-extension
  Array of file extensions (including the leading dot) that identify log files.

---

control

The control object configures the built-in management server provided by the library.

The control server allows dynamic runtime reconfiguration using the logmectl utility without restarting the application. This is particularly useful for long-running server processes.

Basic operation

If enable is set to true, the server listens on interface:port.

• interface may be an IP address (0.0.0.0, 127.0.0.1) or localhost
• port specifies the TCP port number

The server implements a telnet-like CLI protocol.

TLS and authentication

The control server can operate over TLS. To enable TLS, a certificate (cert) and private key (key) must be provided in PEM format.

Storing a private key directly in a configuration file is usually discouraged. In practice, TLS is often enabled programmatically using Logger::SetControlCertificate().

When TLS is enabled, the server accepts only TLS connections.

Optional authentication is supported using the AUTH command. If the pass parameter is specified, clients must authenticate before issuing commands.

---

subsystems

The subsystems section controls how the library handles Subsystem IDs (SID) when emitting log records.

Behavior

• If block-listed is true, subsystems listed in list are discarded. This is the default behavior.

• If block-listed is false, output is discarded unless the subsystem is explicitly listed.

After loading the configuration, subsystem rules can be changed dynamically using the following Logger methods:

• ReportSubsystem
• UnreportSubsystem
• SetBlockReportedSubsystems

---

flags

The flags object defines named flag sets that can be referenced by channels.

Each entry has the form:

"name": { "Flag1": value1, "Flag2": value2, ... }

Each flag corresponds to a field of the OutputFlags union (for example Timestamp, Signature, Console, etc.).

Values

• Single-bit flags use boolean values.
• Multi-bit flags may be specified as strings or integers.

Example:

"example": {
  "Timestamp": "local",
  "Console": "cout",
  "Eol": true
}

Supported string constants are defined in Config/ParseFlags.cpp.

Inheritance

Flag sets may inherit from previously defined sets using the Inherit field.

Example:

"flags": {
  "default": {
    "Timestamp": "local",
    "Signature": true,
    "Method": true,
    "ErrorPrefix": true,
    "ThreadID": true,
    "Highlight": true,
    "Eol": true,
    "ThreadTransition": true
  },
  "internal": {
    "Inherit": "default",
    "DisableLink": false
  }
}

---

channels

The channels section defines logging channels.

It is an array of objects, each describing a channel with a given name and configuration.

Channel parameters

• name – channel name
• level – log level filter (debug, info, warn, error, critical)
• flags – name of a flag set defined in flags
• link – name of another channel to link to
  An empty string links to the default channel.
• backends – array of backend definitions
• build, platform – optional conditional parameters

Backends

Each backend object must define the type field. Additional parameters depend on the backend type.

Example:

{
  "type": "FileBackend",
  "append": true,
  "max-size": "16Mb",
  "file": "{%ROOT_LOG}"
}

---

Full JSON Schema

See schema definition below.

---

Complete JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "control": {
      "type": "object",
      "required": ["interface", "port", "enable"],
      "properties": {
        "interface": { "type": "string" },
        "port": { "type": "integer" },
        "enable": { "type": "boolean" },
        "cert": { "type": "string" },
        "key": { "type": "string" },
        "pass": { "type": "string" }
      },
      "additionalProperties": false
    },

    "home-directory": {
      "type": "object",
      "required": ["path", "watch-dog"],
      "properties": {
        "path": { "type": "string" },
        "watch-dog": {
          "type": "object",
          "required": ["enable", "max-size", "check-periodicity", "file-extension"],
          "properties": {
            "enable": { "type": "boolean" },
            "max-size": { "type": "string" },
            "check-periodicity": { "type": "string" },
            "file-extension": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },

    "subsystems": {
      "type": "object",
      "required": ["block-listed", "list"],
      "properties": {
        "block-listed": { "type": "boolean" },
        "list": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    },

    "flags": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "Inherit": { "type": "string" },
          "Timestamp": { "type": ["string", "integer"] },
          "Signature": { "type": "boolean" },
          "Location": { "type": ["string", "integer"] },
          "Method": { "type": "boolean" },
          "Eol": { "type": "boolean" },
          "ErrorPrefix": { "type": "boolean" },
          "Duration": { "type": "boolean" },
          "ThreadID": { "type": "boolean" },
          "ProcessID": { "type": "boolean" },
          "Channel": { "type": "boolean" },
          "Highlight": { "type": "boolean" },
          "Console": { "type": ["string", "integer"] },
          "DisableLink": { "type": "boolean" },
          "ThreadTransition": { "type": "boolean" },
          "Subsystem": { "type": "boolean" }
        },
        "additionalProperties": false
      }
    },

    "channels": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "level", "flags"],
        "properties": {
          "name": { "type": "string" },
          "enable": { "type": "boolean" },
          "level": {
            "type": "string",
            "enum": ["debug", "info", "warn", "error", "critical"]
          },
          "flags": { "type": "string" },
          "link": { "type": "string" },
          "build": {
            "type": "string",
            "enum": ["any", "debug", "release"]
          },
          "platform": {
            "type": "string",
            "enum": ["any", "windows", "linux", "macos"]
          },
          "backends": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["type"],
              "properties": {
                "type": { "type": "string" },
                "build": {
                  "type": "string",
                  "enum": ["any", "debug", "release"]
                },
                "platform": {
                  "type": "string",
                  "enum": ["any", "windows", "linux", "macos"]
                },
                "append": { "type": "boolean" },
                "file": { "type": "string" },
                "max-size": { "type": "string" },
                "max-parts": { "type": "integer", "minimum": 1 },
                "rotation": {
                  "type": "string",
                  "enum": ["daily", "hourly", "size"]
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}