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

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:

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 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.

---

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 and Control Server.

---

Example project

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