Migrate the Rust SDK from 0.x.x to 1.0.0
The Rust SDK 1.x.x sends every event to the capture v1 endpoints, /i/v1/analytics/events and /i/v1/ai/events.
Use the top right copy page button to work through this with your agents.
You don't need to make every change on the day you upgrade your SDK. Required changes fall in these categories:
- Before you upgrade: you should make these changes before you upgrade your SDK to 1.x.x.
- During your upgrade: These are changes that you need to make in the same PR that upgrades your SDK version.
- Follow ups: These are changes that can come in follow up PRs because 1.x.x has limited backward compatibility for methods that are to be deprecated.
Checklist
Read the checklist first, then the sections that apply to you.
Before you upgrade
- You send events through your own proxy → Prepare your proxy
- A proxy redirects capture or
/flagsrequests → Prepare your proxy - You pass a personal API key (
phx_...) as the projectapi_key→ Use a project token - Your build environment has no C compiler → Check your C compiler
During your upgrade
- You enable the
capture-v1feature → Update Cargo features - You set
default-features = false→ Update Cargo features - You call
Uuid::new_v4→ Update Cargo features - You use
Endpoint::Batch,V1ErrorResponse, orpersonal_api_key→ Fix removed APIs - You
matchonEndpointorFeatureFlagsResponse, or build an SDK response type with a struct literal → Fix removed APIs - You call
is_feature_enabled,get_feature_flag,get_feature_flag_payload, orget_feature_flags→ Replace flag methods - You build
EvaluateFlagsOptionswith a struct literal → Replace flag methods - You filter logs on the
posthog_rstarget, or match the SDK's log lines → Update log filters - Your
before_sendhook returns a newEvent→ Copy options in before_send - You send large
$ai_events, or use the$ai_prefix for your own events → Route AI events - You capture a cloned or reused
Eventmore than once, or set auuidwithEvent::set_uuid→ Check event IDs - You set timestamps in the future, or read the timestamps the SDK sends → Check timestamps
- You call
group_identify, or pass an empty distinct ID toEvent::new→ Fix identity calls - You send
$identify,$create_alias,$merge_dangerously,$groupidentify,$set, or$set_onceevents, including throughaliasorgroup_identify→ Check identify-style events - You use
Event::new_anon,Event::add_group, orCaptureExceptionOptions::group→ Check person processing - You set an option to a value of another type, such as
"false"for a boolean → Check option values - You set
$set,$set_once,$groups, or$group_seton an event and in a request context → Check property precedence - You set
$os,$is_server,$geoip_disable, or a$feature/<key>property yourself, or change them inbefore_send→ Check property precedence - You use
RequestContext, with the async client, the blocking client, or themcpfeature → Check request context - You set
$libor$lib_versionyourself, or use themcpfeature → Check SDK identity - You send event names over 200 bytes, empty event names, or a
$session_idor$window_idthat isn't a string → Check dropped events - You send batches of large events → Check batch sizes
- You set
CaptureCompressiontoDeflate,Br, orZstd→ Check compression - You set
$trace_idor$span_idon exceptions, or read$debug_images→ Check exceptions - You advance durable state after
capture_immediate, or use anon_errorhook → Update error handling - You set
max_capture_attemptsorretry_initial_backoff_ms, or rely on their defaults → Check retries
Follow ups
- You depend on
posthog-rsand importposthog_rs→ Rename the crate - You set legacy option properties like
$process_person_profile→ Move to event options - You use the
mcpfeature → Add MCP event options - You capture
$ai_events withcapture→ Send AI events with capture_ai
Before you upgrade
Prepare your proxy
1.x.x sends events to these endpoints:
| Events | Endpoint |
|---|---|
Every event except those from the capture_ai methods | /i/v1/analytics/events |
Events from the capture_ai methods | /i/v1/ai/events |
The analytics endpoint includes error tracking, $feature_flag_called events, historical migration, before_send, and terminal failures reported through on_error.
The capture_ai methods are capture_ai, capture_ai_batch, capture_ai_immediate, capture_ai_batch_immediate, and the global posthog::capture_ai.
If you send events through your own reverse proxy, update it before you upgrade:
- Forward both routes. Forward
/i/v1/analytics/eventsand/i/v1/ai/eventsto PostHog. - Pass the headers through unchanged. Pass
Authorization, everyPostHog-*header,Content-Type,Content-Encoding, andUser-Agent.Authorizationholds the project token, sent asBearer <token>. PostHog answers401withoutAuthorizationand400without the others, and the batch fails. - Keep PostHog credentials. If the proxy strips other credentials, keep
Authorizationvalues that start withBearer phc_,Bearer phs_, orBearer phx_. Also keep the exactBearer <token>of an older project token without a prefix. - Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A
413from the proxy fails the batch. - Pass the capture response through. Return PostHog's status code and response body unchanged. A proxy that answers the capture path with its own
200fails the batch.
PostHog's managed reverse proxy already does this. See the proxy guides.
The capture and /flags HTTP clients the SDK builds follow a redirect only when it's a 307 or 308 to the same scheme, host, and port. They follow at most 5 redirects in a row.
Any other redirect fails the request, so the SDK never sends the request body to another host. 0.x.x followed up to 10 redirects of any kind to any host, and local evaluation polling still does. If a proxy redirects capture requests to another host, set host to the final host.
A client you pass with http_client or blocking_http_client keeps its own redirect policy.
Use a project token
A personal API key (phx_...) passed as the project api_key disables the client and logs one error, as an empty key does. PostHog never accepts a personal key for capture, so every request with it failed with a 401.
An empty key now logs at the error level instead of warning. A client built with disabled(true) logs nothing about its key.
Check your C compiler
Brotli and Zstandard support is always compiled in. zstd-sys builds C code with the cc crate, so the build needs a C compiler.
Every 0.x.x build already needed one for aws-lc-sys, the TLS crypto library.
During your upgrade
Update Cargo features
Remove capture-v1 from your dependency features. Capture no longer needs a feature flag.
The default features are the async client, error tracking, and TLS. For the blocking client, use default-features = false, and enable a TLS feature yourself when you send to an HTTPS endpoint.
0.x.x enabled TLS even with default-features = false. In 1.x.x, choose one of these features:
tls. It uses reqwest's default Rustls provider.tls-no-provider. Choose it when the application installs a process-level RustlsCryptoProvider. It avoids pulling inaws-lc-rsfrom this SDK, but constructing a client before installing a provider panics.
Cargo features are additive, so tls-no-provider only avoids the built-in provider when no dependency enables tls.
1.x.x no longer enables the v4 feature of the uuid crate. If your application calls Uuid::new_v4, enable v4 on its own uuid dependency.
The posthog-rs package takes the same features in 1.x.x (see Rename the crate).
Fix removed APIs
1.x.x removes these APIs:
| Removed | Use instead |
|---|---|
The V0 capture implementation, with its /i/v0/e/ and batch plumbing | Nothing |
Endpoint::Batch | Nothing |
V1ErrorResponse | CaptureErrorResponse |
is_feature_enabled, get_feature_flag, get_feature_flag_payload, get_feature_flags | evaluate_flags |
The builder's personal_api_key alias | secret_key |
LocalEvaluationConfig::personal_api_key | LocalEvaluationConfig::secret_key |
Endpoint::Capture now resolves to /i/v1/analytics/events.
For evaluate_flags, see Replace flag methods. The single-flag methods and the builder's personal_api_key alias were already deprecated in 0.x.x.
Rename V1ErrorResponse to CaptureErrorResponse:
These types are now non-exhaustive:
| Type | What to change |
|---|---|
Endpoint | Add a wildcard arm |
CaptureResponse, EventResult | Remove struct literals |
EvaluateFlagsOptions | Construct with Default |
FeatureFlagsResponse | Add a wildcard arm |
FlagDetail, FlagMetadata, FlagReason, LocalEvaluationResponse | Remove struct literals |
Endpoint has a new CaptureAi variant, so a match on it needs a wildcard arm. A match on the FeatureFlagsResponse enum needs a wildcard arm.
You can't build CaptureResponse or EventResult with a struct literal. Construct EvaluateFlagsOptions with Default (see Replace flag methods).
The FlagDetail, FlagMetadata, FlagReason, and LocalEvaluationResponse structs no longer accept struct literals. Build a LocalEvaluationResponse with LocalEvaluationResponse::new and assign its public fields.
Use secret_key terminology throughout configuration:
secret_key accepts either a project secret key (phs_...) or a personal API key (phx_...). Don't send this key as an event property.
Replace flag methods
Call evaluate_flags once and read from the returned snapshot:
The blocking client uses the same calls without .await.
EvaluateFlagsOptions is now non-exhaustive. Construct it with Default and assign the fields you need instead of using a struct literal:
Update log filters
The implementation's tracing target is now posthog, including when you use the posthog-rs compatibility crate. Update filters such as RUST_LOG=posthog_rs=debug to RUST_LOG=posthog=debug.
Update any log filter that matches the 0.x.x text of these lines:
- A request that fails for good. Without an
on_errorhook, it logsposthog-rs: dropping <n> event(s) for <endpoint>: <error>. 0.x.x logged the same line withoutfor <endpoint>. - Queue-full and shutdown warnings. They now name the endpoint too, for example
posthog-rs: event queue full for <endpoint> (capacity <n>); dropping events. - A
before_sendhook that panics. The SDK logs an error that names the event:panic in PostHog before_send hook for event "<name>"; dropping event. 0.x.x logged that line withoutfor event "<name>", and a panic in theMcpOptionshook logged a different warning.
The error text can include PostHog's response body. Register an on_error hook to choose what to log.
Copy options in before_send
Review your before_send hooks for the new event shape. Capture v1 reads per-event processing controls, such as person profile processing, from an options map that is sent next to properties.
before_send hooks can read and change options with Event::options, insert_option, and remove_option. To change an option, use insert_option.
A hook that returns a new Event must copy the options of the event it received, or the event is sent without them.
That includes the process_person_profile option that Event::new_anon sets to false. Without it, PostHog would create a person for the generated ID. It also includes the true the SDK sets on identify-style events.
Route AI events
1.x.x routes AI events to their own endpoint:
- The endpoint.
capture_ai,capture_ai_batch,capture_ai_immediate,capture_ai_batch_immediate, and the globalposthog::capture_aimirror their analytics counterparts. They post to/i/v1/ai/eventson their own background lane, batched by size. - Routing.
capturenever reroutes by event name. Large AI events always needcapture_ai. - Event names. PostHog drops an event sent with
capture_aiwhose name doesn't start with$ai_. It reports it as a per-eventdropwith the detailmisrouted_eventinside a200. - Where the drop is reported. That verdict reaches an
on_errorhook, whereCaptureFailure::endpoint()says which lane, or the returnedCaptureSummaryfor the immediate variants. - The
$ai_prefix. PostHog owns the$ai_prefix, so don't use it for your own events. - Flush and shutdown.
flushandshutdowndrain both lanes. - Events over 8 MiB. The SDK drops an event over the backend's 8 MiB per-event limit locally, on the background lane and in the immediate variants. On the background lane, that drop logs a warning with the event name and size, and it doesn't reach
on_error. The immediate variants return that drop in theCaptureSummarywith the detailai_event_too_big. - Events over the request limit. An event too large for the AI endpoint's request size limit gets HTTP
413instead.capture_ai_batch_immediatereturnsError::BadRequestand doesn't send the rest of the batch.
The AI lane has its own options:
| Option | Default |
|---|---|
capture_ai_compression | Unset |
capture_ai_max_queue_size | 1000 |
An unset capture_ai_compression sends AI bodies uncompressed. Set CaptureCompression::Zstd, the best fit for large JSON.
Check event IDs
- Generated IDs. The SDK gives every event a UUIDv7
uuidand every request a UUIDv7 request ID. - When the SDK assigns a uuid. The SDK assigns an event's uuid when you hand the event to
captureorcapture_immediate, not inEvent::new. Capturing a cloned or reusedEventtwice now sends two uuids. In 0.x.x both copies shared one uuid, so PostHog kept only one of them. - Your own uuids. A uuid set with
Event::set_uuidis still sent as given on every capture. If you set your own, keep it unique. - Duplicates. When two events in one request share a
uuid, PostHog keeps the first and drops the later copies. The SDK reports each dropped copy throughon_errorandCaptureSummarywith the reasonduplicate_event_uuid. An entry'sEventResult::duplicates_droppedcounts the copies dropped with it. Older PostHog versions reject the whole request with HTTP400duplicate_event_uuidinstead. - Duplicates of a retried event. If the kept copy comes back
retryin the background worker, those dropped copies aren't reported. PostHog still raises aduplicate_event_uuidingestion warning in your project.
Check timestamps
- The format. Every timestamp the SDK sends is UTC with a
Zand 3, 6, or 9 fractional-second digits. That covers the eventtimestamp, the batchcreated_at, and thePostHog-Request-Timestampheader. A whole second is sent as.000Z, and finer digits from your timestamp or the clock are kept. - Future timestamps.
Event::set_timestampaccepts timestamps in the future. In 0.x.x it returnedError::InvalidTimestampfor a timestamp more than 1 s ahead. PostHog clamps far-future timestamps, as it does for every other SDK. The method keeps itsResultreturn type.
Fix identity calls
- Empty distinct IDs.
Event::newwith an empty or whitespace-only distinct ID creates an anonymous event, asEvent::new_anondoes. In 0.x.x it sent the empty ID, and PostHog dropped the event. - Long distinct IDs. PostHog drops an event whose distinct ID is over 200 UTF-8 bytes, with the per-event result
distinct_id_too_large. It reacheson_error, or theCaptureSummaryof an immediate method. 0.x.x sent events to legacy capture, which shortened the ID to 200 characters and kept the event. - Group fallback.
group_identifysends the request context's distinct ID when the context has one, and$<group_type>_<group_key>otherwise. In 0.x.x it always sent$<group_type>_<group_key>. - Group sessions.
group_identifynever adds the context session ID. In 0.x.x it did. - Long group IDs. If
$<group_type>_<group_key>is over 200 bytes, PostHog drops the event. To set a group with a longer key, capture a$groupidentifyevent yourself withEvent::new("$groupidentify", <your distinct ID>)and the$group_type,$group_key, and$group_setproperties.
Check identify-style events
$identify, $create_alias, $merge_dangerously, $groupidentify, $set, and $set_once events default to process_person_profile: true. These events merge persons or update person or group properties, which PostHog skips when person processing is off.
PostHog drops $create_alias and $groupidentify events that have person processing off and records an invalid_event_when_process_person_profile_is_false ingestion warning in your project. Capture accepts these events before the drop, so on_error doesn't see it.
The SDK therefore keeps the request context from turning person processing off for them, except on an event whose distinct ID the SDK generated. This covers alias, group_identify, and any event with one of these names that you build and capture yourself.
- Event values. The event's own value wins over every layer. An event that sets the
process_person_profileoption keeps it. An event that sets only the legacy$process_person_profileproperty sends that value as the option. Anullvalue counts as unset. - The default. Otherwise, when the SDK didn't generate the event's distinct ID, the SDK sets the option to
truebefore it applies the request context, so a context option or property offalsedoesn't reach the event. - Generated distinct IDs. An event whose distinct ID the SDK generated gets no default and stays personless. That's an event from
Event::new_anon, fromEvent::newwith a blank ID, or fromRequestContext::eventwithout a context distinct ID. A$process_person_profileproperty you set on such an event wins over the personlessfalseonly when you set it before you apply a request context yourself.RequestContext::eventapplies its context when it builds the event, so set theprocess_person_profileoption on that event instead. before_send. The hook sees the resolved value as the option, without a$process_person_profileproperty next to it. It can change the option, and the SDK sends what the hook returns. A hook that removes the option sends the event without one.- Hooks that build or rename events. The SDK checks the event name when you capture the event. A
before_sendhook that builds an event with one of these names, or renames an event to one, must set the option itself. - Contexts you apply yourself. When you apply a request context yourself with
RequestContext::eventorRequestContext::apply_to_event, set theprocess_person_profileoption on an identify-style event afterwards, not the legacy$process_person_profileproperty. The SDK ignores a legacy property set after that, whether or not it generated the distinct ID. In 0.x.x, a$process_person_profileproperty set afterRequestContext::eventstill applied. - Keeping one personless. To send an identify-style event without person processing, set the
process_person_profileoption tofalseon the event or inbefore_send, or turn off person processing for the project in PostHog.
To set options on the events that alias and group_identify send, build them with Event::alias and Event::group_identify, then capture them:
Both constructors return Error::InvalidArgument for a blank ID, group type, or group key. client.alias and client.group_identify still log a warning and drop the event.
In 0.x.x, a context that turned person processing off reached alias and group_identify, and PostHog dropped their events.
Check person processing
- Anonymous events.
Event::new_anonsets theprocess_person_profileoption tofalse. To process person profiles for an anonymous event, set the option withinsert_option("process_person_profile", true). Anullor removed option counts as unset, so the SDK setsfalseagain beforebefore_send. - Context options. A context
process_person_profileoption replaces thefalsethatEvent::new_anonsets. - Identify-style events. An identify-style event gets
process_person_profile: truebefore the context applies, unless it sets its own value or the SDK generated its distinct ID. - Groups. Adding a group no longer turns on person processing. In 0.x.x,
Event::add_groupandCaptureExceptionOptions::groupturned person processing on. In 1.x.x they leave it unchanged. - Events from
Event::new. They still process person profiles by default. - Anonymous events with groups. An anonymous event with groups, from
Event::new_anonor an exception without a distinct ID, now stays personless. PostHog attaches groups for group analytics only to events that process person profiles. Setinsert_option("process_person_profile", true)on those events if you need them in group analytics.
Check option values
The SDK sends option values unchanged, and PostHog validates them:
- Unknown keys. PostHog ignores keys it doesn't know.
- Common forms. PostHog converts common forms of a known key's value. For a boolean, those include
"yes","off","false", and0. - Values PostHog can't read. PostHog drops the event if a known key has a value it can't read. That drop reaches
on_erroras a per-eventdropwith the detailinvalid_options. - 0.x.x with
capture-v1. The SDK removed a value it couldn't read and sent the event without it. - 0.x.x without
capture-v1. It used the V0 endpoint, which ignored aprocess_person_profileoption of"false". In 1.x.x that string turns person processing off. The V0 endpoint also kept an event with a value it couldn't read and ignored the value.
Check property precedence
An event's properties and options come from three layers. For the same key, a layer earlier in this list wins, except for $lib, $lib_version, and its version parts, which follow the rule in Check SDK identity:
- Event values: what you set on the event with
insert_propandinsert_option, or onCaptureExceptionOptions. For$feature_flag_calledevents, a per-calldisable_geoipinEvaluateFlagsOptionscounts as an event value. - Request context: properties and options from
RequestContext. They fill only the keys the event leaves unset. - SDK values:
$lib,$lib_versionand its three version parts,$os,$os_version, and$is_serverand$geoip_disablefrom the client settings, plus theprocess_person_profileoption thatEvent::new_anonsets tofalse.
before_send runs after all three and can change any value. The SDK has no client-wide layer for properties or options.
A property set to null counts as set, so the request context doesn't fill it. A null option counts as unset.
- System properties. The SDK adds
$os,$os_version,$is_server, and$geoip_disableonly when the event doesn't already have the key, and it adds them beforebefore_sendruns. The hook sees them and can change or remove them, and the SDK doesn't add them again after the hook. - System properties in 0.x.x. The default 0.x.x path (V0) also added them before the hook. The 0.x.x
capture-v1path added them while building the request, after the hook, so a hook couldn't see$osor remove any of them. $liband$lib_version. The SDK adds them beforebefore_sendruns, as a pair, as described in Check SDK identity. The 0.x.xcapture-v1path never added them.- Feature flag properties.
Event::with_flagskeeps a$feature/<key>or$active_feature_flagsproperty that the event already has. In 0.x.x, the flag values replaced it. - Groups. Groups from
Event::add_groupmerge into a$groupsproperty key by key, and the added group wins for the same group type. In 0.x.x, they replaced the whole$groupsproperty. - Groups in
before_send. The SDK merges those groups into$groupsbeforebefore_sendruns, so the hook sees them and can change or remove them. The default 0.x.x path (V0) also merged them before the hook. The 0.x.xcapture-v1path merged them while building the request, after the hook. A group the hook adds withadd_groupis still sent. - Merged maps. A
$set,$set_once,$groups, or$group_setfrom the request context fills in only the keys the event's own value lacks. For example, a context$setof{"plan": "free", "source": "web"}and an event$setof{"plan": "pro"}send{"plan": "pro", "source": "web"}. In 0.x.x, the context value was used only when the event had none of that property. A$setin the request context sets those person properties on every event it reaches. - Minimized flag events. For a minimized
$feature_flag_calledevent, the SDK trims the properties to its allowlist beforebefore_sendruns, so a property the hook adds is sent. In 0.x.x the trim ran after the hook and removed it. - Flag events.
$feature_flag_calledevents now take a request context value over the client's$is_serverand$geoip_disabledefaults, as other events do. A per-calldisable_geoipwins over both, andSome(false)sends$geoip_disable: false. In 0.x.x,Some(false)sent nothing, so a request context$geoip_disableapplied. - The
disable_geoipdefault.disable_geoipdefaults tofalse, as in 0.x.x and unlike PostHog's other server SDKs, so PostHog adds GeoIP properties based on the IP address of your server. To turn this off, call.disable_geoip(true)onClientOptionsBuilder.
Check request context
The request context works only with the async client. Code inside RequestContext::scope sends the context with these calls:
- Capture calls.
capture,capture_batch,capture_immediate,capture_batch_immediate, thecapture_aimethods, andcapture_exception. - Identity calls.
aliasandgroup_identify. - Flag snapshots. A flag snapshot from
evaluate_flagsinside the scope keeps the context for its$feature_flag_calledevents, even after the scope ends.
An event you build with Event::new or Event::new_anon keeps its own distinct ID. An exception without a distinct ID takes the context distinct ID.
MCP events from the mcp feature take the request context too:
- Over HTTP.
rmcpruns each request handler in a task of its own, so over HTTP the SDK reads theRequestContextthatPostHogLayeror your middleware placed in the request extensions. - A scoped context. A context scoped around the code that sends the event wins over the one in the request extensions.
- The distinct ID. The identity from the
McpOptionsidentifycallback stays the distinct ID. - Anonymous MCP events. An anonymous MCP event keeps its MCP session ID as the distinct ID and keeps
process_person_profile: falseover a context option. - The hook. The
McpOptionshook sees the context values.
The blocking client has no scoped context, and RequestContext::current() returns None. Apply a context to each event yourself with RequestContext::event or RequestContext::apply_to_event, and use evaluate_flags_with_context for flags.
Check SDK identity
Each event's $lib and $lib_version properties name the library that produced it. The SDK sends them in properties as they are when the event is sent, and PostHog stores them.
The SDK also sends posthog-rs/<version> in the posthog-sdk-info request header. PostHog uses the header only to fill in what an event leaves unset: both properties when $lib isn't set, and the version when $lib is posthog-rs and $lib_version isn't set.
You can set them on the event or in the request context. Like any other property, each one comes from the most specific place that sets it, so set both in the same place.
The SDK fills these properties after the event and request context values, and before before_send runs.
A $lib counts as set only when it's a non-empty string, so a missing, null, empty, or non-string $lib isn't set. The same goes for $lib_version.
| The event has | The SDK sends |
|---|---|
No $lib | $lib as posthog-rs and $lib_version as the crate version |
A $lib of posthog-rs and no $lib_version | The crate version in $lib_version |
A $lib that names another library | Both properties as they are |
A $lib_version set without $lib is replaced.
The SDK sends another library's $lib and $lib_version as they are, even if $lib_version is missing. Set both when you name another library.
before_send sees the result and can change either property. The SDK doesn't fill them again after the hook.
PostHog still uses the header as described above, so an event the hook sends without $lib is stored as posthog-rs. To label an event as another library, set both $lib and $lib_version in the hook.
When the SDK adds its own $lib_version, it also adds $lib_version__major, $lib_version__minor, and $lib_version__patch as numbers.
It never adds them to another library's $lib. A minimized $feature_flag_called event keeps $lib and $lib_version but not the three version parts.
The two 0.x.x paths filled these properties in other ways:
- The default 0.x.x path (V0). It also added these properties before
before_send, but one key at a time, so a$libyou set on its own got the SDK's$lib_versionand version parts. In 1.x.x it doesn't. That path also kept anull, empty, or non-string$libas sent, where 1.x.x replaces it. - The 0.x.x
capture-v1path. It didn't add these properties, so PostHog set them from the header.
The mcp feature sets $lib to posthog-rs-mcp and $lib_version to the crate version on its events, and PostHog stores both. 0.x.x without capture-v1 also stored posthog-rs-mcp, and added the three version parts, which 1.x.x doesn't send on MCP events.
To label MCP events as another library, set $lib and $lib_version in the McpOptions hook or the client's before_send. Removing $lib in either hook makes the event report posthog-rs.
$mcp_interface is mcp on every MCP event.
Check dropped events
- Empty names. The SDK sends an event with an empty name, and PostHog drops it with the per-event result
missing_event_name. PostHog's other server SDKs drop it before sending. - Long names. PostHog drops an event whose name is over 200 UTF-8 bytes, with the per-event result
event_name_too_long. Legacy capture had no limit on event name length. NaNand infinite numbers. The SDK sends aNaNor infinite number in a property asnull, as in 0.x.x, and keeps the event. Anullin$setclears that person property.
Each per-event result reaches on_error, or the CaptureSummary of an immediate method.
The SDK sends $session_id and $window_id as top-level fields of the event, because capture reads them there and requires strings. The value's type decides what the SDK sends:
- A string. The SDK sends it unchanged, including an empty string.
null. It counts as unset, and the SDK drops it without a warning.- Any other value. The SDK drops it and logs a warning for each drop. The warning names the key and the value's type, never the value. In 0.x.x without
capture-v1, the SDK sent any value as a property.
Check batch sizes
The regular capture and capture_batch methods remain fire-and-forget. They enqueue events for the background worker, which batches and retries delivery.
capture_immediate and capture_batch_immediate still bypass the queue and return a CaptureSummary after reaching a terminal result.
- Analytics batches. The background worker now splits each analytics batch into requests of at most 5 MiB of serialized events. A batch of large events no longer exceeds capture's 10 MiB request limit and fails whole.
- Large events. A single event larger than 5 MiB is sent on its own.
before_send. It still runs when a batch is sent.- Immediate batches. A batch passed to
capture_batch_immediateis still sent as one request.
Check compression
CaptureCompression::Gzip, Deflate, Br, and Zstd now all apply their corresponding Content-Encoding. In older default V0 builds, only gzip was supported, and selecting another variant could send an uncompressed body.
Check any proxy or WAF in front of PostHog before you enable Brotli or Zstandard.
Check exceptions
- Debug images.
$debug_imageslists only images with a debug ID that a sent stack frame points into. In 0.x.x it could also list an image that only a trimmed frame pointed into. - Trace IDs. A
$trace_idor$span_idyou set in the exception's properties now wins over the trace context provider. Setting either one stops the SDK adding both provider IDs. - The
trace_contextoption.CaptureExceptionOptions::trace_contextstill wins over both.
Update error handling
The capture v1 endpoint returns a result for each event.
CaptureSummary::not_persisted() and CaptureSummary::all_persisted() now use those per-event results. In 0.x.x, the V0 path reported a successful 2xx as fully persisted without per-event confirmation.
If your application advances durable state after capture_immediate, check both that submitted() equals the number of intended events and that all_persisted() is true. Disabled clients and fully before_send-filtered batches submit no events but still report all_persisted() as true.
- Billing limits. HTTP
402means the whole request is over the billing limit. - Product quotas. A product quota drops single events inside a
200, as a per-eventdropsuch asllm_events_over_quota. - Logs without
on_error. Without a hook the SDK logs one aggregate warning per batch with drop and retry totals. - Drop and retry reasons. To log every drop and retry reason, call
CaptureFailure::verdict_summary()in anon_errorhook. It returns one line such asdrop/invalid_options=2, retry/not_persisted=1. - Captures inside
on_error. The hook must not call back into the SDK (capture,flush, orshutdown), because an event sent while handling a failure can fail again and loop. - Immediate methods. They never call
on_error. - Drops that skip
on_error. Queue-full andbefore_senddrops don't reachon_error.
During shutdown, the SDK makes one final attempt per batch:
- A retryable failure. If that attempt gets a network error, a retryable HTTP status, or a per-event
retryresult while the batch still has attempts left, the SDK drops those events instead of retrying them. - The timeout. The SDK also drops any events left when
shutdown_timeout_msruns out. - How these drops are reported. They're logged with a warning that names the endpoint, and they don't reach
on_error, as in 0.x.x. - A batch out of attempts. A batch that has used all its
max_capture_attemptsfails as usual and reacheson_error.
Check retries
The SDK retries transient request failures. From a partial response, it retries only the events with retryable results.
| Behavior | 0.x.x (V0) | 1.x.x |
|---|---|---|
Capture attempts (max_capture_attempts) | 3 by default | 4 by default |
First retry wait (retry_initial_backoff_ms) | 200 ms | 100 ms |
| Statuses retried | 429 only with Retry-After, never 404 | Network errors and HTTP 404, 408, 429, 500, 502, 503, and 504 |
First remote /flags retry wait | 200 ms by default | 300 ms |
In 0.x.x, the V0 path retried a 429 only when it had a Retry-After header, and never retried a 404. In 1.x.x, every other status is terminal.
In 0.x.x, remote /flags retries used the capture retry options, with a first wait of 200 ms by default. In 1.x.x, they wait 300 ms before the first retry and double up to 30 s. They no longer use the capture retry options.
In 1.x.x each later wait doubles up to retry_max_backoff_ms, 30 s by default. Each capture retry wait varies at random by up to 25% either way, so clients that fail together don't retry together.
A Retry-After header is still the minimum wait, capped at retry_max_backoff_ms as in 0.x.x. The SDK still honors it for retryable statuses and retry results.
The capture retry options apply to capture and capture_ai. feature_flags_request_max_retries still sets how many /flags retries the SDK makes.
Capture itself doesn't return 429, but a proxy in front of it can.
Follow ups
Rename the crate
1.x.x publishes the SDK as posthog. New applications should depend on posthog = "1" and import posthog.
Existing applications can use posthog-rs = "1" and keep their posthog_rs imports. That package forwards every feature and re-exports the same implementation, types, and global state.
The tracing target is posthog in both crates (see Update log filters).
Move to event options
Capture v1 reads per-event processing controls, such as person profile processing, from an options map that is sent next to properties. Set them with Event::insert_option, or with CaptureExceptionOptions::option for exceptions:
- Both lanes. Options work the same on
captureandcapture_ai. - Every event in a request. To set an option on every event in a request, use
RequestContext::option(see Check request context). An option the event sets, other thannull, wins over it. A contextprocess_person_profiledoesn't reach identify-style events whose distinct ID the SDK didn't generate. - Keys and values. Keys are strings and values are any JSON value.
- New options. The SDK sends options as given, so a new option that PostHog adds needs no SDK upgrade. PostHog validates them (see Check option values).
Each option replaces a legacy option property:
| Option | Replaces |
|---|---|
process_person_profile | $process_person_profile |
cookieless_mode | $cookieless_mode |
disable_skew_correction | $ignore_sent_at |
product_tour_id | $product_tour_id |
Legacy option properties still work, but an option overrides its legacy property. Use options.
For the changes every capture v1 SDK shares, such as event options, limits, and per-event results, see the capture v1 API reference.
Add MCP event options
MCP events from the mcp feature take options from two places:
- The callback. The
McpOptionsevent_optionscallback runs for each request. - The manual API.
ToolCallRequest::event_optionsets an option on one call. - Precedence. The call's own option wins over the callback's, and both win over the request context.
- Anonymous events. An anonymous MCP event keeps
process_person_profile: false. - Hooks. The
McpOptionshook and then the client'sbefore_sendsee the result and can change it.
Set the callback in McpOptionsBuilder, or call event_option on a ToolCallRequest:
Send AI events with capture_ai
Use the capture_ai family for LLM analytics events. Those are $ai_generation, $ai_span, $ai_trace, $ai_embedding, and the other $ai_* names PostHog's LLM analytics product defines.
If you send $ai_ events with capture, switch them to capture_ai:
For now the capture v1 analytics endpoint still accepts $ai_ events sent through capture, but this is temporary.





