feat(analytics): print a session's agent metrics under --experimental-auth

[Topherhindman]

Fixes DEVX-798
Stacked on #1022.
Depends on livekit/public-api-server#53.

lk analytics session metrics SESSION_ID prints a page of the OpenTelemetry metric points a session's agents exported, one line per point. These are the raw metrics agents emit, so they won't exactly match the dashboard's metrics panel, and the help says so. The command runs only under --experimental-auth, since only the Public API serves agent metrics.

What changed

• Regenerated client (chore(public)): oapi.gen.go is regenerated from livekit/public-api-server@3e3abf0, livekit/public-api-server#53's merge commit on main. It picks up GetSessionMetrics as the server now serves it:

  • agent metrics come back as typed MetricPoints instead of livekit MetricsBatches
  • each point carries its metric's name, unit and kind (gauge, sum, histogram or exponential histogram), its start and end times, and typed attributes with its resource's and scope's merged in
  • a point holds either a gauge's or sum's value, or a histogram's count, sum, min, max and buckets
  • the request gains a names filter (at most 50 names, each 1 to 256 characters), and points come by end time
  • the docs say an attribute integer beyond ±2^53 comes as its decimal string, and on an ACTIVE session a point exported mid-read behind the cursor is missed until a new read

  Nothing hand-written reads the changed types, so only oapi.gen.go changes.

• Client (feat(public)):

  • GetSessionMetrics returns one page of points, by end time, and the cursor for the next.
  • MetricOptions embeds PageOptions and adds the metric names to keep, matched exactly. Validate rejects a negative limit or a blank name before any request is sent.
  • The generated point is a union that hides whether it holds a value or a histogram. So the body is decoded again into MetricPoints that say, as the transcript's items do. A point marshals back to the API's own JSON.
  • An unknown session is NotFound. An empty unfiltered first page with user data recording off carries the ObservabilityDisabled detail.

• Command (feat(analytics)):

  • Lines: each point prints its end time to the millisecond, its metric's name, and a gauge's or sum's value or a histogram's count, sum, min and max, in the metric's unit. An annotation such as {token} loses its braces.
  • JSON: --json prints {items, nextCursor} with the points as the API sent them, kind, start time, typed attributes and histogram buckets included.
  • Filter: --name is repeatable and keeps only those metrics' points, matched exactly. A blank one fails before the project lookup.
  • Paging: the next-page hint says to re-run with its --cursor. The user's own command already repeats the names the cursor was made for.
  • Empty page: it says why: no points for the metrics asked for, no agent metrics at all (only agents that export OpenTelemetry metrics to LiveKit Cloud produce them), or no more pages.
  • Errors go through sessionReadError: with user data recording off it says so and links the project's observability settings. An unknown session says there's no such session in the project, and names the project. A permission denial says reading the agent metrics requires being a project admin.
  • Runs only under --experimental-auth, through sessionRead.

Usage

lk --experimental-auth analytics --experimental session metrics SESSION_ID \
    [--name NAME ...] [--limit N] [--json]

• --limit defaults to 50, the server's page size. --cursor is hidden.

11:00:30.000  lk.agents.usage.llm_input_tokens  1520 token
11:00:30.250  lk.agents.turn.e2e_latency        count 3, sum 2.4 s, min 0.6 s, max 1.1 s
11:01:00.000  gen_ai.client.operation.duration  count 2, sum 1.5 s
More points available — re-run with --cursor c2

Since review

• a17eb17 fix(analytics): strip terminal escapes from metric names and units

Testing

• go build ./..., go vet ./pkg/... ./cmd/lk/ and go test ./pkg/... ./cmd/lk/ pass on every commit.
• New tests:
  • pkg/public: TestGetSessionMetrics (values and histograms decoded), TestMetricPointJSON, TestGetSessionMetricsRejectsBadOptions and TestGetSessionMetricsErrors.
  • pkg/public/render: TestSessionMetricsText, TestSessionMetricsEmpty and TestSessionMetricsJSON.
  • cmd/lk: TestSessionMetricsCommand, TestSessionMetricsRequiresExperimentalAuth, TestMetricOptions, TestFetchSessionMetrics (each empty-page reason), TestFetchSessionMetricsJSON and TestFetchSessionMetricsErrors.
• The command above was run on staging on 2026-10-08, against public-api-server's stack run locally, with a real sign-in and staging data.
• Known issue on staging: the aggregator merges metric series across names. That's in the aggregator, not in this command, which prints the points as the API returns them.
• Compared side by side with the staging dashboard on 2026-10-09 for two sessions: session detail, participants, events, transcript, agent logs and traces match, down to timestamps, turn latencies, redactions and log levels. The dashboard's "Dispatch" trace row is built in the browser from job_entrypoint's span events, which these reads return. Metrics are the known exception: the aggregator files several token and TTS series under one name, which the dashboard avoids by deriving usage from the transcript and traces.