Skip to main content

Cache And Usage Store

The cache, usage database, decision telemetry, diagnostics, content capture, and retention settings determine what the router stores about requests. These features must remain safe for operations, reports, and audits without persisting secrets or raw governed content unless content capture is explicitly enabled.

This example is a partial subset of config.example.yaml; the shipped sample config is the source of truth.

config.example.yaml
server:
  default_model_group: default
  cache:
    enabled: true
    max_bytes: 134217728
    default_ttl: 15m
  usage_db:
    enabled: true
    driver: sqlite
    path: usage.sqlite
  decision_telemetry:
    enabled: false
    max_candidates: 64
    max_filter_reasons: 256
    record_candidates: true
    record_cache_reasons: true
  diagnostics:
    enabled: true
    retention_days: 30
    store_sanitized_upstream_errors: false
    max_error_bytes: 2048
  content_capture:
    enabled: false
    retention_days: 30
    capture_request: false
    capture_response: false
    capture_tool_calls: false
    capture_images: false
    capture_upstream_errors: false
    capture_headers_allowlist: []
    redact_before_storage: true
    redaction_patterns: []
    max_capture_bytes: 65536
    encryption:
      enabled: false
      kms_key_id: ""

Schema​

server.cache covers eligible deterministic unary responses. Tool-bearing agent requests and image-bearing requests bypass response caching.

usage_db enables relational usage persistence. Usage rows store request-time cost inputs, calculated costs, upstream-reported billed costs where available, latency, throughput, cache status, attempts, fallbacks, caller/project dimensions, and provider/model/dialect dimensions.

decision_telemetry is optional and disabled by default. When enabled, it writes normalized scalar child rows for request shape, bounded candidates, filter reasons, routing decisions, score terms, script/external policy executions, fallback transitions, cache reasons, and non-secret fingerprints.

diagnostics adds safe relational troubleshooting rows. content_capture is a separate governed feature and remains disabled until an operator enables at least one scope. Retention policy is configured under server.retention and defaults to dry-run.

Rollback​

Disable optional telemetry or capture by setting the relevant enabled flag to false, then restart or reload. For governed capture, also verify delete-by-request and purge authorization before rollout and after rollback.

See Usage Reporting, Admin Browser Reports, PII Filtering, Admin Authorization, and Router Configuration.