0pt/services/analytics/README.md

0pt analytics HTTP surface

The missing read plane between API0's /analytics/* contract and the opt_analytics ClickHouse database.

Surface

Serves the BI-P068 operation paths under /api/0pt/analytics:

• GET /health
• GET /datasets, GET /datasets/{id}
• GET /metrics, GET /metrics/{id}, GET /metrics/{id}/explain
• POST /metrics/{id}/query
• POST /query, POST /query/estimate, POST /query/explain
• GET /query/{id} (404: executions are not persisted yet)
• GET /dashboards, GET /reports (empty until the BI metadata lane writes them)
• GET /search

Identity: the caller's Keycloak token is verified against the portal realm JWKS; tenant_id is taken from the token and cross-checked against X-Tenant-Id. An X-Internal-Token path exists only for the ingestion worker.

Ingest

ingest_aud0.py maps AUD0 audit events to opt_analytics_event (dataset_id=aud0.events, metric=event_count, dimensions event_type/app_id/ capability_id/risk_level). It is idempotent per event_id.

AUD0_TOKEN=... AUD0_TENANT_ID=... CLICKHOUSE_URL=http://opt-analytics-clickhouse:8123 \
  python ingest_aud0.py --limit 50000

Run

pip install -r requirements.txt
CLICKHOUSE_URL=http://opt-analytics-clickhouse:8123 \
KEYCLOAK_ISSUER=https://auth.portal.siax.dev/realms/portal \
uvicorn app:app --host 0.0.0.0 --port 8096

Test

python -m pytest tests -q