> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

The Orchestrator uses a single structured logger for all runtime output. Every event -- startup, configuration loading, connector initialization, route matching, authentication decisions, authorization decisions, session operations, health checks, and errors -- flows through this logger.

## Log Levels

The Orchestrator supports four log levels, from most verbose to least:

| Level   | Description                                                                                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `debug` | Verbose diagnostic output for troubleshooting. Includes internal state, request details, and processing steps. Use only when actively debugging -- debug logging is verbose and can impact performance. |
| `info`  | Standard operational events. Startup, configuration loaded, requests processed, authentication outcomes. Recommended for production.                                                                    |
| `warn`  | Conditions that may indicate a problem but do not prevent operation. Deprecated configuration, fallback behavior triggered, approaching resource limits.                                                |
| `error` | Failures that prevent an operation from completing. Connection failures, authentication errors, invalid configuration, unhandled exceptions.                                                            |

<Note>
  The `-verbose` CLI flag or `MAVERICS_DEBUG_MODE=true` environment variable sets the log level to `"debug"` at startup, overriding the `logger.level` value in the configuration file.
</Note>

## Output Destinations

Where log output goes depends on how the Orchestrator is deployed:

| Deployment      | Destination                                   | View With                 |
| --------------- | --------------------------------------------- | ------------------------- |
| Linux (systemd) | journald                                      | `journalctl -u maverics`  |
| Docker          | stdout (captured by Docker logging driver)    | `docker logs <container>` |
| Kubernetes      | stdout (captured by kubelet)                  | `kubectl logs <pod>`      |
| macOS           | stdout (foreground process)                   | Terminal output           |
| Windows         | Windows Event Log (when running as a service) | Event Viewer              |

## Structured JSON Output

Enable `jsonOutput: true` to produce machine-parseable JSON log entries. This is recommended for production deployments where logs are ingested by aggregation systems like Elasticsearch, Loki, or Splunk.

```yaml maverics.yaml theme={null}
logger:
  level: "info"
  jsonOutput: true
  timeFormat: "RFC3339Nano"
  logSessionID: true
  fieldOrdering:
    enabled: true
```

## Deployment Correlation

Starting in **v2026.03.3**, every log entry includes a `soid` (Secure Orchestrator ID) field -- a 10-character identifier that uniquely identifies each Orchestrator instance in a deployment. The identifier is stable across restarts on the same machine as long as the Orchestrator points to the same deployment in the Console (or the same local config file path when not using the Console). Changing the deployment or config path produces a new identifier.

In multi-instance deployments (load-balanced, clustered, or multi-region), use the `soid` value to:

* **Filter logs** to a single Orchestrator instance in your log aggregation system
* **Correlate events** across restarts without losing continuity
* **Distinguish instances** that share the same configuration but run on different machines

The `soid` value is automatically derived at startup -- no configuration is required.

