Add the Context

Custom contexts allow you to attach arbitrary data to events. You cannot search for these, but you can view them on the questions page:

If you want to be able to search for custom data, you need to use tags.

To configure additional context:

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetExtra("character.name"."Mighty Fighter")})Copy the code

Note that the external value of the context must be a Dictionary /map/object, while the internal value can be arbitrary.

When sending context, be aware of the maximum payload size, especially if you want to send the entire application state as additional data. Sentry does not recommend this approach because application state can be very large and can easily exceed Sentry’s maximum 200kB on a single event payload. When this happens, you receive HTTP Error 413 Payload Too Large as the server response, or (when you send keepalive: True when set to fetch), the request will always be pending (for example, in Google Chrome).

Sentry will do its best to accommodate the data you send, but Sentry will trim large context payloads or truncate them entirely.

Refer to the developer documentation on SDK data handling for more details.

Additional Data, Additional Data

If you encounter any use of “extra” (SetExtra in code) or “Additional Data” (Additional Data in user interface), mentally replace it with context. Most SDKS don’t recommend using Extra and use context instead.

Identify users

Users contain key information that constitutes a unique identity in Sentry. Each option is optional, but one must exist for the Sentry SDK to capture the user:

id

Your internal user identifier.

username

The user name. Often used as a better label than an internal ID.

email

Substitution (or addition) of the user name. Sentry knows email addresses and can display things like Gravatars and unlock messaging.

ip_address

IP address of the user. If the user is not authenticated, Sentry uses the IP address as the user’s unique identifier. Sentry will attempt to extract this information, if any, from the HTTP request data.

Identify users:

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetUser(sentry.User{Email: "[email protected]"})})Copy the code

Additional key/value pairs can be specified as metadata, and the Sentry SDK stores these key/value pairs with the user.

Custom labels

Tags are key/value string pairs that are both indexable and searchable. Tags have powerful UI features, such as filters and tag maps. Tags also help you quickly access related events and see the label distribution of a group of events. Common uses of tags include host names, platform versions, and user languages.

We will automatically index all labels for an event, as well as the frequency and last time Sentry saw the label. We will also track the number of different tags and can help you identify hotspots for various issues.

It is easy to define tags and bind them to the current scope, ensuring that all future events within the scope contain the same tag:

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetTag("page.locale"."de-at");
})
Copy the code

Some labels are automatically set by Sentry. It is strongly recommended that you do not overwrite these tags and use your own name instead.

Once you start sending the tagged data, you’ll see it in the Sentry Web UI: filters in the sidebar of the Project page, summaries within events, and on the Tag page for aggregate events.

Bread crumbs

Sentry uses breadcrumbs to create clues about events before they happen. These events are very similar to traditional logging, but allow richer structured data to be recorded.

This page provides an overview of manual breadcrumb recording and customization. Learn more about what is displayed on the “Issue Details” page and how to filter bread crumbs for a quick fix.

:::tip Learn about SDK usage

Developers who want to modify the breadcrumb interface can learn more about this using the developer documentation dedicated to the breadcrumb interface. : : :

Hand breadcrumbs

You can manually add crumbs whenever something interesting happens. For example, breadcrumbs can be recorded manually if a user authenticates or has some other state change.

sentry.AddBreadcrumb(&sentry.Breadcrumb{
	Category: "auth",
	Message: "Authenticated user " + user.email,
	Level: sentry.LevelInfo,
});
Copy the code

Automatic bread crumbs

The SDK and its associated integrations automatically record many types of breadcrumbs. For example, the browser JavaScript SDK automatically logs all location changes.

Custom bread crumbs

The SDK allows you to customize breadcrumbs with before_breadcrumb hook. This hook passes the assembled breadcrumbs and, in some SDKS, an optional hint. This function can modify the breadcrumb, or decide to discard it entirely by returning NULL:

sentry.Init(sentry.ClientOptions{
	BeforeBreadcrumb: func(breadcrumb *sentry.Breadcrumb, hint *sentry.BreadcrumbHint) *sentry.Breadcrumb {
		if breadcrumb.Category == "auth" {
			return nil
		}
		return breadcrumb
	},
})
Copy the code

User feedback

When a user encounters an error, Sentry can collect additional feedback. This type of feedback is useful when you can usually render simple error pages (classic 500.html).

