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 (storage_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.

Cockpit governance audit (OCSF 1.3)

Sprint 66 added a production-grade audit emitter inside akko-cockpit-backend that captures every governance write action initiated through the cockpit (role composite wiring, user/group/role assign or revoke). Events follow the OCSF 1.3 schema (Open Cybersecurity Schema Framework, OASIS 2024) — the same model used by Splunk, AWS Security Lake, Cisco SecureX and Microsoft Sentinel.

OCSF field Meaning
class_uid 3005 user-access mgmt, 3006 group mgmt, 3007 data access (Sprint 67), 3008 LLM (Sprint 68)
activity_id 1 create, 4 delete, 3 update, 2 read
actor.user.uid OIDC sub claim — the stable user identifier
actor.user.type_id 1 human, 2 service account
resources[] typed list, e.g. realm-role:akko-admin, realm-role-mirror:AD_engineer
status Success / Failure / Unknown
correlation_id links cockpit row → VictoriaLogs stream → Tempo trace
app always akko-audit

Each event is fanned out concurrently to two redundant sinks for at-least-once delivery :

  • stdout sink — line AKKO_AUDIT {compact-json} on cockpit-backend pod stdout, picked up by the cluster fluent-bit DaemonSet → VL.
  • direct VL HTTP push — POST /insert/jsonline with stream label app=akko-audit, retry 3× exp backoff (200ms → 800ms → 3.2s).

The cockpit Gouvernance > Audit tab queries /api/governance/audit?since=24h&activity=role&actor=alice and renders each row with a French human label, the actor display name + email, typed resource chips, status pill and a copyable correlation ID.

For SIEM integration, forward the VL stream {app="akko-audit"} to your existing OCSF-aware collector — no schema translation needed. See ADR-052.

Data Retention

  • VictoriaLogs: Default retention is 14 days (configurable via logs.victorialogs.retention in helm/akko/charts/akko-observability/values.yaml; the vlogs chart, service akko-victorialogs on port 9428)
  • Prometheus: Default retention is 15 days (configurable via helm/akko/values.yaml under monitoring)
  • 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.