Context

Custom contexts allow you to attach arbitrary data to an event. Often, this context is shared among any issue captured in its lifecycle. You cannot search these, but they are viewable on the issue page:

Custom contexts as viewed on the Additional Data section of an event

The best way to attach custom data is with a structured context. A context must always be an object and its values can be arbitrary.

Then, use set_context and give the context a unique name:

The configureScope helper will setup the scope for all events being captured by the Sentry SDK.

Copied
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setContext('character', [
        'name' => 'Mighty Fighter',
        'age' => 19,
        'attack_type' => 'melee'
    ]);
});

If you need to modify the scope for a single event, you can use the withScope helper instead, which does not keep the scope changes made.

Copied
\Sentry\withScope(function (\Sentry\State\Scope $scope) use ($e): void {
    $scope->setContext('character', [
        'name' => 'Mighty Fighter',
        'age' => 19,
        'attack_type' => 'melee'
    ]);

    \Sentry\captureMessage('The fighter is out of energy!');
    // or: \Sentry\captureException($e);
});

There are no restrictions on context name. In the context object, all keys are allowed except for type, which is used internally.

Learn more about conventions for common contexts in the contexts interface developer documentation.

When sending context, consider payload size limits. Sentry does not recommend sending the entire application state and large data blobs in contexts. If you exceed the maximum payload size, Sentry will respond with HTTP error 413 Payload Too Large and reject the event.

The Sentry SDK will try its best to accommodate the data you send and trim large context payloads. Some SDKs can truncate parts of the event; for more details, see the developer documentation on SDK data handling.

Additional Data is deprecated in favor of structured contexts.

Sentry used to support adding unstructured "Additional Data" via set_extra.

Help improve this content
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").