Telemetry Event Schema

Parapet emits telemetry as a public contract. Event names define the lifecycle seam, while metadata stays bounded and safe for downstream metrics, SLOs, and incident logic.

Versioning Contract

The telemetry event schema version is tied to the package version. Renaming or removing event names, measurements, or documented metadata fields is a semver-major change. Adding new bounded fields or measurements may be done in a minor release.

Label Safety

Phase 4 introduces a strict split between label-safe metadata and exact refs:

• Safe top-level metadata is limited to documented bounded fields such as integration, provider, channel, queue, pipeline_stage, outcome, failure_class, delay_bucket, retry_state, and fault_plane.
• Exact identifiers do not belong in top-level metadata. They are demoted into metadata.refs using _ref keys such as message_ref, delivery_ref, job_ref, or webhook_ref.
• Raw provider payloads, paths, tokens, and *_id values are not part of the public contract.

Async And Delivery Families

Delivery families

[:parapet, :delivery, :outbound]

Emitted when Parapet observes an outbound provider handoff attempt.

Measurements:

• count (integer) - Defaults to 1.
• duration_ms (integer) - Duration of the observed upstream step in milliseconds when available.

Metadata:

• integration - Adapter name such as :mailglass.
• provider - Provider or delivery backend.
• channel - Delivery channel such as :email or :notification.
• outcome - Usually :attempted at this seam.
• fault_plane - Usually :provider.
• refs - Optional exact identifiers such as message_ref or delivery_ref.

[:parapet, :delivery, :provider_feedback]

Emitted when a provider response or reconciliation step yields a bounded delivery outcome.

Measurements:

• count (integer)
• duration_ms (integer)

Metadata:

• integration
• provider
• channel
• outcome - Bounded delivery outcomes: attempted, provider_accepted, delivered, failed, and supported extensions such as bounced, complained, suppressed.
• failure_class - Small bounded reason classification when relevant.
• fault_plane - Usually :provider or :suppression.
• refs

[:parapet, :delivery, :webhook_ingest]

Emitted when callback or webhook processing is the meaningful delivery seam.

Measurements:

• count (integer)
• duration_ms (integer)
• delay_ms (integer) - Optional raw measurement for timing, not a label.

Metadata:

• integration
• provider
• channel
• outcome
• failure_class
• delay_bucket - Bounded bucket derived from delay, not a raw value.
• fault_plane - Usually :webhook.
• refs

Async families

[:parapet, :async, :stage]

Emitted for bounded async pipeline progress.

Measurements:

• count (integer)
• duration_ms (integer)

Metadata:

• integration
• provider - Optional when the upstream system has one.
• queue
• pipeline_stage
• outcome - Bounded async outcomes: started, succeeded, retryable_failed, discarded, delayed.
• retry_state - For example first_attempt, retrying, exhausted.
• fault_plane - Usually :worker.
• refs

[:parapet, :async, :backlog]

Emitted when the primary symptom is queue or backlog pressure.

Measurements:

• count (integer)
• delay_ms (integer) - Optional raw measurement for timing, not a label.

Metadata:

• integration
• provider
• queue
• outcome
• delay_bucket
• fault_plane - Usually :backlog.
• refs

[:parapet, :async, :callback]

Emitted when callback or reconciliation delay is distinct from internal backlog.

Measurements:

• count (integer)
• delay_ms (integer)

Metadata:

• integration
• provider
• queue
• pipeline_stage
• outcome
• delay_bucket
• fault_plane - Usually :webhook.
• refs

Semantic Guarantees

• provider_accepted is not the same as delivered.
• retryable_failed is not the same as discarded.
• Callback or reconciliation delay is not the same as queue backlog.
• Public metadata is intentionally narrower than the upstream integration payloads.