Skip to main content

G-04 Analytics store

Brick G of the Enterprise AI Platform. Technology: ClickHouse (usage_events, spans, audit projections) with materialized views. French version: ../../fr/bricks/G-04-analytics.md.

Role and responsibilities​

  • Hold high volume facts: Usage Events, span summaries, evaluation results, for fast aggregation.
  • Serve /v1/finops/summary and /v1/telemetry/overview aggregates.

Position and interactions​

  • Execution path: batch and streaming inserts.
  • PostgreSQL eai.usage_events is the transactional source; rows are replicated to ClickHouse eai_finops.usage_events (ReplacingMergeTree by event_id), and eai.telemetry_spans to eai_telemetry.spans, by the worker job analytics_export (see docs/operations/en/analytics-export.md).

Open source and developed parts​

  • Open source reused: ClickHouse, clickhouse-operator.
  • Developed in the platform: Schemas, materialized views per day/tenant/model, replication worker with idempotency.

Data model​

Control Plane tables (schema eai): eai.usage_events, ClickHouse usage_events.

Every tenant table has tenant_id uuid NOT NULL and a row level security policy on current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events is the analytics replica of eai.usage_events (ReplacingMergeTree keyed by event_id).

Contract: contracts/v1/usage-event.schema.json (schema_version 1.0). Usage is always reported with contracts/v1/usage-event.schema.json, audit with contracts/v1/audit-event.schema.json.

API endpoints​

MethodPath
GET/v1/finops/summary
GET/v1/telemetry/overview
GET/v1/finops/usage

GET /v1/finops/summary​

Response:

{
  "group_by": "agent",
  "currency": "EUR",
  "items": [
    {
      "key": "agt_ap",
      "estimated": "41.20",
      "measured": "38.75",
      "billed": "39.02"
    }
  ]
}

GET /v1/telemetry/overview​

Response:

{
  "window": "24h",
  "requests": 18234,
  "error_rate": 0.012,
  "p95_latency_ms": 2140,
  "tokens": {
    "input": 9120044,
    "output": 1203400
  },
  "top_models": [
    {
      "model_id": "gpt-4o-mini",
      "share": 0.61
    }
  ]
}

GET /v1/finops/usage​

Response:

{
  "items": [
    {
      "event_id": "use_01J",
      "usage_type": "llm",
      "cost": {
        "measured": {
          "amount": "0.000228",
          "currency": "USD"
        }
      }
    }
  ],
  "next_cursor": null
}

SLO and error budget​

GET /v1/telemetry/slo returns, per service and over a window in minutes, requests, 5xx errors, requests over the latency threshold, budget remaining and burn rate, from the platform's own request measurements. See docs/operations/en/slo.md.

SDK examples​

Python​

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="en")
client.finops.summary(group_by="agent")
client.telemetry.overview(days=1)
client.finops.usage(agent_id="agt_ap", limit=100)

TypeScript​

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "en" });
await client.finops.summary({ group_by: "agent" });
await client.telemetry.overview({ days: 1 });
await client.finops.usage.list({ agent_id: "agt_ap", limit: 100 });

Java​

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.ENGLISH)
    .build();
client.finops().summary(Map.of("group_by", "agent"));
client.telemetry().overview(Map.of("days", 1));
client.finops().listUsage(Map.of("agent_id", "agt_ap", "limit", 100));

Go​

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("en"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.FinOps.Summary(ctx, eai.WithQuery(map[string]string{"group_by": "agent"}))
_, err = client.Telemetry.Overview(ctx, eai.WithQuery(map[string]string{"days": "1"}))
_, err = client.FinOps.ListUsage(ctx, eai.WithQuery(map[string]string{"agent_id": "agt_ap"}), eai.WithLimit(100))

Configuration​

Environment variables: EAI_CLICKHOUSE_URL.

Helm values keys (deploy/helm/enterprise-ai/values.yaml): controlPlane.config.EAI_CLICKHOUSE_URL.

Security​

  • Row policies by tenant_id; read-only users for Grafana.
  • Tenant resolved from the credential, never from the body; PostgreSQL row level security on every tenant table.
  • Every mutation and policy decision writes a hash chained audit event (G-11).
  • Errors use the standard envelope with message_i18n en and fr.

Observability​

  • Insert latency, parts count, replication lag versus PostgreSQL.
  • W3C traceparent propagated, X-Request-Id returned, spans carry eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

FinOps units​

  • Storage and query cost allocated by tenant through partition sizes.

Failure modes and resilience​

  • ClickHouse unavailable -> summary falls back to PostgreSQL aggregates (slower), flagged source=postgres.

Standalone adoption​

A data team can query ClickHouse views directly with read-only credentials.

Acceptance tests​

  1. Replaying the same Usage Event twice produces one row after merge.
  2. Summary by model matches PostgreSQL totals to the cent.

Implementation roadmap