Runtime Control

Runtime Control

Runtime control is the ability to inspect and change logging behavior while the application is still running.

This is one of the main differences between logme and logging systems that are fully configured only at startup.
In production, the most useful diagnostic setting is often the one you do not want enabled all the time. Runtime control allows turning it on only when needed.

---

What runtime control is for

Runtime control is useful when a problem appears only in a live process or cannot be reproduced easily under a debugger.

Typical operations are:

• list existing channels
• inspect one channel
• enable or disable a channel
• change a channel level
• add or remove a backend by type
• change output flags
• manage subsystem filtering rules
• list, enable, disable, and reset trace points

These operations affect the live logging graph. The process does not need to be restarted.

---

Control server and logmectl

The runtime interface is provided by the built-in control server.

The bundled logmectl utility connects to this server and sends commands. The web UI logmeweb uses the same control server when a browser-based view is more convenient. The same control surface also exposes the restricted read-only logs command used by the logmeweb Logs tab.

logmectl -p 7791 help
logmectl -p 7791 list
logmectl -p 7791 channel ch1

A typical diagnostic session might look like this:

logmectl -p 7791 channel --enable http
logmectl -p 7791 level --channel http debug
logmectl -p 7791 backend --channel http --add console

This enables a channel, changes its level, and attaches a simple console backend without restarting the application.

See logmectl for command-line usage, logmeweb for the web UI, and Control Server for the protocol and command reference.

---

Channels and subsystems are different

Runtime channel commands operate on channels.

A channel is the main logging entity. It can be enabled or disabled and has a level.

Subsystems are classification tags used for filtering.
They are not the same thing as channels and should not be described as channels.

For subsystem-related diagnostics, use subsystem commands:

logmectl -p 7791 subsystem --block s2
logmectl -p 7791 subsystem --unblock s2
logmectl -p 7791 subsystem --allow s1
logmectl -p 7791 subsystem --disallow s1
logmectl -p 7791 subsystem --clear-blocked
logmectl -p 7791 subsystem --clear-allowed
logmectl -p 7791 subsystem --clear
logmectl -p 7791 subsystem --check s1

The blocked list has priority. When the allowed list is not empty, only listed subsystems are logged, unless they are also blocked. Messages without a subsystem are not affected by subsystem filtering.

See Subsystems and Message Filtering.

---

Trace points

Trace points are runtime-controlled diagnostic points compiled into the application. They count hits even while disabled and start emitting normal log records only after they are enabled through the control server.

A typical session is:

logmectl -p 7791 trace stat '*WorkerLoop*'
logmectl -p 7791 trace enable '*WorkerLoop*'
# reproduce the problem
logmectl -p 7791 trace stat '*WorkerLoop*'
logmectl -p 7791 trace disable '*WorkerLoop*'

This is different from changing a channel level. Channel commands change routing and filtering for existing log records. Trace point commands activate or deactivate specific dormant call sites identified by file:function:line patterns.

See Trace Points.

---

Startup environment control

Runtime control commands can also be applied during startup from environment variables, but only when the application explicitly calls Logger::ApplyEnvironmentControl(). logme does not read LOGME_CONTROL automatically.

Example environment value:

LOGME_CONTROL="channel --enable http; level --channel http debug; trace enable *WorkerLoop*"

The string is split into separate commands by ;, and each command is executed through the policy-aware control API. The default environment policy is ControlPolicy::Safe().

This is useful for service managers, containers, CI jobs, and diagnostic launch scripts where a process should start with temporary logging overrides without changing its normal JSON configuration.

See Environment Control and Control Policies.

---

Policy-aware control calls

Application code can execute control commands with an explicit ControlPolicy:

std::string response = Logme::Instance->Control(
  "level --channel net debug",
  Logme::ControlPolicy::Safe()
);

The old Control(command) overload remains available and uses full control for compatibility. Use the policy-aware overload when commands come from a restricted source such as environment variables, a UI, a plugin, or a custom management endpoint.

See Control Policies.

---

Configuration reload vs runtime control

JSON configuration and runtime control solve different problems.

Configuration is authoritative. It describes the logging graph that should be built when configuration is loaded. It can specify detailed backend settings such as file names, rotation, buffer sizes, and other backend-specific options.

Runtime control is operational. It is meant for live diagnostics and quick changes. It can add a backend by type, change levels, or adjust flags, but it is not a replacement for the full JSON configuration language.

For example, adding a file backend through the control server creates it with default settings. Detailed file paths and rotation policy belong in configuration.

See Configuration and Configuration JSON.

---

Security

The control server can be protected with TLS and a password.

If TLS is configured, logmectl must connect with --ssl.
If a password is configured, pass it with --pass:

logmectl --ip 192.168.1.10 --port 7791 --ssl --pass secret help

Runtime control is powerful and should be exposed only where it is safe to do so.

See Security, Control Server, and logmeweb.

---

Example project

The DynamicControl example demonstrates a program that keeps running while logmectl changes channels, backends, and subsystem filters from another console.