LEX AI Analytics Guidelines Summary

The analytics contract in summary: transport, backend architecture, safety rules, run identity, the canonical event envelope, and current event coverage.

A
Written By Atakan KayaLast updated 3 months ago

LEX AI Analytics Guidelines Summary

This summary captures the key rules from the repository analytics contract. It matters to anyone who needs to state what leaves the machine during a run and what does not.

Storage and transport

  • Primary remote path: events forwarded through the remote MCP tool log_analytics_event, one event per call.
  • Local fallback: a JSONL file under the user's home config path, which is the default backend when no remote is configured.
  • The local server never talks to the analytics store directly, so an install needs no cloud credentials and no extra dependencies.

Architecture requirements

  • Strategy-pattern backend abstraction with dependency injection.
  • Backends: local, remote, composite, and null. A failure in one backend must not stop the others.
  • The emitter auto-injects the envelope metadata and never raises. A broken backend must never break a tool call.

Safety requirements

  • Never write to stdout from analytics paths — stdout is the JSON-RPC channel.
  • Never block tool execution on telemetry I/O; remote emission is queued to a background worker.
  • Never include secrets in emitted data; reuse the existing redaction helpers.
  • Correlation identifiers are UUIDs. No emails, no access tokens, and no URLs carrying tokens. The one identity field is github_username, the GitHub login resolved from the workflow token, which is null in the modes that never touch GitHub.

Identity and correlation

  • Session ID is per server boot. It survives mode switches and is lost on restart.
  • Run token is per workflow run, minted at that mode's kickstart, persisted in the session manifest, and restored on resume. Nine of the ten modes mint one, not only the forward-style ones; brief mode is the exception and emits its interview events without one.
  • Run label is human-readable display metadata; correlation always uses the run token.

Error and observability behavior

  • Instrument boundaries on both the success and the failure path.
  • Use the canonical envelope for every event: event_id, event_type, timestamp, session_id, run_token, run_label, mode, github_username, and an event-specific payload.
  • Preserve explicit workflow lifecycle observability, including the workflow_stale event a long pause raises on resume.

Coverage

The catalogue currently lists 63 event types across the modes, from brief_started and question_declined through test_prerequisite_blocked and input_session_finalized. The inventory is generated from the emit call sites rather than written by hand, but it is regenerated on demand and can lag a newly added mode: deploy's session, step and finalize events are emitted today without appearing in it.

For implementation detail, consult analytics/ANALYTICS_GUIDELINES.md and the event catalogue in analytics/ANALYTICS_EVENTS.md. See What we can diagnose.

Was this helpful?

Your feedback shapes what we write next.