Client

Initialization

Sentry.init(options) MUST create a Client, configure its transport, and set up integrations. The Client is then set on the global scope, replacing the NoOpClient.

Before Sentry.init() is called, a NoOpClient MUST be present on the global scope. (since 2.0.0)

SDKs MUST accept an empty DSN as valid configuration. If initialized with an empty or missing DSN, the SDK MUST NOT send any data over the network. Depending on the platform, the SDK MAY reduce its runtime footprint to a minimum.

Calling Sentry.init() multiple times is permitted for testing. Behavior in production beyond application startup is undefined.

Active State

The Client is considered active when it has a configured transport. When active, the Client processes captured events through the event pipeline.

Shutdown

Both methods MUST block for at most timeout seconds. If the transport includes a TelemetryProcessor, flushing MUST first forward all buffered items to the transport, then flush the transport itself.

A Client MUST always be available — getClient() MUST NOT return null.

Client resolution walks the scope chain:

1. Check the current scope
2. Check the isolation scope
3. Check the global scope
4. Fall back to NoOpClient (should not happen if init() was called)

Users MAY bind a different Client to any scope via scope.setClient(client).

See Scopes: Client Resolution for details.

When captureEvent, captureException, or captureMessage is called, the Client processes the event through the following pipeline. The event MAY be discarded at any stage, stopping further processing.

1. Disabled check: If the SDK is disabled (no transport / no DSN), discard immediately.
2. Scope application and event processors: Obtain the current, isolation, and global scopes, then apply in this order:
   1. Merge scope data onto the event in the defined order. Scope data MUST be merged before event processors run, so processors observe the fully populated event.
   2. Invoke event processors — scoped first, then global, each in registration order. Any processor returning null discards the event (client report reason: event_processor).
   3. Discard events matching ignoreErrors (client report reason: event_processor). SDKs MAY implement this as an event processor, in which case it runs as part of the previous step.
3. before_send hook: Invoke the user-configured callback. Returning null discards the event (client report reason: before_send). This hook MUST only apply to error events. For transactions, use before_send_transaction. For logs, use before_send_log. See Hooks for details.
4. Session update: SDKs that implement Sessions MUST update the current session by incrementing its errors count or setting the appropriate status. SDKs without session support skip this step.
5. Sampling: Apply the configured sample_rate. Events MAY be randomly discarded. When discarded, the Client MUST record a client report with discard reason sample_rate.
6. Transport: Pass the event to the transport (or TelemetryProcessor). The transport MAY discard due to missing DSN, full queue, or rate limiting.

Ignored exception types, event processors, and before_send are developer-controlled filters: an event they discard MUST NOT update the session, because the developer chose to ignore it. Sampling and the transport discard events to save quota, so they MUST NOT prevent the session update — a sampled-out event still counts toward release health. This is the only reason sampling runs after before_send.

SDKs without session support MAY instead apply sampling immediately after the disabled check. With no session to update, where sampling runs does not affect release health, and sampling early skips event processors and before_send for events that will never be sent. The sample_rate client report is REQUIRED either way.