To gather feedback, use an embeddable JavaScript widget that requests and collects the user’s name, E-mail address, and description of what happened. Once you provide feedback, Sentry pairs it with the original event, giving you more insight into the problem.

The screen capture below provides an example of a “user feedback” widget, although your personalization may vary depending on your customization:

Collect feedback

To integrate widgets, you need to run the JavaScript SDK version 2.1 or higher. The widget will authenticate with your public DSN and then pass in the event ID generated on your back end.

If you want to use an alternative widget product, or if you don’t have a JavaScript front end, you can use the user feedback API.

Make sure you have the JavaScript SDK available:

<script
  src="https://browser.sentry-cdn.com/5.27.2/bundle.min.js"
  integrity="sha384-+69fdGw+g5z0JJXjw46U9Ls/d9Y4Zi6KUlCcub+qIWsUoIlyimCujtv+EnTTHPTD"
  crossorigin="anonymous"
></script>
Copy the code

You then need to call showReportDialog and pass in the generated event ID. This event ID is returned from all calls to CaptureEvent and CaptureException. There is also a function called LastEventId, which returns the ID of the most recently sent event.

<script>Sentry.init({ dsn: "https://[email protected]/0" }); Sentry.showReportDialog({ eventId: "{{ event_id }}"});</script>
Copy the code

Custom widgets

You can customize widgets to your organization’s needs, especially for localization purposes. All options can be passed through the showReportDialog call.

Override of Sentry’s automatic language detection (e.g. Lang =de)

Scope and Hub

After capturing the event and sending it to Sentry, the SDK merges the event data with additional information in the current scope. The SDK usually manages the scope automatically for you in the framework integration, and you don’t have to worry about them. However, you should know what scope is and how to use it to your advantage.

What is Scope and what is Hub

You can think of the Hub as the central point that our SDK uses to route events to Sentry. When you call init(), a hub is created with a client and a blank scope on it. The center is then associated with the current thread and will hold a scoped stack internally.

The scope will contain useful information that should be sent with the event. For example, context or breadcrumbs are stored on scope. When pushed into a scope, it inherits all data from the parent scope, and when it pops up, all changes are restored.

The default SDK integration will intelligently push and pop up scopes. For example, Web Framework integration creates and destroys scopes around your routes or controllers.

How do Scope and Hub work

When you start using the SDK, the Scope and Hub will be created automatically for you out of the box. Unless you are writing an integration or want to create or destroy scopes, you are unlikely to interact directly with the Hub. Scope, on the other hand, is more user-oriented. You can call configure-scope at any time to modify the data stored on that scope. For example, it is used to modify the context.

When a global function (such as capture_event) is called internally, Sentry finds the current Hub and asks it to catch an event. The hub then internally merges the event with the data of the topmost Scope.

Configure the Scope

The most useful operation when using scopes is the configure-scope function. It can be used to reconfigure the current range. For example, this can be used to add custom tags or notify Sentry about the currently authenticated user.

sentry.ConfigureScope(func(scope *sentry.Scope) {
	scope.SetTag("my-tag"."my value")
	scope.SetUser(sentry.User{
		ID: "42",
		Email: "[email protected]",})})Copy the code

This also applies to unsetting the user on logout:

To see what useful information can be associated with a scope, see the context documentation.

Local scope

We also support one-time push and scope configuration. This is often referred to as with-scope or push-scope, and is also useful if you only want to send data with a specific event. In the following example, we use this function to attach only one level and one label to a particular error:

sentry.WithScope(func(scope *sentry.Scope) {
	scope.SetTag("my-tag"."my value");
	scope.SetLevel(sentry.LevelWarning);
	// will be tagged with my-tag="my value"
	sentry.CaptureException(errors.New("my error"))})// will not be tagged with my-tag
sentry.CaptureException(errors.New("my error"))
Copy the code

While this example looks similar to configure-Scope, it is quite different because configure-Scope actually changes the scope of the current activity, so all subsequent calls to configure-Scope will retain those changes.

Using with-scope, on the other hand, creates a clone of the current scope and remains isolated until the function call completes. Thus, by calling clear on the scope, you can set context information here that you do not want to place elsewhere, or attach no context information at all, while the “global” scope remains unchanged.