Interaction Logs¶

Interaction logging records individual LLM requests that pass through the gateway: the caller, the model used, cost and token counts, timing, etc., and optionally the full request and response bodies. The records are shown in the Interaction Logs page of the admin portal and can be exported as CSV or ZIP.

The feature is configured under the top-level interaction_log key. It is disabled by default.

Note: Infra values for the body storage backend (account URL, subscription, resource group) are not set here. They come from environment variables so they never leak through the config API. See the LLMGW container env vars.

Example¶

interaction_log:
  enabled: true
  entity_enabled_default: true
  entity_sensitive_default: false
  entity_log_body_default: true
  metadata_retention_days: 90
  export:
    max_rows_without_body: 30000
    max_rows_with_body: 10000
    max_concurrent: 2
    body_download_concurrency: 4
  body:
    enabled: true
    retention_days: 30
    container: interaction-logs
    storage:
      type: dir
      base_dir: ./interaction-logs

Top-level options¶

enabled (bool, default false) — Turn the whole feature on or off. When false, no requests are logged.
entity_enabled_default (bool, default false) — Default for whether requests tied to an entity are logged. Applied to entities that have no explicit per-entity override.
entity_sensitive_default (bool, default true) — Default for whether an entity's logs are marked sensitive. Applied to entities that have no explicit per-entity override.
entity_log_body_default (bool, default false) — Default for whether request/response bodies are stored for an entity. Applied to entities that have no explicit per-entity override.
metadata_retention_days (int, default 90, range 1–3650) — How long metadata rows are kept in the database before they are deleted.

Per-entity overrides¶

The entity_*_default values are deployment-wide defaults only. Each entity (for example a project) can override the three settings — logging enabled, sensitive, and log body — independently. An entity that has no override inherits the matching default.

Overrides are set in the admin portal, not in this file: open a project and use the Interaction Logging tab. Each control is a tri-state — Inherit (use the default), Enabled, or Disabled. See Interaction Logging tab.

This split keeps deployment-wide policy in the config file while letting project owners tune logging for their own project without a redeploy.

Export¶

Row caps and concurrency for the export endpoints. The two row caps differ because the ZIP export downloads bodies per row, so it gets a lower cap.

max_rows_without_body (int, default 30000) — Row cap for the CSV (metadata-only) export.
max_rows_with_body (int, default 10000) — Row cap for the ZIP (with bodies) export.
max_concurrent (int, default 2, min 1) — How many exports can run at the same time. Extra requests are rejected.
body_download_concurrency (int, default 4, min 1) — How many body downloads run in parallel within a single ZIP export.

Body storage¶

Controls whether request/response bodies are stored and where.

enabled (bool, default false) — Turn body storage on or off. When false, only metadata is logged.
retention_days (int, default 30, range 1–3650) — How long bodies are kept. Must be less than or equal to metadata_retention_days, because bodies are referenced from metadata rows.
container (str, default interaction-logs) — Namespace for bodies: a blob container for Azure, a subdirectory for the local backend.
storage — The backend that stores the bodies. Selected by the type field.
- Local directory
```
storage:
  type: dir
  base_dir: ./interaction-logs
```
Where base_dir (str, default: ./interaction-logs) — Root directory for stored bodies.

Bodies stored on local disk are not cleaned up automatically. Manage retention yourself.
- Azure Blob
```
storage:
  type: azure_blob
```
No fields are set here. The account URL, subscription, and resource group come from environment variables. See LLMGW container env vars.

Azure lifecycle management deletes blobs after retention_days.