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

Proto Definitions

Language-agnostic protobuf definitions for PostHog services.

Structure

proto/
├── buf.yaml
├── cymbal/               # Cymbal internal services
│   └── resolution/v1/    # Exception-level symbol resolution
├── ingestion/            # Event ingestion
│   └── worker/v1/        # Consumer → worker streaming ingest transport
├── kafka_assigner/       # Kafka partition assignment
├── personhog/            # Person data service
│   ├── types/v1/
│   ├── replica/v1/
│   └── service/v1/
├── prometheus/           # Prometheus remote write
│   └── v1/               # Remote write transport
└── usage_ingestion/      # Usage ingestion service
    └── v1/               # Billing usage record ingest

Consumers

Proto Rust Python Node.js
cymbal/ rust/cymbal-proto (auto via tonic) — —
ingestion/ rust/ingestion-worker-proto (auto via tonic) — nodejs/src/common/generated/ingestion-worker (checked in)
personhog/ rust/personhog-proto (auto via tonic) packages/personhog-proto/ (checked in) nodejs/src/common/generated/personhog (checked in)
kafka_assigner/ rust/kafka-assigner-proto (auto via tonic) — —
prometheus/ rust/prometheus-rw-proto (auto via tonic) — —
usage_ingestion/ rust/usage-ingestion-proto (auto via tonic) — nodejs/src/common/generated/usage-ingestion (checked in)

Updating protos

  1. Edit .proto files in the relevant directory
  2. Regenerate language bindings for affected consumers (see table above)
  3. Commit generated files — CI rejects stale stubs

Python stubs (personhog only)

bin/generate_personhog_proto.sh

Only needed when personhog/ protos change. Requires grpcio-tools (uv sync).

If you added or removed message types, update the re-exports in posthog/personhog_client/proto/__init__.py. If you added or removed RPCs, update the wrapper methods in posthog/personhog_client/client.py.

Rust

No action needed — Rust bindings regenerate on cargo build.

CI

.github/workflows/ci-proto.yml runs on proto changes:

  • buf lint — style and naming
  • buf breaking — backwards compatibility against master
  • Python codegen staleness check