Hooks
Client lifecycle hooks, the on/emit subscription system, and user-facing hooks like before_send and before_breadcrumb.
The Client supports several hook mechanisms for extensibility:
- Lifecycle hooks (
on/emit) — an internal event subscription system primarily for integration authors before_send— a user-facing callback for modifying or discarding error eventsbefore_send_transaction— a user-facing callback for modifying or discarding transaction eventsbefore_send_check_in— an optional callback for modifying or discarding check-in eventsbefore_breadcrumb— a user-facing callback for modifying or discarding breadcrumbs
Related specs:
- Client — event pipeline and capture methods
- Configuration —
before_sendandbefore_breadcrumboptions
The Client SHOULD support an event subscription system for fine-grained extensibility beyond before_send and event processors. This is primarily an internal API for integration authors. (See RFC 0034.)
interface Client { on(hookName: string, callback: (...args: unknown[]) => void): void; emit(hookName: string, ...args: unknown[]): void; } Hooks are stateless and called in registration order. Data passed into hooks MAY be mutated by callbacks. Available hooks vary by SDK but may include:
startSpan/finishSpan— span lifecyclebeforeEnvelope— last chance to inspect/modify outgoing envelopesstartSession/endSession— session lifecycle
This system complements — not replaces — the before_send hook and event processors. Use hooks when integrations need to react to lifecycle events that are not part of the event pipeline (e.g., span creation).
Hook called with the event (and on some platforms the hint) that allows the user to decide whether an event should be sent or not. This can also be used to further modify the event. This hook MUST only apply to error events. Other event types like transactions, check-ins, and feedbacks MUST NOT go through beforeSend — they have their own dedicated hooks.
In the event pipeline, before_send is invoked after scope application and event processors. Returning null discards the event (client report reason: before_send).
Hook called with the transaction event (and on some platforms the hint) that allows the user to decide whether a transaction should be sent or not. This can also be used to further modify the transaction event. SDKs SHOULD support this hook.
This hook MUST only apply to transaction events. Returning null discards the transaction.
SDKs MAY implement a dedicated beforeSendCheckIn hook that applies only to check-in events. Check-in events MUST NOT go through the beforeSend hook.
See the Check-Ins spec for full details.
| Version | Date | Summary |
|---|---|---|
1.0.0 | 2025-02-24 | Initial spec, extracted from client spec v2.1.0 and expected features |
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").