Observability keys: audit.*, logging.*, diagnostics.*, and telemetry.*.

For the full key index and the other top-level config domains, see Configuration reference.

Audit

{
  logging: {
    audit: {
      enabled: true,
      executionIdentity: false,
      messages: "off", // off | direct | all
    },
  },
}

The Gateway records metadata-only audit events for agent runs and tool actions into the shared state database. Message lifecycle metadata is a separate opt-in. The ledger stores identity, timing, tool names, and normalized outcomes, but never prompts, message bodies, tool arguments, results, or raw error text. Message rows do not store raw platform account, conversation, message, and target ids. Run/tool session keys remain available for correlation and can themselves contain platform account or peer ids. Records expire after 30 days and the ledger is capped at 100,000 rows. Query them with apus audit or the audit.activity.list Gateway RPC. See Audit history for the full data model, privacy semantics, and coverage limits.

A root-level audit block is retired; the canonical path is logging.audit. The root config object is strict, so an old top-level audit block is rejected. Run apus doctor --fix to move it to logging.audit.

All three settings apply live. Accepted writes still drain through the same writer, and retained identity contexts remain unchanged. Enabling collection does not backfill activity or add identity to already admitted runs. Message coverage includes accepted inbound messages that reach core dispatch and one terminal row per original logical outbound reply payload that reaches shared durable delivery. Plugin-local and direct-send paths that bypass those shared boundaries are not covered. The bounded background writer is best-effort, not a lossless compliance archive.

Logging

{
  logging: {
    level: "info",
    file: "/tmp/apus/apus.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | json
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

Diagnostics

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf",
      headers: { "x-tenant-id": "my-org" },
      serviceName: "apus-gateway",
      traces: true,
      metrics: true,
      logs: false,
      logsExporter: "otlp",
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: false,
    },

    cacheTrace: {
      enabled: false,
    },
  },
}

Telemetry

{
  telemetry: {
    enabled: false,
    consentedAt: "2026-08-02T12:00:00.000Z",
  },
}

See Usage telemetry and update checks for the complete payload, privacy guarantees, and all opt-out controls.