<Note>
  In containerized deployments, each container receives a unique `soid` by default because containers have ephemeral machine identities. To maintain a consistent `soid` across container restarts (for example, in singleton deployment scenarios), mount a stable `/etc/machine-id` file into the container. See [Docker — Stable Deployment Identity](/reference/orchestrator/installation/docker#stable-deployment-identity) for details.
</Note>

## Session ID Correlation

Enable `logSessionID: true` to include the session identifier in each log entry. This allows you to correlate all log entries across a user's session -- from initial authentication through subsequent requests -- making it straightforward to trace a single user's activity through the system.

## Field Ordering

Enable `fieldOrdering.enabled: true` for consistent log field order across all entries. When enabled, log fields appear in the same sequence in every entry, making logs easier to scan visually and parse with tools that rely on field position.

## Log Filters

The `logger.filters` configuration allows suppressing or routing specific log messages. Filters can match on message content, log level, or other attributes to control which log entries are emitted.

## Access Logs

HTTP access logs are separate from operational logs and are configured under the `http.accessLog` key. Access logs record every HTTP request handled by the Orchestrator, including method, path, status code, and response time.

| Field                     | Default  | Description                                           |
| ------------------------- | -------- | ----------------------------------------------------- |
| `http.accessLog.disabled` | `false`  | Disable HTTP access logging entirely                  |
| `http.accessLog.level`    | `"info"` | Access log level -- `"debug"`, `"info"`, or `"error"` |

<Note>
  Access log configuration lives under the `http` top-level key, not as a separate top-level key. See [Configuration](/reference/orchestrator/configuration#http-server-configuration) for the full HTTP section reference.
</Note>

## Audit and Auth Event Logs

Authentication and authorization decisions are emitted as structured log entries by the Orchestrator. These entries include:

* **Event type** -- authentication or authorization
* **Timestamp** -- when the event occurred
* **User identifier** -- the authenticated user (when available)
* **Application name** -- the app that processed the request
* **Decision outcome** -- allow or deny
* **Connector or policy involved** -- which identity connector or authorization policy was evaluated

These structured log entries can be forwarded to SIEM systems (Splunk, Elasticsearch, Microsoft Sentinel) for audit retention, compliance reporting, and security monitoring.

<Info>
  For Console-level audit logs (API actions, config changes, deployments), see [Console Audit Logs](/reference/console/audit-logs).
</Info>

## Configuration Reference

### Logger Fields

| Key                            | Type    | Default         | Required | Description                                                      |
| ------------------------------ | ------- | --------------- | -------- | ---------------------------------------------------------------- |
| `logger.level`                 | string  | `"info"`        | No       | Log verbosity -- `"debug"`, `"info"`, `"warn"`, `"error"`        |
| `logger.timeFormat`            | string  | `"RFC3339Nano"` | No       | Time format string for log timestamps                            |
| `logger.logSessionID`          | boolean | `false`         | No       | Include the session ID in log entries for request correlation    |
| `logger.jsonOutput`            | boolean | `false`         | No       | Output logs in JSON format (structured logging)                  |
| `logger.fieldOrdering.enabled` | boolean | `false`         | No       | Order log fields consistently across entries                     |
| `logger.filters`               | array   | `[]`            | No       | Log message filters for suppressing or routing specific messages |

<Note>
  The `-verbose` CLI flag or `MAVERICS_DEBUG_MODE=true` environment variable sets the log level to `"debug"` at startup, overriding the `logger.level` value in the configuration file.
</Note>

### Access Log Fields

Access log settings are configured under the `http.accessLog` key (part of the `http` section, not a separate top-level key).

| Key                       | Type    | Default  | Required | Description                                           |
| ------------------------- | ------- | -------- | -------- | ----------------------------------------------------- |
| `http.accessLog.disabled` | boolean | `false`  | No       | Disable HTTP access logging entirely                  |
| `http.accessLog.level`    | string  | `"info"` | No       | Access log level -- `"debug"`, `"info"`, or `"error"` |

<Note>
  Access log configuration lives under the `http` top-level key, not as a separate top-level key. See [Configuration](/reference/orchestrator/configuration#http-server-configuration) for the full `http` section reference.
</Note>

### Example

<Tabs>
  <Tab title="Console UI">
    <Info>
      **Console UI documentation is coming soon.** This section will walk you
      through configuring this component using the Maverics Console's visual
      interface, including step-by-step screenshots and field descriptions.
    </Info>
  </Tab>

  <Tab title="Configuration">
    ```yaml maverics.yaml theme={null}
    logger:
      level: "info"
      jsonOutput: true
      timeFormat: "RFC3339Nano"
      logSessionID: false

    http:
      accessLog:
        disabled: false
        level: "info"
    ```
  </Tab>
</Tabs>

## Related Pages

<CardGroup cols={2}>
  <Card title="Console Audit Logs" icon="scroll" href="/reference/console/audit-logs">
    Console-level audit logs for API actions, config changes, and deployments
  </Card>

  <Card title="Monitor and Observe" icon="eye" href="/guides/operations/monitor">
    Step-by-step guide for setting up observability in production
  </Card>

  <Card title="Metrics" icon="chart-line" href="/reference/orchestrator/telemetry/metrics">
    OpenTelemetry metrics via OTLP for request, authentication, and runtime data
  </Card>

  <Card title="Traces" icon="diagram-project" href="/reference/orchestrator/telemetry/traces">
    OpenTelemetry distributed tracing via OTLP for end-to-end request visibility
  </Card>
</CardGroup>