Skip to main content
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:
LevelDescription
debugVerbose 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.
infoStandard operational events. Startup, configuration loaded, requests processed, authentication outcomes. Recommended for production.
warnConditions that may indicate a problem but do not prevent operation. Deprecated configuration, fallback behavior triggered, approaching resource limits.
errorFailures that prevent an operation from completing. Connection failures, authentication errors, invalid configuration, unhandled exceptions.
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.

​
Output Destinations

Where log output goes depends on how the Orchestrator is deployed:
DeploymentDestinationView With
Linux (systemd)journaldjournalctl -u maverics
Dockerstdout (captured by Docker logging driver)docker logs <container>
Kubernetesstdout (captured by kubelet)kubectl logs <pod>
macOSstdout (foreground process)Terminal output
WindowsWindows 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.
maverics.yaml
logger:
  level: "info"
  jsonOutput: true
  timeFormat: "RFC3339Nano"
  logSessionID: true
  fieldOrdering:
    enabled: true

​
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.
FieldDefaultDescription
http.accessLog.disabledfalseDisable HTTP access logging entirely
http.accessLog.level"info"Access log level — "debug", "info", or "error"
Access log configuration lives under the http top-level key, not as a separate top-level key. See Configuration for the full HTTP section reference.

​
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.
For Console-level audit logs (API actions, config changes, deployments), see Console Audit Logs.

​
Configuration Reference

​
Logger Fields

KeyTypeDefaultRequiredDescription
logger.levelstring"info"NoLog verbosity — "debug", "info", "warn", "error"
logger.timeFormatstring"RFC3339Nano"NoTime format string for log timestamps
logger.logSessionIDbooleanfalseNoInclude the session ID in log entries for request correlation
logger.jsonOutputbooleanfalseNoOutput logs in JSON format (structured logging)
logger.fieldOrdering.enabledbooleanfalseNoOrder log fields consistently across entries
logger.filtersarray[]NoLog message filters for suppressing or routing specific messages
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.

​
Access Log Fields

Access log settings are configured under the http.accessLog key (part of the http section, not a separate top-level key).
KeyTypeDefaultRequiredDescription
http.accessLog.disabledbooleanfalseNoDisable HTTP access logging entirely
http.accessLog.levelstring"info"NoAccess log level — "debug", "info", or "error"
Access log configuration lives under the http top-level key, not as a separate top-level key. See Configuration for the full http section reference.

​
Example

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.

Console Audit Logs

Console-level audit logs for API actions, config changes, and deployments

Monitor and Observe

Step-by-step guide for setting up observability in production

Metrics

OpenTelemetry metrics via OTLP for request, authentication, and runtime data

Traces

OpenTelemetry distributed tracing via OTLP for end-to-end request visibility