: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
//! Registry of ingestion warning types emitted by Rust services.
//!
//! The `WarningType` enum — every registered type with its `as_str()` tag and
//! registry-declared `category()`/`severity()` — is generated at build time (see
//! `build.rs`) from `warning_types.generated.json`, which mirrors the whole
//! Node.js registry, the single source of truth for the warning taxonomy
//! (`nodejs/src/ingestion/common/ingestion-warning-types.ts`). The taxonomy is
//! producer-agnostic: which service emits which type is not registry data — each
//! producer references the variants it emits, and the message's `source` field
//! records who said it.
//!
//! `from_tag` is a hand-written allowlist mapping capture error tags to warning
//! types: only tags registered here ever produce a warning. Unknown or
//! deliberately excluded tags (auth/transport/server errors, intentional drops
//! like `dropped_performance_event`) map to `None` and emit nothing. The
//! allowlist's domain is welded by test to the registry's `captureProduced`
//! flags — the Node consumer's trust allowlist for the capture envelope —
//! since skew in either direction silently drops warnings: a flagged type
//! without an arm is never emitted, and an arm without the flag is emitted
//! but rejected at the consumer. An arm for a type removed from the registry
//! stops compiling.
// Brings in `pub enum WarningType` with `ALL`, `as_str`, `category`, and
// `severity`.
include!(concat!(env!("OUT_DIR"), "/warning_types.rs"));
impl WarningType {
/// Types capture emits directly, with no error tag behind them.
///
/// The tag route only reaches conditions capture already models as an
/// `Error` or a per-event drop detail. Two kinds of warning sit outside it:
///
/// * Ones that aren't failures at all. A rate-limited event is ingested
/// (degraded, not dropped), so there is no tag to map and inventing one
/// would mean inventing an error that never gets returned.
/// * Ones from a pipeline that has no tag vocabulary. The AI endpoints
/// reject via their own typed conditions, not `v1::Error`, so their tags
/// would be strings no `Error` ever produces. The replay endpoint is the
/// same case from the other direction: its conditions are `CaptureError`
/// variants v1 analytics never returns, so no `Error::tag()` names them.
///
/// Emit sites for these name the variant directly.
///
/// This list exists so the trust-allowlist invariant below can still be
/// airtight: `captureProduced` must equal "reachable by one of capture's two
/// emit routes", and without this the direct route would be invisible to it.
pub const DIRECT_EMIT: [Self; 9] = [
Self::HighVolumeDistinctId,
Self::DistinctIdTruncated,
Self::InvalidAiEvent,
Self::InvalidAiPayload,
Self::NoAiSpansIngested,
Self::MisroutedEvent,
Self::MissingSessionId,
Self::InvalidSessionId,
Self::MissingSnapshotData,
];
/// Map a capture error tag (`v1::Error::tag()` / per-event drop detail) to a
/// registered warning type. Returns `None` for anything not on the allowlist —
/// callers emit nothing in that case. Direct-emit types are deliberately
/// absent: see [`WarningType::DIRECT_EMIT`].
pub fn from_tag(tag: &str) -> Option<Self> {
match tag {
"missing_event_name" => Some(Self::MissingEventName),
"event_name_too_long" => Some(Self::EventNameTooLong),
"missing_distinct_id" => Some(Self::MissingDistinctId),
"distinct_id_too_large" => Some(Self::DistinctIdTooLarge),
"invalid_event_timestamp" => Some(Self::InvalidEventTimestamp),
"malformed_event_properties" => Some(Self::MalformedEventProperties),
"invalid_options" => Some(Self::InvalidOptions),
"empty_batch" => Some(Self::EmptyBatch),
"invalid_batch" => Some(Self::InvalidBatch),
"missing_event_uuid" => Some(Self::MissingEventUuid),
"invalid_event_uuid" => Some(Self::InvalidEventUuid),
"duplicate_event_uuid" => Some(Self::DuplicateEventUuid),
"message_size_too_large" => Some(Self::MessageSizeTooLarge),
// The v1 AI lane's per-event ceiling. v0 reports the same condition
// as `CaptureError::AiEventTooBig`, which already maps here, so
// moving AI traffic onto the v1 endpoint keeps the warning a
// project owner already sees for an oversized event. An alias, not
// a second route: `MessageSizeTooLarge` stays tag-derived, so the
// one-route-per-type invariant below is untouched.
"ai_event_too_big" => Some(Self::MessageSizeTooLarge),
_ => None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use rstest::rstest;
#[test]
fn capture_emit_routes_equal_the_capture_trust_allowlist() {
// Two hand-maintained answers to "which types does capture emit?" must
// stay equal: capture's emit routes here (`from_tag` plus
// `DIRECT_EMIT`) and the registry's `captureProduced` flags (the Node
// consumer's trust allowlist, carried through the artifact). Skew fails
// silently in production in either direction — a flagged type on
// neither route is never emitted; a type on a route without the flag is
// emitted and then rejected at the consumer's trust check.
//
// Comparing the variant itself (not just presence) pins each `from_tag`
// arm to the right type, so a mis-mapped tag can't hide behind an
// unrelated `Some`.
for warning in WarningType::ALL {
let tag_derived = WarningType::from_tag(warning.as_str()) == Some(warning);
let direct = WarningType::DIRECT_EMIT.contains(&warning);
assert_eq!(
tag_derived || direct,
warning.capture_produced(),
"{}: emit routes and captureProduced flag disagree — add the missing side",
warning.as_str()
);
// One route per type. Both would mean a warning capture can produce
// two ways, with the tag route silently winning wherever a tag is
// available, so its details would differ by call path.
assert!(
!(tag_derived && direct),
"{}: on both emit routes — pick one",
warning.as_str()
);
}
}
// Excluded on purpose: intentional drops, auth/transport/server errors, and
// ops-imposed drops are not data-quality signals for the v2 surface.
//
// "Post-validation" is not itself the test -- customer-actionable is.
// `event_restriction` is excluded because the operator caused it and the
// project owner cannot act on it; `ai_event_too_big` is included, after the
// same stage, because the customer sent an oversized event and v0 already
// tells them so.
#[rstest]
#[case::intentional_drop("dropped_performance_event")]
#[case::auth("invalid_api_token")]
#[case::auth_missing("missing_authorization")]
#[case::transport("payload_too_large")]
#[case::transport_decoding("request_decoding_error")]
#[case::transport_parsing("request_parsing_error")]
#[case::transport_encoding("unsupported_content_encoding")]
#[case::timeout("request_timeout")]
#[case::server("internal_error")]
#[case::server_unavailable("service_unavailable")]
#[case::billing("billing_limit_exceeded")]
#[case::post_validation("event_restriction")]
#[case::sink("rejected")]
#[case::unknown("some_future_tag")]
#[case::empty("")]
// Direct-emit types must stay off the tag route even though their name reads
// like a tag, or they'd be reachable both ways.
#[case::direct_emit("high_volume_distinct_id")]
fn from_tag_rejects_unregistered_tags(#[case] tag: &str) {
assert_eq!(
WarningType::from_tag(tag),
None,
"tag {tag:?} must not emit"
);
}
}