Environment Control

Environment Control

Environment control allows an application to apply logme control commands from process environment variables during startup.

This is not automatic configuration. logme never reads LOGME_CONTROL by itself. The application must explicitly call Logger::ApplyEnvironmentControl(). If that call is absent, environment variables have no effect.

This design is intentional. Environment variables are often controlled by service managers, test runners, shells, containers, or launch scripts. They are useful for diagnostics, but they should not silently change logging behavior unless the application has opted in.

---

Basic idea

Environment control reuses the normal control-command language:

LOGME_CONTROL="channel --enable raw; level --channel raw debug; trace enable Raw:*:*"

The value is split into separate commands by semicolon (;). Each command is then executed through the policy-aware control API.

The existing parser for one control command is not changed. Environment control only adds a small outer splitter for a group of commands.

---

Public API

#include <Logme/Logme.h>
#include <Logme/EnvironmentControl.h>

Logme::EnvironmentControlOptions options;
options.Policy = Logme::ControlPolicy::Safe();
options.ErrorMode = Logme::EnvironmentControlErrorMode::CONTINUE_ON_ERROR;

bool ok = Logme::Instance->ApplyEnvironmentControl(options);

Default options are intentionally conservative:

• Prefix = "LOGME"
• Policy = ControlPolicy::Safe()
• ErrorMode = CONTINUE_ON_ERROR
• MaxVariables = 32
• MaxCommands = 64
• MaxVariableLength = 8192
• MaxCommandLength = 2048
• MaxTotalLength = 32768
• LogAppliedCommands = true

---

Environment variable names

With the default prefix, logme reads:

LOGME_CONTROL
LOGME_CONTROL_1
LOGME_CONTROL_2
...

LOGME_CONTROL is processed first. Numbered variables are then processed in increasing order.

Each variable may contain one command or several commands separated by ;:

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

The prefix can be changed when several products or libraries in the same process need separate namespaces:

Logme::EnvironmentControlOptions options;
options.Prefix = "MYAPP_LOGME";

Logme::Instance->ApplyEnvironmentControl(options);

That reads MYAPP_LOGME_CONTROL, MYAPP_LOGME_CONTROL_1, and so on.

---

Error modes

EnvironmentControlErrorMode controls how ApplyEnvironmentControl() reacts to failed or rejected commands.

IGNORE_ERRORS

Errors are logged to CHINT, processing continues, and the method returns true.

Use this only when environment control is purely best-effort diagnostics.

CONTINUE_ON_ERROR

Errors are logged to CHINT, processing continues, and the method returns false if at least one command failed or was rejected.

This is the default.

STOP_ON_ERROR

The first error is logged to CHINT, processing stops, and the method returns false.

Environment control is not transactional. Commands already applied before the failure are not rolled back.

---

Policy

Environment control does not have its own security model. It executes commands through the policy-aware control API.

The default policy is ControlPolicy::Safe(), which allows diagnostic changes such as levels, flags, trace points, and subsystem filters, but rejects backend changes, file backends, channel creation/deletion, channel routing changes, error-channel changes, logs, and extension commands.

For details, see Control Policies.

---

Example

#include <Logme/Logme.h>
#include <Logme/EnvironmentControl.h>

LOGME_CHANNEL(CHNET, "net");

int main()
{
  Logme::CreateDefaultLogger();

  Logme::EnvironmentControlOptions options;
  options.Policy = Logme::ControlPolicy::Safe();
  options.ErrorMode = Logme::EnvironmentControlErrorMode::CONTINUE_ON_ERROR;

  bool ok = Logme::Instance->ApplyEnvironmentControl(options);
  if (!ok)
  {
    LogmeW("one or more environment control commands failed");
  }

  LogmeD(CHNET, "debug diagnostics controlled by environment");
  LogmeI(CHNET, "normal network message");

  return 0;
}

Run with:

LOGME_CONTROL="channel --enable net; level --channel net debug" ./app

---

Security notes

• Environment control is disabled unless the application calls ApplyEnvironmentControl().
• Do not add a JSON setting that silently enables environment control. The application should opt in from code.
• Prefer ControlPolicy::Safe() for production startup overrides.
• Use Diagnostic() or Full() only when the process environment is trusted.
• Environment commands and errors are logged through CHINT like other internal logme diagnostics.
• The full command text may contain paths or operational details, so code and documentation should avoid printing it at high log levels unless needed for diagnostics.