The Sentry SDK captures errors, exceptions, crashes, transactions, and generally anything that goes wrong in your application in real-time. Once captured, the SDK enriches the data with contextual information that it gets from the application's runtime and sends all this data as an event to your Sentry account.
While Sentry adds a lot of this contextual data by default, we highly encourage you to add your custom data through the SDK. Multiple Sentry workflows and tools can be configured and fine-tuned based on this data, so adapting those to the way you work is very helpful in getting even more value out of Sentry.
Types of Data
The SDK allows you to set various types of data that are then attached to every event that occurs in your application. Generally, those data types are:
Unstructured Data - Includes additional data like
Extra data, and
Custom Contexts. While these fields are unsearchable, they enrich your events with information that will help you debug and resolve the associated issues.
Structured Data - Key/value pairs that are indexed and searchable, allowing you to search, filter, and query through all your events across projects, in addition to helping you debug specific issues. These include:
Custom Tags- A way to reflect key characteristics that apply to your applications, dev process, or business in your error data. These might include variants and flavors of your app, a user type, tenant ID, payment plan, and so on.
Environment- Predefined data fields available as SDK configuration options.
User Context- Comprised of a set of predefined data fields. Setting any one of those (when applicable) allows Sentry to construct a user identity and define user uniqueness.
Using Your Data
Adding custom structured data that is unique to your applications, users, and business logic enriches your data and provides valuable context to every event. You can also use that same data to customize Sentry workflows and adapt them to your precise needs. Let's look at those major workflows:
Targeted alerts are key to focusing attention when your app breaks and notifying exactly the people who can fix it. The more data you add to your events, the more flexibility you gain to create pinpointed alerts. The following data types can be incorporated in your alert rules by adding the relevant conditions to trigger the alert:
- User Context: Once a certain issue has impacted a defined threshold of unique users.
- Custom Tags: When events contain custom tag values that match your defined values.
- Environment: When events are occurring in a specific environment.
These can all come in handy in both issue and metric alerts. For instance:
Issue Alerts: The following rule will trigger a Slack message when a certain issue with level error or fatal, originating from my EMEA releases in my prod environment, impacts more than 50 enterprise end-users in one hour:
Metric Alerts: The following rule will trigger a Slack message if more than 50 enterprise end-users in one hour are impacted by warning level errors (from multiple issues) originating from my EMEA releases in my prod environment:
Learn more in Alerts.
Filter, Search, and Order Issues
On the Issues page, custom data allows you to:
- Filter issues according to your application's
environmentsusing the environment filter dropdown.
- Sort issues by the number of (unique) impacted
- Search through issues by your
user contextattributes, and
releaseids in the issue search bar.
Learn more in Search.
Discover is a powerful query engine that builds upon your data, allowing you to reveal patterns, anomalies, and deeper insights in the health of your entire system. With this in mind, the more (custom) data you add to your events, the more flexibility you'll gain in building queries that address your environments, releases, custom development, and business characteristics through tags, and the end-users impacted by those events.
For instance, the Discover query below displays all the errors (total of 143 events) that occurred in the production environment, distributed by the customer-type custom tag, and ordered by the uniquely impacted end users.
Learn more in Discover.
Ownership Rules allow you to target email notifications and automatically assign issues to members in your project teams by defining rules in your project settings or using code owners functionality. Ownership rules can be defined based on an error's origin
path of the files in the error's stack-trace, or an error's
Code owners functionality lets you import your GitHub or GitLab CODEOWNERS file, and then we assign issues according to those file paths.
You'll be able to reduce noise by pinpointing notifications to the right people and automatically assigning new issues to their proper owners. You can configure ownership rules in [Project] > Settings > Ownership Rules. Learn more in Ownership Rules.
Configuring the release version ID on the SDK will associate every error that happens in your application runtime with a specific release version of your code. This way, you know exactly when an error was introduced into your source code. It also unlocks these powerful features and workflows:
- Commit Tracking - With a release in place, Sentry can track which commits were involved with a release and the authors who made them.
- Resolve With Release - When you mark an issue as resolved in a specific release, new events of that issue occurring in previous releases will be ignored and will not trigger any notifications.
- Regression Notifications - If you marked an issue as resolved in a release and new events are still occurring in that same release or any future releases, Sentry will consider that a regression and will notify you.
- Release Health - Sentry can monitor the health of your releases by observing various metrics like user adoption, crash-free users and sessions, and others. (Not all release health features are available on all SDKs that support release health.)
Learn more in Releases.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").