Skip to content

Audit Trail & Usage Tracking

AKKO provides a comprehensive audit trail and usage tracking system that gives administrators full visibility into platform activity. This is essential for compliance (GDPR, SOC 2, ISO 27001) and cost allocation.

What Is Tracked

Source Data Collected Collection Method
Trino User, SQL query, tables touched, rows scanned, duration, status Event listener -> stdout -> log shipper -> logs layer
LiteLLM User, model, tokens consumed, latency, cost estimate Prometheus metrics + JSON logs -> logs layer
JupyterHub User, server spawn/stop, kernel, session duration, memory Prometheus metrics (jupyterhub_*)
object storage Bucket usage, object count, storage per bucket Prometheus metrics (minio_bucket_*)
Keycloak Login, logout, password changes, registration, active sessions Event listeners (jboss-logging, metrics-listener)
OPA Authorization decisions (allow/deny), column masking, row filters Decision logs -> logs layer
PostgreSQL Database sizes per instance Prometheus metrics (pg_database_size_bytes)

Dashboards Dashboard

The AKKO Audit Trail & Usage dashboard (akko-audit-usage) contains 14 panels:

  1. Activity Timeline -- Unified log from all sources (table, filterable)
  2. Top Users by Trino Queries -- Bar gauge, 24h window
  3. Top Users by LLM Tokens -- Bar gauge, 24h window
  4. JupyterHub Active Sessions -- Stat panel
  5. JupyterHub Total Users -- Stat panel
  6. Users Online vs Total -- Keycloak active sessions vs registered
  7. Storage by Bucket -- S3 bucket usage (bar chart)
  8. CPU Usage by User Pods -- JupyterHub singleuser pods (timeseries)
  9. Memory Usage by User Pods -- JupyterHub singleuser pods (timeseries)
  10. Keycloak Auth Events -- Login/logout log panel
  11. Trino Query Log -- SQL queries with user and duration
  12. OPA Authorization Decisions -- Policy decisions log
  13. LiteLLM Request Rate -- AI gateway requests per model (timeseries)
  14. Audit Event Volume -- Stacked bar chart of all event types over time

Access via: Dashboards > AKKO folder > "AKKO Audit Trail & Usage"

Cockpit Usage Page

The cockpit includes a dedicated Usage page (sidebar > Usage, admin-only) that provides:

  • KPI cards: Total users, online users, Trino queries (24h), LLM requests (24h), active notebooks
  • Overview tab: Embedded Dashboards audit dashboard in kiosk mode
  • Trino Queries tab: Recent query log table
  • LLM Usage tab: Token consumption, latency, model usage, error rate
  • Sessions tab: JupyterHub active sessions + Keycloak auth events
  • Storage tab: S3 bucket usage + PostgreSQL database sizes with bar chart
  • Resources tab: CPU and memory consumption per user pod

Configuration

Trino Event Listener

Configured in values.yaml and values-trino.yaml:

trino:
  eventListenerProperties:
    - event-listener.name=log
    - log.query-created=true
    - log.query-completed=true
    - log.split-completed=false

This logs query events to stdout, which log shipper collects and ships to logs layer.

LiteLLM Usage Tracking

LiteLLM is configured with Prometheus callbacks in the config:

litellm_settings:
  success_callback: ["prometheus"]
  failure_callback: ["prometheus"]
  json_logs: true
  store_audit_logs: true

When database_url is set (pointing to PostgreSQL), LiteLLM also persists usage data for historical analysis.

Keycloak Events

The realm has events enabled with two listeners:

  • jboss-logging -- Writes events to server logs (collected by log shipper)
  • metrics-listener -- Exposes event counts as Prometheus metrics

Enabled event types: LOGIN, LOGOUT, REGISTER, TOKEN_EXCHANGE, CLIENT_LOGIN, UPDATE_PASSWORD, UPDATE_PROFILE, RESET_PASSWORD, and more.

Admin events are also enabled (adminEventsEnabled: true) for tracking administrative operations.

OPA Decision Logs

OPA is configured with decision logging enabled. All Trino authorization decisions (allow/deny, column masking, row filtering) are logged and collected by log shipper.

Data Retention

  • logs layer: Default retention is 7 days (configurable via values-loki.yaml)
  • Prometheus: Default retention is 15 days (configurable via values-monitoring.yaml)
  • LiteLLM PostgreSQL: Persistent, follows database backup schedule

For compliance requirements exceeding these defaults, increase retention or configure log forwarding to an external SIEM.

Access Control

The Usage page and Dashboard are restricted to users with the akko-admin role. Non-admin users cannot access audit data.