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.

6.6 KB
Raw Blame
use axum::http::HeaderValue;

// ---------------------------------------------------------------------------
// HTTP response header values
// ---------------------------------------------------------------------------

/// Retry-After value (seconds) sent on retryable error responses (408, 5xx).
/// SDKs are expected to layer their own jittered exponential backoff on top of this floor.
pub const DEFAULT_RETRY_AFTER_SECS: HeaderValue = HeaderValue::from_static("1");

// ---------------------------------------------------------------------------
// Route paths
// ---------------------------------------------------------------------------

/// Primary route path for the v1 events endpoint.
pub const CAPTURE_V1_PATH: &str = "/i/v1/analytics/events";

/// Trailing-slash variant registered so both URL forms resolve to the same handler.
pub(super) const CAPTURE_V1_PATH_TRAILING: &str = "/i/v1/analytics/events/";

/// Primary route path for the v1 endpoint on the AI lane. Served only by
/// `CaptureMode::Ai`; `crate::router` owns the mode gating and
/// [`super::router::ai_routes`] the rationale.
pub const CAPTURE_V1_AI_PATH: &str = "/i/v1/ai/events";

/// Trailing-slash variant registered so both URL forms resolve to the same handler.
pub(super) const CAPTURE_V1_AI_PATH_TRAILING: &str = "/i/v1/ai/events/";

/// Every path the v1 batch handler serves. `pin_static_path` resolves a
/// request's `MatchedPath` against this list to the `&'static str` label the
/// request's metrics and warnings carry.
pub(super) const CAPTURE_V1_PATHS: &[&str] = &[
    CAPTURE_V1_PATH,
    CAPTURE_V1_PATH_TRAILING,
    CAPTURE_V1_AI_PATH,
    CAPTURE_V1_AI_PATH_TRAILING,
];

// ---------------------------------------------------------------------------
// Metrics keys
// ---------------------------------------------------------------------------

/// Counter tracking parsed events, labeled valid vs malformed.
pub(super) const CAPTURE_V1_PARSED_EVENTS: &str = "capture_v1_parsed_events";

/// Counter for events rerouted to the historical ingestion destination.
pub(super) const CAPTURE_V1_EVENTS_REROUTED_HISTORICAL: &str =
    "capture_v1_events_rerouted_historical";

/// Counter for events dropped (e.g. due to event restrictions).
pub(super) const CAPTURE_V1_EVENTS_DROPPED: &str = "capture_v1_events_dropped";

/// Counter for events marked as quota-limited, labeled by resource bucket.
pub(crate) const CAPTURE_V1_EVENTS_QUOTA_LIMITED: &str = "capture_v1_events_quota_limited";

/// Counter for events rerouted to the overflow topic by the burst limiter.
pub(super) const CAPTURE_V1_OVERFLOW_ROUTED: &str = "capture_v1_events_rerouted_overflow";

/// Counter/gauge key for the per-token global rate limiter.
pub(crate) const CAPTURE_V1_RATE_LIMITER: &str = "capture_v1_rate_limiter";

/// Detail tag for events flagged by the per-token:distinct_id rate limiter.
/// Matches the OpenAPI BatchEntryStatusError example for `result: warning`.
pub(super) const DETAIL_PERSON_PROCESSING_DISABLED: &str = "person_processing_disabled";

/// Detail tag for events dropped by the event restriction service.
pub(super) const DETAIL_EVENT_RESTRICTION_DROP: &str = "event_restriction_drop";

/// Detail tag for batches dropped by an Import-mode deployment because they
/// were not flagged `historical_migration: true`.
pub(super) const DETAIL_NON_HISTORICAL_DROP: &str = "non_historical_import_drop";

/// Detail tag for events dropped by an AI-mode deployment because they are not
/// on the AI lane. Same tag as the `misrouted_event` ingestion warning it emits.
pub(super) const DETAIL_MISROUTED_EVENT: &str = "misrouted_event";

/// Detail tag for events dropped because an expected option's value is unreadable.
pub(super) const DETAIL_INVALID_OPTIONS: &str = "invalid_options";

/// Detail tag for AI-lane events dropped because the project is over its
/// byte budget.
pub(super) const DETAIL_AI_BYTE_RATE_LIMITED: &str = "ai_byte_rate_limited";

/// Detail tag for AI-lane events dropped for exceeding the deployment's
/// per-event size ceiling.
pub(super) const DETAIL_AI_EVENT_TOO_BIG: &str = "ai_event_too_big";

// ---------------------------------------------------------------------------
// Validation limits
// ---------------------------------------------------------------------------

/// Maximum allowed length for an event name; longer names are rejected.
pub(crate) const CAPTURE_V1_MAX_EVENT_NAME_LENGTH: usize = 200;

/// Maximum allowed length for a distinct_id value; longer IDs are rejected.
pub(crate) const CAPTURE_V1_DISTINCT_ID_MAX_SIZE: usize = 200;

// ---------------------------------------------------------------------------
// Illegal distinct_id values
// ---------------------------------------------------------------------------

/// Known-bad distinct_id values that indicate a bug or misconfiguration in the
/// sending SDK. Ported from the Node.js ingestion pipeline
/// (nodejs/src/common/persons/person-utils.ts) with
/// additions from the new #ingestion-reports feed.
///
/// All comparisons are case-insensitive after trimming whitespace, which is a
/// deliberate simplification over Node.js (which splits into case-sensitive and
/// case-insensitive sets).
pub(super) const ILLEGAL_DISTINCT_IDS: &[&str] = &[
    "0",
    "00000000-0000-0000-0000-000000000000",
    "[object object]",
    "anonymous",
    "anonymous-user",
    "backend",
    "distinct_id",
    "distinctid",
    "email",
    "false",
    "guest",
    "id",
    "nan",
    "none",
    "not_authenticated",
    "null",
    "system",
    "true",
    "undefined",
    "user",
];

// ---------------------------------------------------------------------------
// Timestamp normalization
// ---------------------------------------------------------------------------

/// Events whose timestamp, after any skew correction, is more than 23 hours in
/// the future (in milliseconds) are clamped to server `now`.
pub(super) const FUTURE_EVENT_HOURS_CUTOFF_MS: i64 = 23 * 3600 * 1000;

/// Counter for adjustments applied to accepted events (label: reason).
/// Counts adjustments, NOT unique events — a single event may trigger more
/// than one reason emission.
pub(super) const CAPTURE_V1_EVENT_ADJUSTMENTS_APPLIED: &str =
    "capture_v1_event_adjustments_applied";

/// Counter for non-drop event-restriction actions applied (label: action).
pub(super) const CAPTURE_V1_EVENTS_RESTRICTED: &str = "capture_v1_events_restricted";

/// Counter for per-request batch outcome mix (labels: outcome, path).
pub(super) const CAPTURE_V1_BATCH_OUTCOMES: &str = "capture_v1_batch_outcomes";

/// Histogram for end-to-end processing time (parsing through publish).
pub(super) const CAPTURE_V1_PROCESSING_DURATION_SECONDS: &str =
    "capture_v1_processing_duration_seconds";