Control Server

Control Server

logme can run a built-in TCP control server for inspecting and modifying the live logging graph without restarting the process.

The protocol is line-based and is used by the bundled logmectl utility and by logmeweb. The implementation lives in Control.cpp plus the Command/Cmd*.cpp files.

---

What the control server can and cannot do

The control server can:

• show runtime overview and version information
• list existing channels
• inspect one channel in detail
• create, delete, enable, and disable channels
• bind and unbind channels
• set and clear the error channel
• get or set a channel’s filter level
• get or set a channel’s output flags
• add or delete a backend by type
• manage subsystem blocked/allowed policy
• list, enable, disable, and reset trace points
• start, stop, and query on-demand log-source profiling
• expose a restricted read-only view of log files under the logger home directory
• wrap command output as JSON for tools

It does not expose the full JSON configuration language. Runtime control is operational: it is designed for live diagnostics and temporary changes. Full backend configuration, file rotation policy, and persistent setup still belong in configuration.

---

Enabling the server

From JSON configuration

{
  "control": {
    "enable": true,
    "interface": "127.0.0.1",
    "port": 9010
  }
}

Discovery can also be configured under control.discovery:

{
  "control": {
    "enable": true,
    "port": 9010,
    "discovery": {
      "enable": true,
      "namePrefix": "logme-discovery-"
    }
  }
}

Discovery is used by logmeweb to find local processes. It exposes endpoint metadata, not the password.

The current JSON parser does not parse password or TLS material. Do not put pass, password, cert, or key in the JSON control block expecting them to configure the server. Use application code or another explicit runtime setup path for those fields.

From C++ code

Logme::ControlConfig c{};
c.Enable = true;
c.Port = 9010;
c.Interface = /* IPv4 address */;
c.Password = "secret";

logger.StartControlServer(c);

To stop it:

logger.StopControlServer();

---

TLS and authentication

If certificate/key material is configured, the server accepts TLS connections only.

If a password is configured, most commands require a per-connection auth command before normal use.

Client-side helpers:

• logmectl --ssl
• logmectl --pass <password>
• logmeweb HTTPS target mode and password field

---

Using clients

logmectl

logmectl -p <port> [-i <ip>] [--ssl] [--pass <password>] [--format text|json] <command...>

Examples:

logmectl -p 9010 help
logmectl -p 9010 version
logmectl -p 9010 overview
logmectl -p 9010 list
logmectl -p 9010 channel logme
logmectl -p 9010 level --channel logme debug
logmectl -p 9010 flags --channel logme timestamp=utc signature=off
logmectl -p 9010 trace stat '*:*:*'
logmectl -p 9010 logstat status
logmectl -p 9010 logstat outputs --backend FileBackend --sort records --limit 30
logmectl -p 9010 logs --tree
logmectl -p 9010 logs --read logs/app.log 0 65536

logmeweb

logmeweb is the web UI for the same control server. It is useful for browsing channels, subsystem filters, trace points, and manual commands from a browser.

See logmeweb.

---

Command reference

Command names are case-insensitive. Some command arguments, such as channel names and trace point patterns, keep their original case where the specific command needs it.

help

help

Prints the built-in command summary. This is the best first command when checking the control surface exposed by the current build.

version

version

Displays the logme library version and control protocol version:

Logme version: 2.4.17
Control protocol: 1

overview

overview

Displays a runtime logging summary. This command is intended for tools and dashboards that need a quick high-level view of the current process.

list

list

Lists channels. The default channel is shown as <default> in text mode and as an empty string in JSON mode.

channel

channel [name]
channel --create <name>
channel --delete <name>
channel --enable <name>
channel --disable <name>
channel --bind <source> <target>
channel --unbind <name>
channel --error <name>
channel --clear-error

Behavior notes:

• channel without a name inspects the default channel
• deleting the default channel is rejected
• --bind links a source channel to a target channel
• --unbind removes a channel link
• --error sets the error channel
• --clear-error clears the error channel
• inspection output includes status, access count, flags, level, optional link, and attached backends

level

level [--channel <name>] [debug|info|warn|error|critical]

If no channel is given, the default channel is used. Without a level argument, the command reports the current level. Accepted aliases include information, warning, err, and crit.

flags

flags [--channel <name>] [flag[=value] ...]

Without extra arguments, this reports the current bitmask and flag names. With arguments, it updates the channel’s OutputFlags.

Supported runtime flag names include:

• timestamp
• signature
• location
• method
• eol
• errorprefix
• duration
• threadid
• processid
• channel
• highlight
• console
• disablelink
• transition
• subsystem
• format

This runtime surface is slightly wider than some configuration examples because the control command exposes fields needed for live diagnostics.

backend

backend [--channel <name>] --add <type> [options]
backend [--channel <name>] --delete <type>

Type names are case-insensitive and accept common backend type names such as console, debug, file, sharedfile, buffer, and ringbuffer. Short aliases include con, dbg, shared, sfile, buf, ring, and rbuf.

Supported add options include:

--async
--file <path>
--append
--overwrite
--max-size <size>
--daily-rotation
--no-daily-rotation
--max-parts <count>
--timeout <interval>
--policy <policy>
--max-items <count>

Option availability depends on backend type. For example, --async is only supported by ConsoleBackend, --timeout applies to SharedFileBackend, --policy applies to BufferBackend, and --max-items applies to RingBufferBackend.

