: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.
Cymbal HTTP compatibility
Remote symbol resolution is an internal implementation detail of cymbal. The external Node.js error-tracking consumer contract stays unchanged.
/process request and response
- Node still sends
POST /processto cymbal with an array ofAnyEvent-shaped exception events. - Cymbal still returns an array with the same length and ordering as the request.
- Each non-null response entry is the same
AnyEventshape with updatedproperties. nullentries keep their existing meaning: the event was suppressed by the normal cymbal pipeline.- Remote resolution only changes how cymbal fills the exception list before properties, grouping, linking, suppression, and alerting continue.
Node-side chunking
nodejs/src/ingestion/error-tracking/cymbal/client.ts chunks HTTP requests by estimated original event body size before they reach cymbal.
That remains valid because cymbal preserves the HTTP boundary and performs private exception-level gRPC work after it receives an HTTP chunk.
No generated type changes are needed:
- the Node request type remains
CymbalRequest - the Node response type remains
(CymbalResponse | null)[] - the internal
cymbal.resolution.v1gRPC messages are not exposed to Node
Remote resolution behind the HTTP boundary
- Events use the remote pool and do not silently fall back to inline resolution on failures.
- Events are flattened into exception-level
ResolveItems. Items are grouped by their first symbol-set reference when available, with a per-team fallback, then submitted over per-endpoint bidirectionalResolvestreams. - Resolver-specific context is carried in
ResolveItem.metadataas JSON bytes. The native symbolication convention uses adebug_images_jsonkey. Done.release_idcarries the newest release bound to a symbol set the item's frames reference. It is empty when none of them has a release, and on servers that predate the field, so callers treat empty as "no release". The processing side uses it only as the fallback source for$exception_release, behind the event's own$release_idand mobile app metadata.- Per-item
ResolveOutcome.Error.kindis the control-flow surface.ERROR_KIND_OVERLOADEDis result-only backpressure and triggers item reroute. Accepted items emitResolveOutcome.Acceptedbefore their terminal outcome; cymbal releases its routing permit on that acceptance signal. IfCYMBAL_REMOTE_RESOLUTION_OVERLOAD_EJECTION_MSis non-zero, the overloaded endpoint is also temporarily excluded from new routing in that cymbal process. Repeated overloads double that cooldown up toCYMBAL_REMOTE_RESOLUTION_OVERLOAD_EJECTION_MAX_MS, and a quietCYMBAL_REMOTE_RESOLUTION_OVERLOAD_EJECTION_DECAY_MSwindow resets it.CYMBAL_REMOTE_RESOLUTION_ROUTING_JITTERcontrols how much routing flattens across the load-adjusted rendezvous-ranked candidate list (0.0strict top load-adjusted candidate,1.0load-weighted across candidates).LoadEventcarries endpoint freshness/draining state plusin_flight/max_in_flightas a soft routing load signal.
This means Node request chunking limits protect cymbal's public HTTP body size, while cymbal's private gRPC path owns exception-level routing, reroute depth, and overload handling.