Skip to main content

​
Debugging Oxygen CLI & Viewing Logs

Oxygen provides detailed logs to help you debug issues and understand what is happening under the hood.

​
Enable Debug Logging

By default the CLI logs warnings and errors only. For more detail, set OXY_DEBUG=true (a shortcut for OXY_LOG_LEVEL=debug) when running any Oxygen CLI command:
OXY_LOG_LEVEL accepts the usual levels (error, warn, info, debug, trace) and keeps noisy framework libraries quiet. For full control, set RUST_LOG instead — it takes a standard tracing filter and overrides both.

​
Where to Find Logs

  • In your terminal — every command, including oxy serve and oxy start, writes logs to stderr, so program output on stdout stays pipeable.
  • In a log file — local runs also write to a daily log file, oxy.YYYY-MM-DD.log, in the Oxygen state directory:
    Set OXY_STATE_DIR to use a different directory. The last 7 daily files are kept; older ones are deleted automatically.
In containers on Kubernetes (or when OXY_LOG_FORMAT=json is set), Oxygen writes one JSON object per line to stderr for your log aggregator and skips the log file. Set OXY_LOG_FORMAT=text to force the human-readable format.

​
Tips

  • If you encounter an error or unexpected behavior, check the log file above for details.
  • For persistent issues, run with OXY_DEBUG=true to get more context.