--max-size uses the same byte-size parser as JSON configuration (64Mb, 1Gb, 512Kb, or a plain byte count). --timeout uses the same interval parser (100ms, 30s, 5min, 1h, or a plain millisecond count).

Runtime backend creation is useful for diagnostics, but it is still not a replacement for full configuration management.

subsystem

subsystem
subsystem --block <name>
subsystem --unblock <name>
subsystem --allow <name>
subsystem --disallow <name>
subsystem --clear-blocked
subsystem --clear-allowed
subsystem --clear
subsystem --check <name>

The command manages two explicit subsystem filter lists:

• blocked subsystems are suppressed
• allowed subsystems form an allow-list when the list is not empty
• blocked subsystems have priority over allowed subsystems

See Subsystems and Message Filtering.

trace

trace [list|stat|stats] [pattern]
trace enable <pattern>
trace disable <pattern>
trace reset [pattern]

Trace point patterns match the file:function:line key and support * and ? wildcards. Matching is case-insensitive.

Examples:

trace list *:*:*
trace enable *WorkerLoop*
trace reset *WorkerLoop*
trace disable *WorkerLoop*

trace list, trace stat, and trace stats list registered trace points and their counters. trace reset without a pattern resets all registered trace point counters.

See Trace Points.

logstat

logstat start
logstat stop
logstat status
logstat reset
logstat top [--sort bytes|records] [--limit count]
logstat channels [--sort bytes|records] [--limit count]
logstat outputs [--sort bytes|records] [--limit count] [--backend type]
logstat backends [--sort bytes|records] [--limit count] [--backend type]
logstat files [--sort written-bytes|batches|errors|dropped-bytes] [--limit count]

logstat profiles the logging subsystem itself. It attributes records and output bytes to exact C and C++ source locations, source channels, destination channels, and built-in backends. The files report additionally shows asynchronous FileBackend batching, successful writes, write errors, and queue drops.

A typical investigation is:

logstat start

# Reproduce the workload.

logstat stop
logstat backends --sort bytes --limit 20
logstat outputs --backend FileBackend --sort bytes --limit 30
logstat outputs --backend FileBackend --sort records --limit 30
logstat files --sort batches --limit 20

Collection is disabled by default. start discards previous counters and starts a new interval. stop preserves the current result for repeated queries. reset clears counters without changing whether collection is active.

See Log Source Profiling for metric definitions, result interpretation, performance characteristics, and a complete diagnostic workflow.

logs

logs --info
logs --tree [relative-path]
logs --tail <relative-file-path> [bytes]
logs --read <relative-file-path> [offset] [bytes]
logs --download <relative-file-path>

The logs command exposes a restricted read-only view of log files below the current logger home directory. It is used by the Logs tab in logmeweb, but it can also be called from logmectl.

Security and scope rules:

• absolute paths are rejected
• .. traversal and paths that resolve outside the home directory are rejected
• only files below home-directory.path are visible
• only files with extensions configured in home-directory.watch-dog.file-extension are visible
• if the configured extension list is empty, the default set is .log .nlb .nlr .b64 .dat .csv

logs --info reports the home directory and allowed extensions.

logs --tree lists folders and matching files. The optional argument is a relative directory under the home directory. Text output uses tab-separated records:

Home directory: /var/log/my-app/
Path: logs
DIR	logs/archive
FILE	logs/app.log	123456	134231118817403736

The file record fields are:

FILE    relative-path    size-bytes    modified-time

The modified time is intended for tools; logmeweb formats it as a human-readable date.

logs --tail returns the last part of a file. The optional byte count is capped by the server.

logs --read returns a bounded range of a file. It starts with a metadata header followed by the file chunk:

LOGMEWEB-RANGE	offset	requested-bytes	file-size

logs --download returns the selected file as base64 with a metadata header:

LOGMEWEB-DOWNLOAD-B64	file-size

The download response is intended for logmeweb and is capped by the server to avoid unexpectedly large transfers through the control interface.

auth

auth <password>

Authenticates the current connection when a password is configured.

format

format json <command...>
format text <command...>
format plain <command...>
format plain/text <command...>

Wraps a single command in the requested response format. logmectl --format json ... uses this automatically.

---

JSON wrapper output

When format json is used, the server returns a wrapper object:

{
  "ok": true,
  "error": null,
  "data": {
    "text": "..."
  }
}

ok is false when the text response starts with error:. In that case, error contains the error message without the error: prefix.

All JSON responses include data.text. Some commands also add parsed fields:

• list -> data.channels
• level -> data.level
• flags -> data.value, data.names
• subsystem -> data.blockedSubsystems, data.allowedSubsystems

Commands that do not have structured parsing yet still return the envelope and data.text.

---

Operational notes

• the control server is excellent for live diagnostics and temporary changes
• it is not a replacement for full configuration management
• use trace points when you want dormant diagnostics that can be activated later
• use logstat when a system profiler shows logging overhead but not the responsible source statements
• use logmeweb when the state is easier to inspect visually than through terminal output

---

Security notes

The implementation is intentionally lightweight. Treat it as an operations/debug interface for trusted environments.

Recommendations:

• bind to loopback unless remote access is truly required
• enable TLS and authentication for any non-local use
• do not expose the control server directly to untrusted networks

See Security.