Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

3.0 KB
Raw Blame

AI observability

AI observability started as an analytics view over generation events and has grown into a full LLM platform: traces, evaluations, clustering, prompt management, a model gateway, a playground, and review queues.

This README is the orientation map for the product folder. Agents should also read AGENTS.md for product-specific rules.

Directory layout

products/ai_observability/
  backend/                # Django app (label: llm_analytics)
    api/                  # DRF viewsets (one file per resource;
                          # api/__init__.py is the canonical inventory)
    llm/                  # Unified LLM client
      client.py           # Single entry point for provider calls
      providers/          # Per-provider adapters
      formatters/         # Provider request/response formatters
    models/               # Django models + pydantic validators
    migrations/
    queries/              # Raw .sql files used by query runners
    summarization/        # Trace and evaluation summarization
    translation/
    text_repr/            # Text-representation formatters for events
    tools/                # Shared backend tools
    test/
  frontend/               # React + kea
    components/           # Reusable UI
    <feature>/            # clusters, datasets, evaluations, playground,
                          # prompts, settings, traceReviews,
                          # scoreDefinitions, skills, ...
    generated/            # Generated types (do not edit)
  mcp/                    # MCP tool definitions
  dags/                   # Dagster jobs + metrics
  skills/                 # Agent skills scoped to the product
  docs/                   # Product-level docs (architecture decision records)
  shared/                 # Constants and schemas shared across frontend, backend, capture and ingestion (crosslang/)
  manifest.tsx            # Scene + navigation registration
  package.json            # Turborepo package (@posthog/products-ai-observability)

Query runners for the product live outside this folder in posthog/hogql_queries/ai/. Three runners matter: trace_query_runner.py (single trace), traces_query_runner.py (list), and session_query_runner.py (traces in a session). See AGENTS.md for why that detail matters.

Running tests locally

# Backend (pytest, Django)
hogli test products/ai_observability/backend
hogli test products/ai_observability/backend/api/test/test_trace_reviews.py

# HogQL query runners (live in posthog/, not products/)
hogli test posthog/hogql_queries/ai

# Frontend (Jest)
hogli test products/ai_observability/frontend
hogli test products/ai_observability/frontend/utils.test.ts --watch

After changing a serializer or viewset, regenerate OpenAPI and TypeScript types:

hogli build:openapi

Further reading

  • AGENTS.md — product-specific conventions.
  • products/architecture.md — target architecture for products (facades, contracts, isolation). This product has not yet been migrated.