From 38bf76f22bc7e1449a3c8754df33c33b2fb8dad4 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Tue, 4 Mar 2025 21:58:00 -0800 Subject: [PATCH 1/7] Add llms.txt to docs --- docs/llms.txt | 11755 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 11755 insertions(+) create mode 100644 docs/llms.txt diff --git a/docs/llms.txt b/docs/llms.txt new file mode 100644 index 0000000000000..49df6191cb1be --- /dev/null +++ b/docs/llms.txt @@ -0,0 +1,11755 @@ +# https://docs.sentry.io/ llms.txt + +- [Home](https://docs.sentry.io/) +- [Account Settings](https://docs.sentry.io/account/) +- [Auth Tokens](https://docs.sentry.io/account/auth-tokens/) + +# Auth Tokens + +## Learn about the different kinds of Auth Tokens Sentry provides, and when to use which. + +Auth tokens (short for _authentication tokens_) are a way to authenticate with Sentry. They are similar to passwords but are designed for programmatic interaction with Sentry. Some examples of what you would use auth tokens for include: + +- Uploading Source Maps during your CI build +- Using [Sentry CLI](https://docs.sentry.io/cli/) to interact with Sentry +- Using the [Sentry API](https://docs.sentry.io/api/auth/) + +Each auth token is created with a certain set of permissions and scopes which are mapped to the Sentry API's [Permissions & Scopes](https://docs.sentry.io/api/permissions/). Some types of auth tokens have set permissions that can't be edited, while others can be customized upon token creation and edited later. + +We recommend using a separate auth token for each use case. For example, you would use a different auth token to upload source maps than the one you use with Sentry CLI. This has the benefit that if an auth token is compromised, you can revoke that auth token without impacting the rest of your workflow. + +## [Types of Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#types-of-auth-tokens) + +There are three key types of auth tokens in Sentry: + +- [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens): These tokens are bound to an organization, and have access to all projects within that organization. They have a limited set of permissions and are designed to be used in CI environments and with Sentry CLI. + +- [Internal Integrations](https://docs.sentry.io/account/auth-tokens/#internal-integrations): These tokens are bound to an organization, and have access to all projects within that organization. They can be created with a custom set of permissions, and are designed to be used in cases where organization auth tokens don't have sufficient access rights. + +- [User Auth Tokens](https://docs.sentry.io/account/auth-tokens/#user-auth-tokens): These tokens are bound to a user, and have access to all organizations and projects that user has access to. + + +### [When Should I Use Which?](https://docs.sentry.io/account/auth-tokens/\#when-should-i-use-which) + +For most scenarios, we recommend using [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens). They are designed to be used in CI environments and have a limited set of permissions. This means that if the place you stored the auth token is compromised, the attacker can only do limited damage. + +Organization auth tokens permissions aren't customizable. They are set to allow most CI-related tasks, without any unnecessary permissions. + +[Internal Integrations](https://docs.sentry.io/account/auth-tokens/#internal-integrations) should be used when you need full API access (which the organization auth tokens cannot grant), and you want to interact with the Sentry API on behalf of an organization. For example, to programmatically create a new project, you would use an internal integration. + +Permissions for auth tokens created as part of an internal integration are customizable and editable. + +[User Auth Tokens](https://docs.sentry.io/account/auth-tokens/#user-auth-tokens) should be used to interact with the Sentry API on behalf of a user. For example, to fetch all issues for a user, you would use a user auth token. We don't recommend using user auth tokens for CI tasks because if the user who created the token is removed from the Organization, the token will stop working. + +User auth token permissions are customizable but cannot be edited later. + +### [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#organization-auth-tokens) + +[Organization auth tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) can be created in [sentry.io](https://sentry.io/) on the **Auth Tokens** page under **Settings > Developer Settings > Auth Tokens**. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-auth-tokens-overview-EVXIT75D.png%231200x562&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-auth-tokens-overview-EVXIT75D.png) + +They can also be generated on certain pages of Sentry's docs if you're signed in, and by using the Sentry Wizard to configure uploading source maps. + +Organization auth token names are generated for you unless you create the token through the Sentry UI. This name is only used for display purposes - it helps to identify an auth token in case you want to revoke it later. You can change the name for an organization auth token at [sentry.io](https://sentry.io/) on the **Edit Auth Token** page under **Settings > Developer Settings > Auth Tokens**. + +For security reasons, organization auth tokens are only visible _once_, right after you create them. If you lose the auth token, you will have to create a new one. This means you can't see the full token on the overview page or on the token detail page, you can only see the last characters of the token to help identify it. + +Any user can create organization auth tokens for any of their organizations. This allows any user (not only organization owners) to configure a Sentry SDK and set up CI processes by creating and using organization auth tokens. Since organization auth tokens have limited access, there is limited potential for abuse. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-auth-token-create-C7PVFF4S.png%231200x338&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-auth-token-create-C7PVFF4S.png) + +All owners of the organization will receive a security email when a new organization auth token is created and can revoke these tokens at any point. _Only_ organization owners & managers can revoke organization auth tokens . + +### [Internal Integrations](https://docs.sentry.io/account/auth-tokens/\#internal-integrations) + +We recommend only using an internal integration when you want to interact with the Sentry API on behalf of an organization. See Sentry's API [Authentication](https://docs.sentry.io/api/auth/) docs for more information on how to do this. + +To get started, see our docs on [Internal Integrations](https://docs.sentry.io/organization/integrations/integration-platform/). + +### [User Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#user-auth-tokens) + +[User auth tokens](https://sentry.io/settings/account/api/auth-tokens/) can be created in [sentry.io](https://sentry.io/) on the **User Auth Tokens** page under the Account dropdown in the top left. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-tokens-menu-7RYBD4GV.png%23500x572&w=1080&q=75)](https://docs.sentry.io/mdx-images/user-auth-tokens-menu-7RYBD4GV.png) + +User auth tokens can be created by any user, and are bound to that user. The tokens can be given permissions to all organizations and projects that user has access to. This means a user auth token's _maximum_ scope is all the scopes that the user has access to for a given organization. A user auth token cannot exceed the permissions of the user who created it. See [Organization and User Management](https://docs.sentry.io/organization/membership/) for more details on how permissions work in Sentry. + +When you create a new user auth token, you can select which [scopes](https://docs.sentry.io/api/permissions/) the token should have in the UI: + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-token-create-ZKQIPVXA.png%232396x1404&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-token-create-ZKQIPVXA.png) + +Currently, you can view user auth tokens in the UI after creating them. This is a legacy behavior that may change in the future. We recommend only using each user auth token once, and creating a new token for each use case. Any user can always revoke any of their user auth tokens. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-tokens-overview-R7WDNH5A.png%231200x484&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-tokens-overview-R7WDNH5A.png) + +We recommend only using a user auth token to interact with the Sentry API on behalf of a user. See Sentry's API [Authentication](https://docs.sentry.io/api/auth/) docs for more information on how to do this. + +[Previous\\ +\\ +Account Preferences](https://docs.sentry.io/account/user-settings) + +[Next\\ +\\ +Organization Settings](https://docs.sentry.io/organization) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/auth-tokens/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=qzenzbb76tqy)Ship it, break it, fix it—live! Hands-on workshop debugging with Lazar. [RSVP for March 12.](https://sentry.io/resources/instrument-monitor-fix-workshop/) + +× + +# Welcome to Sentry Docs + +Sentry provides end-to-end distributed tracing, enabling developers to identify and debug performance issues and errors across their systems and services. + +![Sentry's hero image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fhome_illustration.65d91c38.png&w=3840&q=75) + +## Most Viewed Sentry SDKs + +[![javascript-nextjs icon](https://docs.sentry.io/_next/static/media/nextjs.32864a1b.svg)Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs/) + +[![javascript-react icon](https://docs.sentry.io/_next/static/media/react.bdd05676.svg)React](https://docs.sentry.io/platforms/javascript/guides/react/) + +[![php-laravel icon](https://docs.sentry.io/_next/static/media/laravel.bb692921.svg)Laravel](https://docs.sentry.io/platforms/php/guides/laravel/) + +[![javascript-node icon](https://docs.sentry.io/_next/static/media/nodejs.852a24fa.svg)Node.js](https://docs.sentry.io/platforms/javascript/guides/node/) + +[![python icon](https://docs.sentry.io/_next/static/media/python.94740f0e.svg)Python](https://docs.sentry.io/platforms/python/) + +[![react-native icon](https://docs.sentry.io/_next/static/media/react-native.29a585c0.svg)React Native](https://docs.sentry.io/platforms/react-native/) + +## All SDKs Supported by Sentry + +If you use it, we probably support it. + +![android icon](https://docs.sentry.io/_next/static/media/android.b3576036.svg)Android + +![apple icon](https://docs.sentry.io/_next/static/media/apple.e4583c4c.svg)Apple + +[![dart icon](https://docs.sentry.io/_next/static/media/dart.5c7f1c51.svg)Dart](https://docs.sentry.io/platforms/dart/) + +![elixir icon](https://docs.sentry.io/_next/static/media/elixir.7b73ceba.svg)Elixir + +[![flutter icon](https://docs.sentry.io/_next/static/media/flutter.a90468ce.svg)Flutter](https://docs.sentry.io/platforms/flutter/) + +![go icon](https://docs.sentry.io/_next/static/media/go.61b8c940.svg)Go + +[![godot icon](https://docs.sentry.io/_next/static/media/godot.27321999.svg)Godot Engine](https://docs.sentry.io/platforms/godot/) + +![java icon](https://docs.sentry.io/_next/static/media/java.acc28a20.svg)Java + +![javascript icon](https://docs.sentry.io/_next/static/media/javascript.bcdb1761.svg)JavaScript + +![kotlin icon](https://docs.sentry.io/_next/static/media/kotlin.3786f5aa.svg)Kotlin + +![native icon](https://docs.sentry.io/_next/static/media/nativec.2290b21b.svg)Native + +![dotnet icon](https://docs.sentry.io/_next/static/media/dotnet.5140e140.svg).NET + +![php icon](https://docs.sentry.io/_next/static/media/php.8ad32900.svg)PHP + +[![powershell icon](https://docs.sentry.io/_next/static/media/powershell.8794be24.svg)PowerShell](https://docs.sentry.io/platforms/powershell/) + +![python icon](https://docs.sentry.io/_next/static/media/python.94740f0e.svg)Python + +[![react-native icon](https://docs.sentry.io/_next/static/media/react-native.29a585c0.svg)React Native](https://docs.sentry.io/platforms/react-native/) + +![ruby icon](https://docs.sentry.io/_next/static/media/ruby.bdbd1ec3.svg)Ruby + +![rust icon](https://docs.sentry.io/_next/static/media/rust.2e576be7.svg)Rust + +[![unity icon](https://docs.sentry.io/_next/static/media/unity.2a861bdd.svg)Unity](https://docs.sentry.io/platforms/unity/) [![unreal icon](https://docs.sentry.io/_next/static/media/unreal.8100ceaa.svg)Unreal Engine](https://docs.sentry.io/platforms/unreal/) + +## Get to know us + +[![Rocket image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Frocket.b246cb46.png&w=128&q=75)\\ +\\ +**What is Sentry?** \\ +\\ +Application monitoring and debugging software considered “not bad” by 4 million developers.](https://docs.sentry.io/product/) [![Organization image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Forganization.8218fb60.png&w=128&q=75)\\ +\\ +**Organization settings** \\ +\\ +Information for setting up your organization's Sentry account.](https://docs.sentry.io/organization/) [![Calculator image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fpricing.ffb025fd.png&w=128&q=75)\\ +\\ +**Pricing & Billing** \\ +\\ +All about our pricing and billing structure.](https://docs.sentry.io/pricing/) [![Plug image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fapi.a101b39c.png&w=128&q=75)\\ +\\ +**API** \\ +\\ +APIs for accessing Sentry programmatically.](https://docs.sentry.io/api/) [![Terminal image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fcli.2909a9c8.png&w=128&q=75)\\ +\\ +**CLI** \\ +\\ +How to use ‘sentry-cli’ on the command line.](https://docs.sentry.io/cli/) [![Stamped paper image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fsecurity.7c52136a.png&w=128&q=75)\\ +\\ +**Security, Legal & PII** \\ +\\ +Security, compliance, and data-scrubbing processes.](https://docs.sentry.io/security-legal-pii/) [![Concept and references image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fconcepts-reference.3b9f1750.png&w=128&q=75)\\ +\\ +**Concepts & Reference** \\ +\\ +Core concepts that make Sentry, Sentry.](https://docs.sentry.io/concepts/) + +## Talk to us + +[![Chat bubble image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fchat-bubble.0c0f4dff.png&w=128&q=75)\\ +\\ +**Sentry Discord** \\ +\\ +Real talk in real time. Get in it.](https://discord.com/invite/sentry) [![Support image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fsupport.8b7cb019.png&w=128&q=75)\\ +\\ +**Support** \\ +\\ +See how we can help.](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=mqc11j9cbcoh)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/) + +# How to Write - Data Management + +The Data Management section of the content covers how customers can manage the data sent to Sentry using the SDK. We provide a parallel section in product, which focuses on the settings in [sentry.io](http://sentry.io/) a user can user to control data. A new framework can adopt the common content, which is stored in `/docs/platforms//common/data-management` \- feel free to peruse the files in that directory to answer any questions. + +Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. + +Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions if any questions arise by opening an issue on GitHub. + +## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#start-here) + +Determine if the page applies: + +- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. +- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting customers open an issue for the missing sample. + +### [Sensitive Data](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#sensitive-data) + +This file is `/sensitive-data/index.mdx`. It explains how to scrub or filter data within the SDK, so it's not sent with an event. + +For data scrubbing that the guide DOES NOT support, add the name of the guide to the `PlatformSection notSupported` statement, which ensures the content won't display. For example: + +`` + +Add the code sample to these directories: + +- `/src/platform-includes/configuration/before-send` +- `/src/platform-includes/sensitive-data/set-tag` +- `/src/platform-includes/sensitive-data/set-user` + +### [Debug Files](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#debug-files) + +This file is `/sensitive-data/debug-files.mdx`. It explains how to debug information files work for Sentry. + +For specific controls that the guide supports, add the name of the guide to the `PlatformSection supported` statement, which ensures the content displays. + +[Previous\\ +\\ +How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events) + +[Next\\ +\\ +How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-data-management.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=4uol10g7q80v)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) + +# Sentry CLI + +## Learn how to use the \`sentry-cli\` command line executable. + +For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms. + +[Previous\\ +\\ +Pricing & Billing](https://docs.sentry.io/pricing) + +[Next\\ +\\ +Installation](https://docs.sentry.io/cli/installation) + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=nvhm92pvf9r6)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data/) + +# Event Data + +## Learn about event data and how to configure Sentry workflows and tools to fine-tune the data sent to Sentry. + +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](https://docs.sentry.io/concepts/key-terms/enrich-data/\#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: + +1. **Unstructured Data** \- Includes additional data like `Breadcrumbs`, `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. + +2. **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. + - `Release` and `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](https://docs.sentry.io/concepts/key-terms/enrich-data/\#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: + +### [Alert Rules](https://docs.sentry.io/concepts/key-terms/enrich-data/\#alert-rules) + +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: + +1. **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_: [![Issue alert configuration for the example rule.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F002-TZFM5RVW.png%231484x1887&w=3840&q=75)](https://docs.sentry.io/mdx-images/002-TZFM5RVW.png) + +2. **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: + +[![Metric alert configuration for the example rule](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F006-74IB2NWA.png%231484x2090&w=3840&q=75)](https://docs.sentry.io/mdx-images/006-74IB2NWA.png) + + +Learn more in [Alerts](https://docs.sentry.io/product/alerts/). + +### [Filter, Search, and Order Issues](https://docs.sentry.io/concepts/key-terms/enrich-data/\#filter-search-and-order-issues) + +On the **Issues** page, custom data allows you to: + +- Filter issues according to your application's `environments` using the environment filter dropdown. +- Sort issues by the number of (unique) impacted `users`. +- Search through issues by your `custom tags`, `user context` attributes, and `release` ids in the issue search bar. + +[![Issues View](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F003-PA7LJBLZ.png%233403x1522&w=3840&q=75)](https://docs.sentry.io/mdx-images/003-PA7LJBLZ.png) + +Learn more in [Search](https://docs.sentry.io/concepts/search/). + +### [Discover](https://docs.sentry.io/concepts/key-terms/enrich-data/\#discover) + +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_. + +[![Discover Query](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F004-IYDNJC4S.png%232094x1416&w=3840&q=75)](https://docs.sentry.io/mdx-images/004-IYDNJC4S.png) + +Learn more in [Discover](https://docs.sentry.io/product/explore/discover-queries/). + +### [Ownership Rules](https://docs.sentry.io/concepts/key-terms/enrich-data/\#ownership-rules) + +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 `URL`, the `path` of the files in the error's stack-trace, or an error's `tag` value. + +[![Issue Owner Tag Rule](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F005-WBZFLCWC.png%231237x363&w=3840&q=75)](https://docs.sentry.io/mdx-images/005-WBZFLCWC.png) + +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](https://docs.sentry.io/product/issues/ownership-rules/). + +### [Release Workflows](https://docs.sentry.io/concepts/key-terms/enrich-data/\#release-workflows) + +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: + +1. **Commit Tracking** \- With a release in place, Sentry can track which commits were involved with a release and the authors who made them. +2. **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. +3. **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. +4. **Release Health** \- Sentry can monitor the [health](https://docs.sentry.io/product/releases/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.) + +[![Release](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F001-J2GKUTTJ.png%231934x1302&w=3840&q=75)](https://docs.sentry.io/mdx-images/001-J2GKUTTJ.png) + +Learn more in [Releases](https://docs.sentry.io/product/releases/). + +[Previous\\ +\\ +Environments](https://docs.sentry.io/concepts/key-terms/environments) + +[Next\\ +\\ +Tracing](https://docs.sentry.io/concepts/key-terms/tracing) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/enrich-data/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=mai45p2vrhl0)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) + +# Contributing to Docs + +The Sentry documentation is a static site, generated with [Next.js](https://nextjs.org/). + +[Previous\\ +\\ +Concepts & Reference](https://docs.sentry.io/concepts) + +[Next\\ +\\ +Development Environment](https://docs.sentry.io/contributing/environment) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) + +[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=7pqih7842muw)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) +- [Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) + +# Fingerprint Rules + +## Learn about fingerprint rules, matchers for fingerprinting, how to combine matchers, and using variables for fingerprinting. + +This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. + +Fingerprint rules (previously known as _server-side fingerprinting_) are also configured with a config similar to [stack trace rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/), but the syntax is slightly different. The matchers are the same, but instead of flipping flags, a fingerprint is assigned and it overrides the default grouping entirely. Assigning a fingerprint can also refine the default grouping rather than overriding it, if the fingerprint includes the value `{{ default }}`. + +These rules can be configured on a per-project basis in **\[Project\] > Settings > Issue Grouping > Fingerprint Rules**. This setting has input fields where you can write custom fingerprinting rules. To update a rule: + +1. Identify the match logic for grouping issues together. +2. Set the match logic and the fingerprint for it. + +The syntax for fingerprint rules is similar to syntax in [**Discover** queries](https://docs.sentry.io/concepts/search/#syntax). To negate a match, add an exclamation mark ( `!`) at the beginning of the expression. See the full grammar [here](https://github.com/getsentry/sentry/blob/c5b84a393365a833348dd7fd9378d34c353ca6ca/src/sentry/grouping/fingerprinting.py#L17-L55). + +Sentry attempts to match against all values that are configured in the fingerprint. In the case of stack traces, all frames are considered. If the event data matches all the values in a line for a matcher and expression, then the fingerprint is applied. When there are multiple rules that match the event, the first matching rule in the list is applied. + +Fingerprinting Config + +`` + +```bash code-highlight +# You can use comments to explain the rules. Rules themselves follow the +# following syntax: +matcher:expression -> list of values +# The list of values can be hardcoded or substituted values. + +``` + +Below is a practical example, which groups exceptions of a specific type together: + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:DatabaseUnavailable -> system-down +error.type:ConnectionError -> system-down + +error.value:"connection error: *" -> connection-error, {{ transaction }} + +``` + +Now, all the events with the error type `DatabaseUnavailable` or `ConnectionError` will be grouped into an issue with the type `system-down`. In addition, all events with the error value `connection error` will be grouped by their transaction name. So, for example, if your transactions `/api/users/foo/` and `/api/events/foo/`—both with the value `connection error`—crash the same way, Sentry will create two issues, regardless of stack trace or any other default grouping method. + +## [Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#matchers) + +Matchers allow you to use [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)). + +If you want to create a rule that includes brackets `[ ]`, braces `{ }` or a literal `*`, escape them with a backslash; that is, `\[`, `\]`, `\{`, `\}` or `\*`. + +The following matchers are available: + +### [`error.type`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#errortype) + +alias: `type` + +Matches on an exception type (exception name). The match is performed as a case-sensitive glob. + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:ZeroDivisionError -> zero-division +error.type:ConnectionError -> connection-error + +``` + +### [`error.value`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#errorvalue) + +alias: `value` + +Matches on the exception value. Errors or exceptions often have human-readable descriptions (values) associated with them. This matcher allows a case insensitive match. + +Fingerprinting Config + +`` + +```bash code-highlight +error.value:"connection error (code: *)" -> connection-error +error.value:"could not connect (*)" -> connection-error + +``` + +### [`message`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#message) + +Matches on a log message. It will also automatically check for the additional exception value as they can be hard to keep apart. The matching is case insensitive. + +Fingerprinting Config + +`` + +```bash code-highlight +message:"system encountered a fatal problem: *" -> fatal-log + +``` + +### [`logger`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#logger) + +Matches on the name of the logger, which is useful to combine all messages of a logger together. This match is case-sensitive. + +Fingerprinting Config + +`` + +```bash code-highlight +logger:"com.myapp.mypackage.*" -> mypackage-logger + +``` + +### [`level`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#level) + +Matches on the log level. The match is case insensitive. + +Fingerprinting Config + +`` + +```bash code-highlight +logger:"com.myapp.FooLogger" level:"error" -> mylogger-error + +``` + +### [`tags.tag_name`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#tagstag_name) + +Matches on the value of the tag `tag_name`. This can be useful to filter down certain types of events. For instance, you can separate events caused by a specific server: + +Fingerprinting Config + +`` + +```bash code-highlight +tags.server_name:"canary-*.mycompany.internal" -> canary-events + +``` + +### [`stack.abs_path`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackabs_path) + +alias: `path` + +Matches on the path of an event and is case insensitive. It uses path globbing semantics, which means that `*` does not match a slash, but `**` does. Note that this matcher matches on both `abs_path` and `filename` as SDKs can be quite inconsistent about how these values are supported. If the glob matches on either of these values, it's considered a match. + +Fingerprinting Config + +`` + +```bash code-highlight +stack.abs_path:"**/my-utils/*.js" -> my-utils, {{ error.type }} + +``` + +### [`stack.module`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackmodule) + +alias: `module` + +Similar to `stack.abs_path` but matches on the module name instead. The match is case-sensitive and regular globbing rules apply ( `*` also matches slashes). + +Fingerprinting Config + +`` + +```bash code-highlight +stack.module:"*/my-utils/*" -> my-utils, {{ error.type }} + +``` + +### [`stack.function`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackfunction) + +alias: `function` + +Checks if any of the functions in the stack trace match the glob. The match is case-sensitive: + +Fingerprinting Config + +`` + +```bash code-highlight +stack.function:"my_assertion_failed" -> my-assertion-failed + +``` + +### [`stack.package`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackpackage) + +alias: `package` + +Matches on the "package" of a frame. This is typically the name of the debug symbol/object file that contains a frame. If any of the frames match this object file, then it matches. + +Fingerprinting Config + +`` + +```bash code-highlight +stack.package:"**/libcurl.dylib" -> libcurl +stack.package:"**/libcurl.so" -> libcurl + +``` + +### [`family`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#family) + +Used to "scope" down the matcher. The following families exist: `javascript` for any type of JavaScript event, `native` for any type of Native event. Any other platform is called `other`. + +Fingerprinting Config + +`` + +```bash code-highlight +family:native !stack.module:"myproject::*" -> not-from-my-project + +``` + +### [`app`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#app) + +Checks if the frame is in-app or not. It is particularly useful when combined with another matcher. Possible values are `yes` and `no`: + +Fingerprinting Config + +`` + +```bash code-highlight +app:yes stack.function:"assert" -> assert + +``` + +## [Combining Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#combining-matchers) + +When multiple matchers are combined, they all need to match. Matchers that operate on frames must all apply to the same frame; otherwise, they are not considered a match. + +For instance, if you match on both the function name and module name, then a match only exists if a frame matches _both_ the function name and the module name. It's not enough for a frame to match only with the function name, even if another frame would match the module name by itself. + +Fingerprinting Config + +`` + +```bash code-highlight +# this matches if a frame exists with a specific function and module name +# and also a specific error type is thrown +error.type:ConnectionError stack.function:"connect" stack.module:"bot" -> bot-error + +``` + +## [Variables](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#variables) + +On the right-hand side of the fingerprint, you can use constant values and variables. Variables are substituted automatically and have the same name as matchers, but they might be filled in differently. These variables can also be used when assigning fingerprints using Sentry SDKs. + +Variables are enclosed in double braces ( `{{ variable_name }}`). + +### [`{{ default }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-default-) + +This fills in the default fingerprint that would be produced by the normal grouping operation. It is useful if you want to subdivide an already existing group by something else: + +Fingerprinting Config + +`` + +```bash code-highlight +stack.function:"query_database" -> {{ default }}, {{ transaction }} + +``` + +### [`{{ transaction }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-transaction-) + +This fills in the name of the transaction into the fingerprint. It will force the creation of a group per transaction: + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ApiError" -> api-error, {{ transaction }} + +``` + +### [`{{ error.type }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-errortype-) + +alias: `{{ type }}` + +This fills in the name of the error that occurred. When chained exceptions are used, it will be the most recently thrown error. This will force the creation of a group per error type: + +Fingerprinting Config + +`` + +```bash code-highlight +stack.function:"evaluate_script" -> script-evaluation, {{ error.type }} + +``` + +### [`{{ error.value }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-errorvalue-) + +alias: `{{ value }}` + +This fills in the stringified value of the error that occurred. When chained exceptions are used, it will be the most recently thrown error. Note that this can produce really bad groups when error values are frequently changing. + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ScriptError" -> script-evaluation, {{ error.value }} + +``` + +### [`{{ stack.function }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackfunction-) + +alias: `{{ function }}` + +This fills in the function name of the "crashing frame," also known as the application code's topmost frame. + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ScriptError" -> script-evaluation, {{ stack.function }} + +``` + +### [`{{ stack.abs_path }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackabs_path-) + +alias: `{{ path }}` + +This fills in the path of the "crashing frame," also known as the application code's topmost frame. + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ScriptError" -> script-evaluation, {{ stack.abs_path }} + +``` + +### [`{{ stack.filename }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackfilename-) + +This is like `stack.abs_path` but will only fill in the relative file name: + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ScriptError" -> script-evaluation, {{ stack.filename }} + +``` + +### [`{{ stack.module }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackmodule-) + +alias: `{{ module }}` + +This fills in the module name of the "crashing frame," also known as the application code's topmost frame. + +Fingerprinting Config + +`` + +```bash code-highlight +error.type:"ScriptError" -> script-evaluation, {{ stack.module }} + +``` + +### [`{{ stack.package }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackpackage-) + +alias: `{{ package }}` + +This fills in the package name (object file) of the "crashing frame," also known as the application code's topmost frame. + +Fingerprinting Config + +`` + +```bash code-highlight +stack.function:"assert" -> assertion, {{ stack.package }} + +``` + +### [`{{ logger }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-logger-) + +This fills in the name of the logger that caused an event. + +Fingerprinting Config + +`` + +```bash code-highlight +message:"critical connection error*" -> connection-error, {{ logger }} + +``` + +### [`{{ level }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-level-) + +This fills in the name of the log level that was used to create an event. + +Fingerprinting Config + +`` + +```bash code-highlight +message:"connection error*" -> connection-error, {{ logger }}, {{ level }} + +``` + +### [`{{ tags.tag_name }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-tagstag_name-) + +This fills in the value of a tag into the fingerprint, which can, for instance, be used to split events by server name or something similar. + +Fingerprinting Config + +`` + +```bash code-highlight +message:"connection error*" -> connection-error, {{ tags.server_name }} + +``` + +### [`{{ message }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-message-) + +This fills in the message of the event (similar to `error.value` but for captured messages). Note that this can produce groups with poor data quality if messages are changing frequently: + +Fingerprinting Config + +`` + +```bash code-highlight +logger:"com.foo.auditlogger.*" -> audit-log, {{ message }} + +``` + +## [Custom Titles](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#custom-titles) + +When you use fingerprinting to group events together it can sometimes be useful to also change the default title of the event. Normally the title of the event is the exception type and value (or the top most function names for certain platforms). When you group by custom rules this title can often be misleading. For instance if you group a logger together you might want to name the group after that logger. This can be accomplished by setting the `title` attribute like this: + +Fingerprinting Config + +`` + +```bash code-highlight +logger:my.package.* level:error -> error-logger, {{ logger }} title="Error from Logger {{ logger }}" + +``` + +[Previous\\ +\\ +Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues) + +[Next\\ +\\ +Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/fingerprint-rules.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Release Management](https://docs.sentry.io/cli/releases/) + +# Release Management + +## Sentry's command line interface can be used for release management. The CLI allows you to create, edit and delete releases as well as upload release artifacts. + +The `sentry-cli` tool can be used for release management on Sentry. It allows you to create, edit and delete releases as well as upload release artifacts for them. Note that releases are global per organization. If you want the releases in different projects to be treated as separate entities, make the version name unique across the organization. For example, if you have projectA and projectB that share version numbers, you can name the releases `projectA-1.0` and `projectB-1.0` respectively. + +Because releases work on projects you will need to specify the organization and project you are working with. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). + +## [Creating Releases](https://docs.sentry.io/cli/releases/\#creating-releases) + +Releases are created with the `sentry-cli releases new` command. It takes at the very least a version identifier that uniquely identifies the releases. There are a few restrictions -- the release name cannot: + +- contain newlines, tabulator characters, forward slashes(/), or back slashes(\\) +- be (in their entirety) period (.), double period (..), or space ( ) +- exceed 200 characters + +The value can be arbitrary, but for certain platforms, recommendations exist: + +- for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error. +- if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`. +- if you tag releases we recommend using the release tag prefixed with a product or package name (for example, `my-project-name@2.3.12`). + +Bash + +`` + +```bash code-highlight +#!/bin/sh +sentry-cli releases new "$VERSION" + +``` + +Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in. + +## [Finalizing Releases](https://docs.sentry.io/cli/releases/\#finalizing-releases) + +By default a release is created “unreleased”. Finalizing a release means that we populate a second timestamp on the release record, which is prioritized over `date_created` when sorting releases in [sentry.io](https://sentry.io/). Release finalization (and the timestamp) also affects: + +- What counts as "the next release" for resolving issues +- What release is used as the base for associating commits if you use `--auto` + +In addition, it creates an entry in the **Activity** stream. + +You can change this by passing either `--finalize` to the `new` command, which will immediately finalize the release, or by separately calling `sentry-cli releases finalize VERSION` later on, which is useful if you are managing releases as part of a build process. For example: + +Bash + +`` + +```bash code-highlight +#!/bin/sh +sentry-cli releases new "$VERSION" +# do your build steps here +# once you are done, finalize +sentry-cli releases finalize "$VERSION" + +``` + +You can also choose to finalize the release when you've made the release live (when you've deployed to your machines, enabled in the App store, etc.). + +If you are using git you can ask Sentry to determine `$VERSION`: + +Bash + +`` + +```bash code-highlight +#!/bin/sh +VERSION=`sentry-cli releases propose-version` + +``` + +## [Commit Integration](https://docs.sentry.io/cli/releases/\#commit-integration) + +If you have [repositories configured](https://docs.sentry.io/product/releases/setup/release-automation/) within your Sentry organization, you can associate commits with your release automatically or manually. If you don't have a source code integration installed, you can still send Sentry commit information. See [Alternatively: Without a Repository Integration](https://docs.sentry.io/cli/releases/#alternatively-without-a-repository-integration) to associate commits using the git tree of your local repo. + +To integrate commits automatically, you need to deploy from a git repository that sentry-cli can discover from your current working directory and set commits with the `--auto` flag: + +Bash + +`` + +```bash code-highlight +sentry-cli releases set-commits "$VERSION" --auto + +``` + +In case you are deploying without access to the git repository, you can manually specify the commits instead. To do this, pass the `--commit` parameter to the `set-commits` command in the format `REPO_NAME@REVISION`. You can repeat this for as many repositories as you have: + +bash (one repo)bash (many repos) + +`` + +```bash code-highlight +sentry-cli releases set-commits "$VERSION" --commit "repo-owner/repo-name@deadbeef" + +``` + +To see which repos are available for the organization, you can run `sentry-cli repos list` which will return a list of configured repositories. + +Note that you need to refer to releases you need to use the actual full commit SHA. If you want to refer to tags or references (like _HEAD_), the repository needs to be checked out and reachable from the path where you invoke _sentry-cli_. + +If you also want to set a previous commit instead of letting the server use the previous release as the base point you can do that by setting a commit range: + +Bash + +`` + +```bash code-highlight +sentry-cli releases set-commits "$VERSION" --commit "repo-owner/repo-name@from..to" + +``` + +### [Alternatively: Without a Repository Integration](https://docs.sentry.io/cli/releases/\#alternatively-without-a-repository-integration) + +You can still use the `--auto` flag, and the CLI will automatically use the git tree of your local repo, and associate commits between the previous release's commit and the current head commit with the release. If this is the first release, Sentry will use the latest 20 commits. This behavior is configurable with the `--initial-depth` flag. + +You can use the `--local` flag to enable this behavior by default. + +Bash + +`` + +```bash code-highlight +sentry-cli releases set-commits "$VERSION" --local + +``` + +If you receive an "Unable to Fetch Commits" email, take a look at our [help center article](https://sentry.zendesk.com/hc/en-us/articles/23968845267739-Why-am-I-receiving-the-email-Unable-to-Fetch-Commits). + +### [Dealing With Missing Commits](https://docs.sentry.io/cli/releases/\#dealing-with-missing-commits) + +There are scenarios in which your repositories may be missing commits previously used in the release. This can happen whenever you modify the commit in question by, for example, amending it, rebasing, or squashing multiple commits together. In this case, Sentry CLI will be unable to find it, and will throw an error that the commit cannot be found. + +When this happens, you can pass an additional `--ignore-missing` flag. This will allow the command to fall back to the default behavior, which is creating a release with a specified number of commits (see the section above). + +Bash + +`` + +```bash code-highlight +sentry-cli releases set-commits "$VERSION" --auto --ignore-missing + +``` + +## [Managing Release Artifacts](https://docs.sentry.io/cli/releases/\#managing-release-artifacts) + +When you are working with JavaScript and other platforms, you can upload release artifacts to Sentry which are then considered during processing. The most common release artifact are [source maps](https://docs.sentry.io/platforms/javascript/sourcemaps/) for which `sentry-cli` has specific support. + +To manage release artifacts the `sentry-cli files` command can be used which itself provides various sub commands. + +### [Upload Files](https://docs.sentry.io/cli/releases/\#upload-files) + +The most common use case is to upload files. For the generic upload the `sentry-cli files upload` command can be used. However since most release artifacts are JavaScript source map related we have a [Upload Source Maps](https://docs.sentry.io/cli/releases/#sentry-cli-sourcemaps) convenience method for that. + +Files uploaded are typically named with a full (eg: `http://example.com/foo.js`) or truncated URL (eg: `~/foo.js`). + +Release artifacts are only considered at time of event processing. So while it’s possible to modify release artifacts after the fact they will only be considered for future events of that release. + +The first argument to `upload` is the path to the file, the second is an optional URL we should associate it with. Note that if you want to use an abbreviated URL (eg: `~/foo.js`) make sure to use single quotes to avoid the expansion by the shell to your home folder. + +Bash + +`` + +```bash code-highlight +sentry-cli files upload --release "$VERSION" /path/to/file '~/file.js' + +``` + +### [Upload Source Maps](https://docs.sentry.io/cli/releases/\#upload-source-maps) + +For source map upload, a separate command is provided which assists you in uploading and verifying source maps: + +Bash + +`` + +```bash code-highlight +sentry-cli sourcemaps upload /path/to/sourcemaps + +``` + +This command provides several options and attempts as much auto detection as possible. By default, it will scan the provided path for files and upload them named by their path with a `~/` prefix. It will also attempt to figure out references between minified files and source maps based on the filename. So if you have a file named `foo.min.js` which is a minified JavaScript file and a source map named `foo.min.map` for example, it will send a long a `Sourcemap` header to associate them. This works for files the system can detect a relationship of. + +By default, `sentry-cli` rewrites source maps before upload: + +1. It flattens out indexed source maps. This has the advantage that it can compress source maps sometimes which might improve your processing times and can work with tools that embed local paths for source map references which would not work on the server. This is useful when working with source maps for development purposes in particular. +2. Local file references in source maps for source contents are inlined. This works particularly well with React Native projects which might reference thousands of files you probably do not want to upload separately. +3. It automatically validates source maps before upload very accurately which can spot errors you would not find otherwise until an event comes in. This is an improved version of what `--validate` does otherwise. + +The following options exist to change the behavior of the upload command: + +`--dist` + +Sets the distribution identifier for uploaded files. This identifier is used to make a distinction between multiple files of the same name within a single release. `dist` can be used to disambiguate build or deployment variants. For example, `dist` can be the build number of an Xcode build or the version code of an Android build. + +`--no-sourcemap-reference` + +This prevents the automatic detection of source map references. It’s not recommended to use this option since the system falls back to not emitting a reference anyways. It is however useful if you are manually adding `sourceMapURL` comments to the minified files and you know that they are more correct than the autodetection. + +`--no-rewrite` + +Disables rewriting of matching source maps. By default, the tool will rewrite sources, so that indexed maps are flattened and missing sources are inlined if possible. This fundamentally changes the upload process to be based on source maps and minified files exclusively and comes in handy for setups like react-native that generate source maps that would otherwise not work for Sentry. + +`--strip-prefix` / `--strip-common-prefix` + +Unless `--no-rewrite` is specified, this will chop-off a prefix from all sources references inside uploaded source maps. For instance, you can use this to remove a path that is build machine specific. The common prefix version will attempt to automatically guess what the common prefix is and chop that one off automatically. This will not modify the uploaded sources paths. To do that, point the `sourcemaps upload` command to a more precise directory instead. + +`--validate` + +This attempts source map validation before upload when rewriting is not enabled. It will spot a variety of issues with source maps and cancel the upload if any are found. This is not the default as this can cause false positives. + +`--url-prefix` + +This sets an URL prefix in front of all files. This defaults to `~/` but you might want to set this to the full URL. This is also useful if your files are stored in a sub folder. eg: `--url-prefix '~/static/js'` + +`--ext` + +Overrides the list of file extensions to upload. By default, the following file extensions are processed: `js`, `map`, `jsbundle` and `bundle`. The tool will automatically detect the type of the file by the file contents (eg: sources, minified sources, and source maps) and act appropriately. For multiple extensions you need to repeat the option, e.g.: `--ext js --ext map`. + +`--ignore` + +Specifies one or more patterns of ignored files and folders. Overrides patterns specified in the ignore file. See `--ignore-file` for more information. Note that unlike `--ignore-file`, this argument is interpreted relative to the specified path argument. + +`--ignore-file` + +Specifies a file containing patterns of files and folders to ignore during the scan. Ignore patterns follow the [gitignore](https://git-scm.com/docs/gitignore#_pattern_format) rules and are evaluated relative to the location of the ignore file. The file is assumed in the current working directory or any of its parent directories. + +`--strict` + +Fail with a non-zero exit code if there are no sourcemaps to upload in the provided directory. Without this argument, the command succeeds if there are no sourcemaps to upload. + +Some example usages: + +Bash + +`` + +```bash code-highlight +# Rewrite and upload all sourcemaps in /path/to/sourcemaps +sentry-cli sourcemaps upload /path/to/sourcemaps + +# Prefix all paths with ~/static/js to match where the sources are hosted online +sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js' + +# Remove a common prefix if all source maps are located in a subdirectory +sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js' \ + --strip-common-prefix + +# Omit all files specified in .sentryignore +sentry-cli sourcemaps upload /path/to/sourcemaps --ignore-file .sentryignore + +``` + +### [List Files](https://docs.sentry.io/cli/releases/\#list-files) + +To list uploaded files, the following command can be used: + +Bash + +`` + +```bash code-highlight +sentry-cli files list --release "$VERSION" + +``` + +This will return a list of all uploaded files for that release. + +### [Delete Files](https://docs.sentry.io/cli/releases/\#delete-files) + +You can also delete already uploaded files. Either by name or all files at once: + +Bash + +`` + +```bash code-highlight +sentry-cli files delete --release "$VERSION" NAME_OF_FILE +sentry-cli files delete --release "$VERSION" --all + +``` + +## [Creating Deploys](https://docs.sentry.io/cli/releases/\#creating-deploys) + +You can also associate deploys with releases. To create a deploy you first create a release and then a deploy for it. At the very least, you should supply the “environment” the deploy goes to (production, staging etc.). You can freely define this: + +Bash + +`` + +```bash code-highlight +sentry-cli deploys new --release "$VERSION" -e ENVIRONMENT + +``` + +Optionally, you can also define how long the deploy took: + +Bash + +`` + +```bash code-highlight +start=$(date +%s) +... +now=$(date +%s) +sentry-cli deploys new --release "$VERSION" -e ENVIRONMENT -t $((now-start)) + +``` + +Deploys can be listed too (however they cannot be deleted): + +Bash + +`` + +```bash code-highlight +sentry-cli deploys list --release "$VERSION" + +``` + +[Previous\\ +\\ +Configuration and Authentication](https://docs.sentry.io/cli/configuration) + +[Next\\ +\\ +Debug Information Files](https://docs.sentry.io/cli/dif) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/releases.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Set Up Your Organization](https://docs.sentry.io/organization/getting-started/) + +# Set Up Your Organization + +## Learn how to set up a Sentry organization account, so you can start fixing errors right away. + +In this guide, we'll provide the recommended checklist for setting up your [Sentry organization account](https://sentry.io/) so you can get started with Sentry error monitoring. + +If you'd prefer a TL;DR, download our ["Admin Quick Reference Guide"](https://docs.sentry.io/pdfs/Admin-quick-reference-guide.pdf) + +We understand that some of you are running enterprise organizations, while others of you are hobbyists just coding for fun. Below, we've linked where you should get started, depending on your situation. + +- You're configuring Sentry for a large organization? [Start at step 1](https://docs.sentry.io/organization/getting-started/#1-enable-single-sign-on-access) +- You're working on an application with a small team? [Start step 2](https://docs.sentry.io/organization/getting-started/#2-set-up-teams) +- You're a hobbyist or working on an app alone? [Start at step 3](https://docs.sentry.io/organization/getting-started/#3-configure-integrations) + +Of course, you're welcome to go through all the steps, even if you're a team of one. + +## [1\. Enable Single Sign-On Access](https://docs.sentry.io/organization/getting-started/\#1-enable-single-sign-on-access) + +[Single sign-on (SSO)](https://docs.sentry.io/organization/authentication/sso/) allows your team to log in quickly, streamlines the on/off-boarding process for member accounts, and strengthens your login with secure credentials. Sentry provides out-of-the-box configuration for integrating SSO providers like [Okta](https://docs.sentry.io/organization/authentication/sso/#okta) and [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/#azure-active-directory) (SAML) or [Google](https://docs.sentry.io/organization/authentication/sso/#google-business-app) and [GitHub](https://docs.sentry.io/organization/authentication/sso/#github-organizations) (Oauth). In addition, we provide a generic configuration option for any other [SAML2 Identity Provider](https://docs.sentry.io/organization/authentication/sso/saml2/). + +Sentry also supports a subset of the specification for System for Cross-Domain Identity Management (SCIM) for [Okta](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) and [Azure AD](https://docs.sentry.io/organization/authentication/sso/azure-sso/#scim-integration). + +## [2\. Set Up Teams](https://docs.sentry.io/organization/getting-started/\#2-set-up-teams) + +Now that SSO is configured and members have created their accounts, add them to their Sentry Teams. Teams are associated with your [Sentry projects](https://docs.sentry.io/organization/getting-started/#4-create-projects), and their members receive issue notifications in addition to becoming issue assignees. We recommend creating Sentry teams that align with your internal team structure (for example, _#Frontend_, _#Ops_, _#SDK_, and so on). To add a new team, go to **Settings > Teams** and click "Create Team". + +[![Create New Team](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fteam-settings-HSDWF3LG.png%232024x896&w=3840&q=75)](https://docs.sentry.io/mdx-images/team-settings-HSDWF3LG.png) + +Click on a team name to open the team settings and manage its associated members and projects. Under the "Members" tab, add existing members to your team by clicking on "Add Member > \[Member Name\]". + +You can also invite multiple new (external) members to join your organization and team by clicking on "Add Member > Invite Member". + +[![Invite Members](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvite-members-NIJLLGEH.png%231866x717&w=3840&q=75)](https://docs.sentry.io/mdx-images/invite-members-NIJLLGEH.png) + +Learn more about different user roles in [Organization Management](https://docs.sentry.io/organization/membership/). + +## [3\. Configure Integrations](https://docs.sentry.io/organization/getting-started/\#3-configure-integrations) + +Sentry integrates into your existing workflows by providing out-of-the-box integrations with widely-used apps and services. To enable and configure integrations, go to **Settings > Integrations**. There are several types of integrations available, but we recommend that you immediately set up integrations for: + +- [Alerting](https://docs.sentry.io/organization/getting-started/#31-alert-notifications) +- [Source code management](https://docs.sentry.io/organization/getting-started/#32-source-code-management) +- [Issue tracking](https://docs.sentry.io/organization/getting-started/#33-issue-tracking) + +### [Alert Notifications](https://docs.sentry.io/organization/getting-started/\#alert-notifications) + +By default, Sentry will notify you about errors in your apps by email and [Slack](https://docs.sentry.io/organization/integrations/notification-incidents/slack/) (once you enable the integration). You can also enable team notifications in Slack so the right people in your organization always receive the alerts they need. In addition to Slack, Sentry offers several other [notification and incident integrations](https://docs.sentry.io/organization/integrations/notification-incidents/) to help you triage issues, including [Discord](https://docs.sentry.io/organization/integrations/notification-incidents/discord/), [Microsoft Teams](https://docs.sentry.io/organization/integrations/notification-incidents/msteams/), and [PagerDuty](https://docs.sentry.io/organization/integrations/notification-incidents/pagerduty/). + +Learn more about setting up alerts with integrations in [Alert Routing With Integrations](https://docs.sentry.io/product/alerts/create-alerts/routing-alerts/). + +### [Source Code Management](https://docs.sentry.io/organization/getting-started/\#source-code-management) + +When you enable an integration with your source code management (SCM) provider, Sentry will analyze your commit data to: + +1. Identify **suspect commits** that likely introduced an error. + +2. **Suggest assignees** who can best resolve the error, based on the suspect commits and your [codeowners file](https://docs.sentry.io/product/issues/issue-owners/#code-owners). + +3. Mark an issue as **Resolved via Commit or PR** to stop notifications about similar errors in past releases and notify you of a regression. + +4. Link a Sentry issue to a new or existing issue in your integrated [issue tracking](https://docs.sentry.io/organization/getting-started/#33-issue-tracking) solution. + +[![Identify suspect commits and see suggested assignees for issues.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissue-integrations-01-UC7KSKAC.png%231400x537&w=3840&q=75)](https://docs.sentry.io/mdx-images/issue-integrations-01-UC7KSKAC.png) + +[![Link a Sentry issue to a new or existing issue in your issue tracking solution.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissue-integrations-02-WDF5PC4V.png%231400x210&w=3840&q=75)](https://docs.sentry.io/mdx-images/issue-integrations-02-WDF5PC4V.png) + + +Sentry has built-in SCM integrations with: + +- [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/) +- [GitHub](https://docs.sentry.io/organization/integrations/source-code-mgmt/github/) +- [GitLab](https://docs.sentry.io/organization/integrations/source-code-mgmt/gitlab/) +- [Bitbucket](https://docs.sentry.io/organization/integrations/source-code-mgmt/bitbucket/) + +If you're using a different SCM provider or don't want Sentry to connect to your repository, check out our [Releases documentation](https://docs.sentry.io/product/releases/associate-commits/) to learn how you can still associate commits with your release. + +### [Issue Tracking](https://docs.sentry.io/organization/getting-started/\#issue-tracking) + +Enabling an integration with your issue tracking solution allows you to create a new issue from within the **Issue Details** page in [sentry.io](https://sentry.io/), or link to an existing one. GitHub, GitLab, and Bitbucket issues are associated with their respective SCM integrations. Sentry also integrates with [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/), [Shortcut](https://docs.sentry.io/organization/integrations/issue-tracking/shortcut/), [Jira](https://docs.sentry.io/organization/integrations/issue-tracking/jira/), and others. + +For a list of all supported integrations, check out out our [full Integrations documentation](https://docs.sentry.io/organization/integrations/). + +You can set up automated issue management when you create alerts that route to [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/#automatically) and [Jira](https://docs.sentry.io/organization/integrations/issue-tracking/jira/#automatically). External issues will be created for new Sentry issues on your behalf, and these issues will use the configured fields in your Azure DevOps or Jira workspace. For other issue tracking solutions, you can manually link Sentry issues. + +Automatic issue management is available only if your organization is on a Business or Trial plan. + +## [4\. Create Projects](https://docs.sentry.io/organization/getting-started/\#4-create-projects) + +To start monitoring errors in your app with Sentry, you'll need to initialize the SDK with a DSN key. To obtain a key, add a new Sentry project by going to **Projects** and clicking "Create Project". Give the project a name and assign the responsible [team (or teams)](https://docs.sentry.io/organization/getting-started/#2-set-up-teams). Then, retrieve the key in **\[Project\] > Settings > Client Keys (DSN)**. + +[![Retrieve your project DSN key.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-dsn-CQ76WK6B.png%231400x561&w=3840&q=75)](https://docs.sentry.io/mdx-images/project-dsn-CQ76WK6B.png) + +Once the SDK is initialized, any error that occurs in your code, wherever it may be deployed and running, will be associated with that specific project. + +If you haven't set up any teams to associate with your project because you skipped to step three, don't worry. Even on our free Developer plan, Sentry automatically sets up a team for you based on the name of your organization, and adds you to it. + +### [What's in a Project?](https://docs.sentry.io/organization/getting-started/\#whats-in-a-project) + +A _project_ is a logical entity that connects the errors in your application (or a part of it) to the team members assigned to that project. The project settings determine: + +- Which errors should be ingested into your Sentry account and which should be dropped, through [Inbound Filters](https://docs.sentry.io/pricing/quotas/#inbound-data-filters) +- Who to notify, about what error, and how, using [Alert Rules](https://docs.sentry.io/product/alerts/alert-types/) +- Which errors should be automatically assigned to which member or team using [Ownership Rules](https://docs.sentry.io/product/issues/ownership-rules/) +- Custom rules to fine-tune [Event Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) into issues + +Also, when you go to the **Issues** and **Discover** pages in [sentry.io](https://sentry.io/), the filter at the top of the screen prioritizes the projects you're a member of by default. This way, developers are looking at information that is relevant to their work, and they see the errors that they might need to work on. + +[![Issues page with Project dropdown open.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissues-project-dropdown-ASVOHFSW.png%232152x847&w=3840&q=75)](https://docs.sentry.io/mdx-images/issues-project-dropdown-ASVOHFSW.png) + +### [How Many Projects Should I Create?](https://docs.sentry.io/organization/getting-started/\#how-many-projects-should-i-create) + +You could theoretically put all your errors into a single project, as this isn't limited in [sentry.io](https://sentry.io/). However, setting up multiple projects to reflect your application with finer granularity helps makes errors more visible and actionable, which can have a big impact on your team's productivity. + +Here are some points to consider: + +- If your application's source code is managed in **multiple repositories**, create a **separate project for each repo**. +- If your app is made up of **several micro-services**, **split them into projects** accordingly. +- If you have a **monolithic codebase**, set up **separate projects for the backend and frontend**. +- Give **each language its own project**. For example, if your backend code contains NodeJS and Java components, separate those into two different projects. + +## [5\. Define Environments](https://docs.sentry.io/organization/getting-started/\#5-define-environments) + +Depending on your development life cycle, your applications are probably deployed and running in multiple environments — _QA_, _Staging_, _Production_, and so on. Configuring the environment in your Sentry SDK will add the tag to every error event and will help you associate events with the environment in which they occurred. You can do that by creating a `SENTRY_ENVIRONMENT` environment variable or by explicitly defining it in the SDK configuration. Learn more in [Environments](https://docs.sentry.io/platform-redirect/?next=/configuration/environments/). + +[![The Issues page with the Environment dropdown opened.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenvironment-dropdown-CVASUUYU.png%232153x827&w=3840&q=75)](https://docs.sentry.io/mdx-images/environment-dropdown-CVASUUYU.png) + +Having the environment defined in your SDK will allow you to: + +- Create environment-specific alert rules. +- Filter the **Issues** page based on the environment. +- Gain comparative insights, based on the environment, through queries in **Discover**. + +[Previous\\ +\\ +Organization Settings](https://docs.sentry.io/organization) + +[Next\\ +\\ +Authentication](https://docs.sentry.io/organization/authentication) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/getting-started/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/) + +# How to Write - Getting Started + +A new platform/SDK should base it's Getting Started page of off a similar existing SDK page. + +Here's an overview of the general components of a Getting Started page. + +## [config.yml](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#configyml) + +This file resides in the `/docs/platform//` directory. An example: + +YAML + +`` + +```yaml code-highlight +title: JavaScript +caseStyle: camelCase +supportLevel: production +sdk: "sentry.javascript.browser" +categories: + - browser + +``` + +## [Primer Content](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#primer-content) + +Explain the SDK at a high level in these two parts: + +1. An italicized sentence that explains what the SDK enables (errors, or errors and transactions) + +2. A brief paragraph that provides technical insight and the versions supported + +If the primer content isn't developed, this fallback will display " _Sentry's SDKs enable automatic reporting of errors and exceptions_." + + +Add the primer content to this directory: + +- [`/platform-includes/getting-started-primer/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-primer) + +## [Installation Method](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#installation-method) + +Provide an example of the primary installation method for this SDK. While we document alternate methods, we keep those on a separate page (as in this [example](https://docs.sentry.io/platforms/javascript/install/)) to keep the focus of the Getting Started content on the most-common, fastest way to get up and running. + +Add the installation method to this directory: + +- [`/platform-includes/getting-started-install/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-install) + +## [Configuration Code Sample](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#configuration-code-sample) + +Provide an example of the configuration of this SDK, commenting in the code sample, not the surrounding prose. + +Add the configuration code sample to this directory: + +- [`/platform-includes/getting-started-config/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-config) + +If the SDK supports performance monitoring, add it to the list that links back into the SDK content from Product, stored in [`/docs/product/insights/getting-started.mdx`](https://github.com/getsentry/sentry-docs/blob/master/docs/product/insights/getting-started.mdx). + +## [Verification Code Sample](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#verification-code-sample) + +Provide a verification code sample for this SDK. It can be as simple as one line, though the SDK may require a more complex code sample. + +Add the verification code sample to this directory: + +- [`/src/platform-includes/getting-started-verify/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-verify) + +## [But, that's not all](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#but-thats-not-all) + +The Getting Started content is also used by our in-app onboarding wizard to get customers up and running with Sentry. Keeping all content up to date is critical. + +**If updating the code samples for an SDK, also update the Wizard.** + +### [Update the Wizard](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#update-the-wizard) + +The in-app wizard is where customers first implement our SDKs. It's not a simple copy/paste from the Getting Started for two reasons: + +1. New customers lack the context that our Docs provide (think of it this way, there's no lefthand sidebar to review). +2. Experienced customers likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point customers to the product for a tour. + +As a result, a simple copy/paste of the Getting Started won't suffice. See the JavaScript wizard as an example. + +[Previous\\ +\\ +Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content) + +[Next\\ +\\ +How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-getting-started.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) + +# Tracing + +## Learn more about the tracing features Sentry offers to help you track your software performance across multiple systems. + +[Distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/) provides a connected view of related errors and transactions by capturing interactions among your software systems. With tracing, Sentry tracks your software performance and displays the impact of errors across multiple systems. Tracing issues back through services connects your front-end to your back-end. + +The [Trace View](https://docs.sentry.io/product/sentry-basics/tracing/trace-view/) allows you to drill down into the details of a single trace and traverse every transaction in that trace. This accelerates your ability to debug slow services, identify related errors, and root out other bottlenecks. + +The [Trace Explorer](https://docs.sentry.io/product/explore/traces/) allows you to explore traces by querying [span properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/). This helps you find relevant distributed traces that will give you more information to debug and optimize your code. + +## [Learn More](https://docs.sentry.io/concepts/key-terms/tracing/\#learn-more) + +[Previous\\ +\\ +Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data) + +[Next\\ +\\ +Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter/) + +# Frontmatter + +Frontmatter a YAML-formatted blob defined at the top of every markdown or mdx file: + +Markdown + +`` + +```markdown code-highlight +--- +title: Doc Title +--- + +Markdown or MDX content + +``` + +Standard frontmatter will apply on nearly every page: + +`title` + +Document title - used in `` as well as things like search titles. + +`noindex` (false) + +Set this to true to disable indexing (robots, algolia) of this content. + +`notoc` (false) + +Set this to true to disable page-level table of contents rendering. + +`draft` (false) + +Set this to true to mark this page as a draft, and hide it from various other components (such as the PageGrid). + +`keywords` (\[\]) + +A list of keywords for indexing with search. + +`description` + +A description to use in the `<meta>` header, as well as in auto generated page grids. + +`sidebar_order` (10) + +The order of this page in auto generated sidebars and grids. + +Much of the other functionality for pages is also driven via frontmatter, such as: + +- [Redirects](https://docs.sentry.io/contributing/pages/redirects/) +- [Search](https://docs.sentry.io/contributing/pages/search/) + +`nextPage` ( `{ path: 'path/to/page', title: 'Page Title' }`) + +Overrides the next page shown in the bottom pagination navigation. + +`previousPage` ( `{ path: 'path/to/page', title: 'Page Title' }`) + +Overrides the previous page shown in the bottom pagination navigation. + +[Previous\\ +\\ +Pages](https://docs.sentry.io/contributing/pages) + +[Next\\ +\\ +Images](https://docs.sentry.io/contributing/pages/images) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/frontmatter.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Rate Limits](https://docs.sentry.io/api/ratelimits/) + +# Rate Limits + +Sentry rate limits every API request made to prevent abuse and resource overuse. The limit is applied to each unique combination of caller and endpoint. + +We restrict both how frequently a request is made (requests per second rate limit) and how many concurrent requests a caller can make (concurrent rate limit). + +The requests per second rate limit follows a fixed window approach. Requests are counted into time buckets, determined by the window size. If the number of requests from a caller exceeds the number of allowed requests within a window, then that request will be rejected. Each endpoint has its own maximum number of requests and window size. + +Meanwhile, the concurrent rate limiter will reject requests if the caller has too many requests in progress at the same time. + +You can track your rate limit usage by looking at special headers in the response. + +## [Headers](https://docs.sentry.io/api/ratelimits/\#headers) + +Every API request response includes the following headers: + +- `X-Sentry-Rate-Limit-Limit` + - The maximum number of requests allowed within the window +- `X-Sentry-Rate-Limit-Remaining` + - The number of requests this caller has left on this endpoint within the current window +- `X-Sentry-Rate-Limit-Reset` + - The time when the next rate limit window begins and the count resets, measured in UTC seconds from epoch +- `X-Sentry-Rate-Limit-ConcurrentLimit` + - The maximum number of concurrent requests allowed +- `X-Sentry-Rate-Limit-ConcurrentRemaining` + - The number of concurrent requests this caller has left + +## [Additional Information](https://docs.sentry.io/api/ratelimits/\#additional-information) + +The rate limiter looks at the caller's identity instead of the bearer token or cookie. As such, the rate limit cannot be bypassed by generating multiple tokens. + +Polling the API for updates is likely to quickly trigger rate limiting. We recommend using our [webhooks](https://docs.sentry.io/organization/integrations/integration-platform/webhooks/), if possible. + +[Previous\\ +\\ +Permissions & Scopes](https://docs.sentry.io/api/permissions) + +[Next\\ +\\ +Requests](https://docs.sentry.io/api/requests) + +- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Data Storage Location (US or EU)](https://docs.sentry.io/organization/data-storage-location/) + +# Data Storage Location (US or EU) + +## Choose where to store your data in the US or the EU. + +Sentry supports data storage in both the US and the EU. + +You can choose where to store your data when you’re setting up your Sentry account by selecting from the dropdown menu under "Data Storage Location" in the "Create a New Organization" section. + +**Please note that once selected, your data storage location can’t be changed. The only way to switch it is by creating a new organization.** + +Your selection determines your data storage location only. Sentry will continue to access and process your data in accordance with your agreement with Sentry for the Sentry service and our [Privacy Policy](https://sentry.io/privacy/). + +The table below shows the location where your data will be stored at rest, based on your selection. + +| **Data Storage Location** | **Physical Location** | +| --- | --- | +| United States of America (US) | Iowa, USA | +| European Union (EU) | Frankfurt, Germany | + +## [What Types of Data Are Stored Where](https://docs.sentry.io/organization/data-storage-location/\#what-types-of-data-are-stored-where) + +Here’s a list of the types of data that will be stored in whichever data storage location (US or EU) you select. + +### [Data Stored In Selected Location (US or EU)](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-selected-location-us-or-eu) + +- Error events +- Transactions +- Profiles +- Release health +- Releases, debug symbols, and source maps +- Session replays +- Backups for these resources + +### [Data Stored in US](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-us) + +Here’s a list of the types of data that may be stored in the US. + +- User accounts, notification settings, and 2FA authenticators (User accounts are shared by many organizations.) +- Organization integration metadata (Integrations can be shared across organizations and many of our integrations only support sending their webhooks to a singular destination.) +- Access tokens for users and organizations +- Organization settings, configurations, and teams +- Organization audit logs +- Issue activity, issue links +- Cron check-ins +- Project metadata +- DSN keys +- Detailed usage data +- Debug symbol metadata and source map metadata +- Sentry applications +- SSO, SAML, and SCIM metadata + +Metadata that lets Sentry identify an organization will be replicated out of the organization's data storage location to facilitate login, and backwards-compatible APIs. You can always confirm the location of your organization by viewing your organization's settings page. + +### [Data Stored in All Locations (US and EU)](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-all-locations-us-and-eu) + +Here’s a list of the types of data that will be stored in both data storage locations (US and EU). + +- Uptime checks + +##### Uptime Monitoring + +For uptime monitoring to work effectively, we perform uptime checks from multiple geolocations. As a result, uptime check data may be stored outside your selected data region, beyond the storage commitments outlined on this page. + +## [Using Data Storage Location APIs](https://docs.sentry.io/organization/data-storage-location/\#using-data-storage-location-apis) + +To ensure that your API requests are only processed within your selected data storage location, use the region-specific domain: + +| **Data Storage Location** | **API domain** | +| --- | --- | +| United States of America (US) | us.sentry.io | +| European Union (EU) | de.sentry.io | + +For [data stored in the US](https://docs.sentry.io/organization/data-storage-location/#data-stored-in-us), your API domain should be `sentry.io`. + +## [Switching Data Storage Locations for Existing Organizations](https://docs.sentry.io/organization/data-storage-location/\#switching-data-storage-locations-for-existing-organizations) + +### [SaaS](https://docs.sentry.io/organization/data-storage-location/\#saas) + +At this time, your data storage location can’t be changed if you have an existing SaaS organization. The only way to switch it is by creating a new organization. + +### [Self-hosted](https://docs.sentry.io/organization/data-storage-location/\#self-hosted) + +If you have a self-hosted Sentry account, you can [follow these instructions](https://docs.sentry.io/concepts/migration/) to migrate your data. + +**Supported for relocation:** + +- User accounts and settings +- Organization settings and configuration +- Projects and project settings +- Teams and members +- Dashboards +- Alert rules, notifications and incidents +- Saved searches + +**Unsupported for relocation:** + +- Error events, activity, and issue links +- Transactions +- Profiles +- Session Replays +- Cron check-ins +- Uptime checks +- DSN keys +- Release health +- Releases, Debug Symbols, and source maps +- Sentry Applications +- Access Tokens for users and organizations +- User notification settings, and 2FA authenticators +- Project codeowners +- Integrations +- Organization Audit Logs + +## [For Users With Multiple Organizations](https://docs.sentry.io/organization/data-storage-location/\#for-users-with-multiple-organizations) + +If you have multiple organizations, they will be treated separately regardless of where data is stored. This means that subscriptions, usage, users, projects, and so on, will be managed separately for each organization. + +[Previous\\ +\\ +Organization and User Management](https://docs.sentry.io/organization/membership) + +[Next\\ +\\ +Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/data-storage-location/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) +- [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) + +# Trace View + +## Learn more about the Trace View page, where you can drill down into the details of a single trace, allowing you to debug slow services, identify related errors, and find other bottlenecks. + +The Trace View page is designed to be your one-stop-shop when debugging performance or errors. It gives you full context on what was happening when an error or performance issue occurred, all in one place. The waterfall Trace View allows you to see everything that may have occurred during a trace, including errors, performance issues, and any profiles that may have been collected. + +In addition, looking at the Trace View allows you to drill down into a single trace so you can visualize the high-level transactions and spans that took place within that trace. This makes debugging slow services, identifying related errors, and rooting out bottlenecks easier and faster, since you no longer have to navigate around multiple pages of the Sentry product. + +## [Product Walkthrough: Trace View Page](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#product-walkthrough-trace-view-page) + +Sentry's default visualization of a trace is a waterfall-like structure, where the entries (transactions and spans) in the list are organized chronologically and through ancestry (child spans will fall under their parents). This allows you to follow the order of operations and drill into sub-operations. + +On the left side is a list of operations, and on the right is their duration and any events, such as errors, which may have occurred in that timeframe. + +By default, the waterfall view shows a list of transactions. If you need more granular data and want to see spans as well, click "+" to the left of a transaction to expand the waterfall. The waterfall view helps surface any performance issues or profiles collected during a given timeframe. + +![Step 3](<Base64-Image-Removed>)![Expand transaction to view which span produced the error.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/9ee9049b-14ca-4c93-8829-e41a05b6fa2b.png) + +![](<Base64-Image-Removed>) + +### [Helpful Tips](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#helpful-tips) + +Because debugging often involves multiple people or teams, we've made it easy to draw attention to specific areas of the trace and share a link that shows what you've highlighted with your colleagues. To do this, click on the row you'd like to draw attention to and share the resulting URL. Your colleague will see exactly what you want them to. + +Whatever you highlight will also be saved if you navigate away from the page and will still be there when you use your browser's back and forward buttons. + +If you're doing a comparison and want an easy way to go back and forth between highlighted areas of interest in your trace, you can pin the tabs. When a tab is pinned, the view will be persistent throughout your session. + +Trace View — Tabbing + +Trace View — Tabbing + +![Pinning a tab will persist it.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/d2c464e2-9c6a-4212-8c9c-f84302a9ecac.png) + +![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/65d725cb-0e5f-4d04-960f-4c7118ddc307.png) + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +Sometimes, duration gaps between entries can be small, but critical to your debugging effort. That's why the Trace View enables you to zoom into certain areas of the trace, either by double clicking on row elements (which zooms into the row) or by using your scroll wheel. + +Trace View — Zooming + +Trace View — Zooming + +![Scroll to move around or scroll + meta key to zoom.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/37fcd5f8-b2b5-4483-b5e5-cd9904dca78d.png)![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/980a208b-3fda-41fd-a52b-09d051b3f7d5.png) + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +The Trace View has other features like search, which makes it easy to visualize matching spans that you can then iterate over using the up or down arrows. You can also tailor the layout to your preference. + +We're going to continue adding features that enable you to perform efficient investigation into whatever issues you might be facing. If you have feedback or requests, please share it with us. We'd love to hear how we can make your life easier and your users happier. + +## [Troubleshooting](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#troubleshooting) + +### [Orphan Traces and Broken Subtraces](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#orphan-traces-and-broken-subtraces) + +In a fully instrumented system, a span in one service will connect to a transaction in a subsequent service. For a variety of reasons, a transaction in a service may not arrive in Sentry. When Sentry encounters these types of transactions within a trace, the transactions are linked with a dashed line since they can no longer be directly connected to the root, creating an orphan trace. + +In addition, broken subtraces can occur when Sentry receives an error for a trace, but the corresponding transaction does not exist. Such errors are linked using dashed lines and clicking on the row takes you to the corresponding **Issue Details** page. + +Also, in these cases you can click "Open In Discover" to see all the events in the trace. + +Broken subtraces may be caused by: + +- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](https://docs.sentry.io/organization/dynamic-sampling/#deciding-on-your-sdk-sample-rate). +- [Ad blockers](https://docs.sentry.io/platforms/javascript/troubleshooting/#dealing-with-ad-blockers) may prevent transactions in browsers being sent, but HTTP requests to backend projects will still create child transactions +- [Rate-limiting](https://docs.sentry.io/product/accounts/quotas/#limiting-events) on a project may cause only some events to be sent to Sentry +- [Project permissions](https://docs.sentry.io/product/accounts/membership/#restricting-access) may mean you do not have access to transactions in another project +- [Differences in quota limits](https://docs.sentry.io/product/accounts/quotas/) between transactions and errors. When a quota limit is reached - for example, for transactions - an error is received, but corresponding transaction is not. +- Exceeding the span limit. Transactions are associated via the child spans of the parent transaction, but if the number of spans exceed the limit, the association cannot be made + +### [Multiple Roots](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#multiple-roots) + +Each trace ID should have only one root, a transaction without any parents. Automatic instrumentation should prevent multiple roots; however, if the trace ID of your transactions is being set using custom instrumentation, you may encounter multiple roots. + +[Previous\\ +\\ +Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) + +[Next\\ +\\ +Search](https://docs.sentry.io/concepts/search) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/trace-view.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) +- [Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta/) + +# Vanta + +## Learn about Sentry's Vanta integration and how it helps automate security compliance. + +Sentry's Vanta integration grants Vanta read-only access to verify that Sentry organization members are associated with employees in your organization, which automates security compliance. This integration is maintained and supported by the company that created it. For more details, check out our [Integration Platform documentation](https://docs.sentry.io/organization/integrations/integration-platform/). + +## [Install and Configure](https://docs.sentry.io/organization/integrations/compliance/vanta/\#install-and-configure) + +Sentry owner, manager, or admin permissions are required to install this integration. + +1. Navigate to **Settings > Integrations > Vanta** + +2. Follow the full [Vanta installation instructions](https://help.vanta.com/hc/en-us/articles/13045851267092). + + +[Previous\\ +\\ +Truto](https://docs.sentry.io/organization/integrations/compliance/truto) + +[Next\\ +\\ +Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/vanta/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/) + +# How to Write - Configuration + +The Configuration section of the content covers, unsurprisingly, how customers can configure an SDK. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/configuration/` \- feel free to peruse the files in that directory to help answer any questions. + +Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. + +Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions if any questions arise by opening an issue on GitHub. + +## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#start-here) + +Determine if the page applies: + +- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. +- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting that customers open an issue for the missing sample. + +### [Basic Options](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#basic-options) + +This file is `options.mdx`. It explains all the configuration options. + +To develop content for this file: + +1. Create the `configuration/config-intro/` statement, which covers how options can be set. + +2. For individual options that the guide does NOT support, add the name of the guide to the `ConfigKey` statement for that option. This will prevent that option from displaying for this SDK. For example: + +`<ConfigKey name="debug" notSupported={["javascript.react"]}>` + +Alternately, for individual options that the guide DOES support, add the name of the guide to `ConfigKey` statement for that option, which ensures the option displays. For example: + +`<ConfigKey name="send-default-pii" supported={["javascript.electron", "javascript.ember"]}>` + +3. For a grouping of options that the guide DOES support, add the name of the guide to the `PlatformSection` statement for those options, which ensures the option displays. For example: + +`<PlatformSection supported={["javascript.react"]}>` + + +### [Releases & Health](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#releases--health) + +This file is `releases.mdx`. It explains how to configure the SDK to tell Sentry about releases. Provide a code sample for this SDK to set a release, then add the code sample to this directory: + +- `/platform-includes/set-release/` + +A few nuances: + +- If adding an SDK related to JavaScript, update the source maps-related paragraph, as appropriate, in the `PlatformSection supported` statement. +- For SDKs that support release health, we control the display of content with a `PlatformSection supported` statement. For these SDKs, provide the following code sample: Opt out of auto session tracking, stored in `/platform-includes/configuration/auto-session-tracking`. + +### [Environments](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#environments) + +This file is `environments.mdx`. It explains how to configure the SDK to set an environment. + +Add the code sample to this directory: + +- `/platform-includes/set-environment/` + +### [Filtering Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#filtering-events) + +This file is `filtering.mdx`. It explains how to configure the SDK to filter events sent to Sentry. Add code samples to these directories: + +- `/platform-includes/configuration/before-send/` +- `/platform-includes/configuration/before-send-hint/` + +Enable or disable the content for "Using Hints", as appropriate to the SDK, by adding it to the list of either `supported` or `notSupported`, then add code sample to these directories: + +- `/platform-includes/configuration/before-send-fingerprint/` +- `/platform-includes/configuration/decluttering/` + +Enable or disable the content for "Using Sampling to Filter Transaction Events" by adding the SDK to the list of either `supported` or `notSupported`, then add code sample to this directory: + +- `/platform-includes/performance/traces-sampler-as-filter/` + +### [Sampling Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#sampling-events) + +This file is `sampling.mdx`. It explains how to set the sample rate for the SDK. + +Add code samples to these directories: + +- `/platform-includes/configuration/sample-rate/` +- `/platform-includes/performance/uniform-sample-rate/` +- `/platform-includes/performance/sampling-function-intro/` +- `/platform-includes/performance/default-sampling-context` +- `/platform-includes/performance/custom-sampling-context` +- `/platform-includes/performance/always-inherit-sampling-decision` +- `/platform-includes/performance/force-sampling-decision` + +### [Shutdown and Draining](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#shutdown-and-draining) + +This file is `draining.mdx`. Add the drain example content to this directory: + +- `/platform-includes/configuration/drain-example/` + +### [Integrations](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#integrations) + +This content is developed at the primary SDK/platform level. It resides in `/docs/platforms/<SDK>/integrations/` or `/docs/platforms/<SDK>/common/integrations/` and is typically composed of the following: + +1. Default Integrations - `default.mdx` \- system integrations are enabled by default. We document them so customers can both be aware of what they do and disable them if they cause issues. +2. Pluggable Integrations - `plugin.mdx` \- pluggable integrations are snippets of code that augment functionality for specific applications and/or frameworks. We document them so customers can see what they do and that they can be enabled. +3. Custom Integrations - `custom.mdx` \- explains how to enable a custom integration. + +[Previous\\ +\\ +How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started) + +[Next\\ +\\ +How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-configuration.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Sending Events](https://docs.sentry.io/cli/send-event/) + +# Sending Events + +## Learn how Sentry's command line interface can be used for sending events. + +The `sentry-cli` tool can also be used for sending events. If you want to use it, you need to export the `SENTRY_DSN` environment variable and point it to the DSN of a project of yours: + +Bash + +`` + +```bash code-highlight +export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0' + +``` + +Once that is done, you can start using the `sentry-cli send-event` command. + +## [Basic Events](https://docs.sentry.io/cli/send-event/\#basic-events) + +For basic message events, you just need to provide the `--message` or `-m` parameter to send a message: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m "Hello from Sentry" + +``` + +This will send a single message to Sentry and record it as an event. Along with that event, it sends basic information about the machine you are running `sentry-cli` on. You can provide `-m` multiple times to send multiple lines: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m "Hello from Sentry" -m "This is more text" + +``` + +## [Events with Parameters](https://docs.sentry.io/cli/send-event/\#events-with-parameters) + +In addition you can use `%s` as placeholder in a message and fill it in with the `-a` parameter. This helps reviewing them, as all messages will be grouped together automatically: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m "Hello %s!" -a "Joe" +sentry-cli send-event -m "Hello %s!" -a "Peter" + +``` + +## [Sending Breadcrumbs](https://docs.sentry.io/cli/send-event/\#sending-breadcrumbs) + +You can also pass a logfile to the `send-event` command which will be parsed and sent along as breadcrumbs. The last 100 items will be sent: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m “task failed” –-logfile error.log + +``` + +The logfile can be in various formats. If you want to create one yourself you can do something along those lines: + +Bash + +`` + +```bash code-highlight +echo "$(date +%c) This is a log record" >> output.log +echo "$(date +%c) This is another record" >> output.log +sentry-cli send-event -m "Demo Event" --logfile output.log +rm output.log + +``` + +## [Extra Data](https://docs.sentry.io/cli/send-event/\#extra-data) + +Extra data can be attached with the `-e` parameter as `KEY:VALUE`. For instance, you can send some key value pairs like this: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m "a failure" -e task:create-user -e object:42 + +``` + +Likewise, tags can be sent with `-t` using the same format: + +Bash + +`` + +```bash code-highlight +sentry-cli send-event -m "a failure" -t task:create-user + +``` + +## [Stored Events](https://docs.sentry.io/cli/send-event/\#stored-events) + +As of version `1.71`, the `send-event` command can accept an optional argument that specifies a path to the stored JSON representation of an [event payload](https://develop.sentry.dev/sdk/data-model/event-payloads/). When used, it will load the file, validate the event and send it to Sentry. + +Bash + +`` + +```bash code-highlight +sentry-cli send-event ./events/20211029150006.json + +``` + +This argument can be also provided in the form of a glob, which will cause it to process all matched events. + +Bash + +`` + +```bash code-highlight +sentry-cli send-event "./events/*.json" + +``` + +If `send-event` is called with the `--raw` flag, the event will not be validated before being sent. + +Bash + +`` + +```bash code-highlight +sentry-cli send-event --raw ./events/20211029150006.json + +``` + +## [Specifying Releases](https://docs.sentry.io/cli/send-event/\#specifying-releases) + +Releases can be sent with the `--release` parameter. A default release is picked up automatically if you are using sentry-cli from within a git repository. + +## [Bash Hook](https://docs.sentry.io/cli/send-event/\#bash-hook) + +For bash scripts you can also enable automatic error sending by using the sentry-cli bash hook. That enables `set -e` and will send a Sentry event for unhandled errors. + +The limitations for this are: + +- sentry-cli really only works if `set -e` is enabled (which it will by default enable for you). +- sentry-cli registers an `EXIT` and `ERR` trap. + +Usage: + +Bash + +`` + +```bash code-highlight +#!/bin/bash +export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0' +eval "$(sentry-cli bash-hook)" +# rest of the script goes here + +``` + +Alternatively you can use other mechanisms like [a `.sentryclirc` file](https://docs.sentry.io/cli/configuration/#configuration-file) to configure the DSN. + +[Previous\\ +\\ +Debug Information Files](https://docs.sentry.io/cli/dif) + +[Next\\ +\\ +Crons (CLI)](https://docs.sentry.io/cli/crons) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/send-event.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Markdown Variables](https://docs.sentry.io/contributing/pages/variables/) + +# Markdown Variables + +A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within `remark-variables.js`. + +For example: + +ReplacmentSource + +`` + +```code-highlight markdown +JavaScript SDK: 9.3.0 + +``` + +In this case, we expose `packages` as an accessor in the package registry, which is why there's a `packages.version` function available. Additionally, we expose a default context variable of `page`, which contains the frontmatter of the given markdown node. For example, `{{@inject page.title }}`. + +When a variable call is invalid (or errors), or doesn't match something in the known scope, it will produce an error message in the output in development mode. It will force the build to fail in production. + +To escape an expression add a leading `\` to the `@inject`. + +## [`packages`](https://docs.sentry.io/contributing/pages/variables/\#packages) + +The `packages` helper is an instance of `PackageRegistry` and exposes several methods. + +### [`packages.version`](https://docs.sentry.io/contributing/pages/variables/\#packagesversion) + +Returns the latest version of the given package. + +Source + +`` + +```text code-highlight +{{@inject packages.version("sentry.javascript.browser") }} + +``` + +You may also optionally specify a fallback for if the package isn't found (or there's an upstream error): + +Source + +`` + +```text code-highlight +{{@inject packages.version("sentry.javascript.browser", "1.0.0") }} + +``` + +### [`packages.checksum`](https://docs.sentry.io/contributing/pages/variables/\#packageschecksum) + +Returns the checksum of a given file in a package. + +Source + +`` + +```text code-highlight +{{@inject packages.checksum("sentry.javascript.browser", "bundle.min.js", "sha384") }} + +``` + +[Previous\\ +\\ +MDX Components](https://docs.sentry.io/contributing/pages/components) + +[Next\\ +\\ +Redirects](https://docs.sentry.io/contributing/pages/redirects) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/variables.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) +- [Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/) + +# Amazon SQS + +## Learn about Sentry's Amazon SQS integration, which allows you to forward Sentry events to Amazon SQS for further analysis. + +Amazon SQS is useful for a more in-depth analysis of exceptions, making it quick and easy to pipe exceptions back into your own systems. Or, use it to empower other teams, such as a Business Intelligence function. + +This integration needs to be set up in each project for which you wish to use it. It is maintained and supported by the [Sentry community](https://open.sentry.io/). + +## [Install and Configure](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/\#install-and-configure) + +Sentry owner, manager, or admin permissions are required to install this integration. + +Navigate to **Settings > Integrations > Amazon SQS** + +[![Install Amazon SQS integration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Famazon-sqs-OYODE3CU.png%231500x666&w=3840&q=75)](https://docs.sentry.io/mdx-images/amazon-sqs-OYODE3CU.png) + +### [Data Forwarding](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/\#data-forwarding) + +Configure [data forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) in **\[Project\] > Settings > Data Forwarding**, and provide the required information for the given integration. + +The payload for Amazon is identical to our standard API event payload and will evolve over time. For more details on the format of this data, see our [API documentation](https://docs.sentry.io/api/events/retrieve-an-event-for-a-project/). + +[Previous\\ +\\ +Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization) + +[Next\\ +\\ +Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/amazon-sqs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) + +# Pages + +Documentation is written in Markdown (via Remark) and MDX. + +[`Read the quick reference`](https://daringfireball.net/projects/markdown/syntax) + +## [Additional Topics](https://docs.sentry.io/contributing/pages/\#additional-topics) + +[Previous\\ +\\ +Linking Variables](https://docs.sentry.io/contributing/linking) + +[Next\\ +\\ +Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) + +# Issue Grouping + +## Learn about fingerprinting, Sentry's default error grouping algorithms, and other ways to customize how events are grouped into issues. + +A fingerprint is a way to uniquely identify an event, and all events have one. Events with the same fingerprint are grouped together into an issue. + +By default, Sentry will run one of our built-in grouping algorithms to generate an event fingerprint based on information available within the event. The available information and the grouping algorithms vary by event type. Sentry fingerprints error events based on information like `stacktrace`, `exception`, and `message`. Transaction events are fingerprinted by their `spans`. + +## [Default Error Grouping Algorithms](https://docs.sentry.io/concepts/data-management/event-grouping/\#default-error-grouping-algorithms) + +Each time default error grouping behavior is modified, Sentry releases it as a new version. As a result, modifications to the default behavior do not affect the grouping of existing issues. + +When you create a Sentry project, the most recent version of the error grouping algorithm is automatically selected. This ensures that grouping behavior is consistent within a project. + +To upgrade an existing project to a new error grouping algorithm version, navigate to **Settings > Projects > \[project\] > Issue Grouping > Upgrade Grouping**. After upgrading to a new error grouping algorithm, you will very likely see new groups being created. + +All versions consider the `fingerprint` first, the `stack trace` next, then the `exception`, and then finally the `message`. + +To see how an isssue was grouped, go to its **Issue Details** page and scroll down to "Event Grouping Information". There, you'll see if it was grouped by a fingerprint, stack trace, exception, or message. + +### [Grouping by Built-In Fingerprinting Rules](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-built-in-fingerprinting-rules) + +Some kinds of errors, like [chunk load errors](https://sentry.io/answers/chunk-load-errors-javascript/) and [hydration errors](https://sentry.io/answers/hydration-error-nextjs/), often have various different error types, values, or transaction messsages that may result in separate but similar issues. To better handle these cases, Sentry maintains a set of built-in fingerprinting rules to better group such errors. + +Issues grouped by Sentry's built-in fingerprinting rules will list "Sentry Defined Fingerprint" in the "Event Grouping Information" at the bottom of the **Issue Details** page. + +[![event grouping information for a sentry defined fingerprint](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-defined-fingerprint-7P7JYDQM.png%231372x706&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-defined-fingerprint-7P7JYDQM.png) + +Built-in fingerprinting rules work the same as custom fingerprinting rules and are applied by default. If an user defined custom fingerprinting rule matches an event, the custom rule will always take precedence over the built-in ones. + +### [Grouping by Stack Trace](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-stack-trace) + +When Sentry detects a stack trace in the event data (either directly or as part of an exception), the grouping is effectively based entirely on the stack trace. + +The first and most crucial part is that Sentry only groups by stack trace frames that the SDK reports and associates with your application. Not all SDKs report this, but when that information is provided, it’s used for grouping. This means that if two stack traces differ only in parts of the stack that are unrelated to the application, those stack traces will still be grouped together. + +Depending on the information available, the following data can be used for each stack trace frame: + +- Module name +- Normalized filename (with revision hashes, and so forth, removed) +- Normalized context line (essentially a cleaned up version of the source code of the affected line, if provided) + +This grouping usually works well, but two specific situations can throw it off: + +1. Minimized JavaScript source code will destroy the grouping in detrimental ways. To avoid this, ensure that Sentry can access your [Source Maps](https://docs.sentry.io/platforms/javascript/sourcemaps/). +2. Modifying your stack trace by introducing a new level through decorators changes your stack trace, so the grouping will also change. To handle this, many SDKs support hiding irrelevant stack trace frames. For example, the Python SDK will skip all stack frames with a local variable called `__traceback_hide__` set to _True_. + +### [Grouping By Exception](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-exception) + +If the stack trace is not available, but exception information is, then the grouping will consider the `type` and `value` of the exception if both pieces of data are present on the event. This grouping is a lot less reliable because of changing error messages. + +### [Fallback Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#fallback-grouping) + +Grouping falls back to messages if the stack trace, `type`, and `value` are not available. When this happens, the grouping algorithm will try to use the message without any parameters. If that is not available, the grouping algorithm will use the full message attribute. + +### [AI-Enhanced Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#ai-enhanced-grouping) + +In addition to fingerprint-based grouping, Sentry uses AI to further improve issue grouping accuracy. This system helps identify semantically similar errors that might have different fingerprints due to minor code variations. The AI grouping system works alongside traditional fingerprinting - it only attempts to group new issues and will never split up issues that were grouped by fingerprint. + +This system will not apply to any events that have fully custom fingerprints (either set via SDK or [fingerprint rules](https://docs.sentry.io/product/issues/grouping-and-fingerprints/#fingerprint-rules)). However, events with fingerprints containing `{{ default }}` will use AI grouping to calculate the `{{ default }}` portion of the fingerprint. + +When Sentry's default fingerprinting algorithm generates a new hash, it automatically sends the error data to [Seer](https://github.com/getsentry/seer), our AI/ML service. That error data includes the message and in-app stack frames (including those configured with stack trace rules), or all frames when no in-app frames are present. + +Seer performs the following steps: + +1. It generates a vector representation of the error's stack trace using a transformer-based text embedding model +2. It compares this embedding against existing error embeddings for that project in the database +3. If a semantically similar error is found within the configured threshold, Sentry merges the new error into the existing issue + +[![Sentry Seer PostgreSQL.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-seer-postgresql-LJOM3IZL.png%231024x365&w=2048&q=75)](https://docs.sentry.io/mdx-images/sentry-seer-postgresql-LJOM3IZL.png) + +This algorithm is particularly effective at handling cases where: + +- Similar errors occur in different parts of the codebase +- Code changes or deployments introduce slight variations in stack traces +- Different error types represent the same underlying problem + +You can see issues that have been merged through this system in the “Merged Issues” section of the Issue Details UI. You can always unmerge any fingerprints that you would not like to see grouped, and our system will avoid grouping them in the future. + +[![Merged issues.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmerged-issues-AQLAWKNX.png%23653x302&w=1920&q=75)](https://docs.sentry.io/mdx-images/merged-issues-AQLAWKNX.png) + +## [Ways to Customize Error Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#ways-to-customize-error-grouping) + +If the way that Sentry is grouping issues for your organization is already ideal, you don't need to make any changes. However, you may find that Sentry is either creating too many similar groups, or is grouping disparate events into groups that should be separate. If this is the case, for **error issues**, you can extend and change the default grouping behavior. Error grouping can be extended and changed completely according to your needs. Transaction grouping currently cannot be customized. + +You can customize error grouping using a combination of the following options, listed from least to most complex: + +1. In your project, by [Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues/) + +> Merges together similar issues that have already been created. No settings or configuration changes are required for this. + +2. In your project, using [Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) + +> Sets a new fingerprint for incoming events based on matchers. This doesn't affect already existing issues. + +3. In your project, using [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/) + +> Sets rules for how incoming events should be treated based on matchers. This doesn't affect already existing issues. + +4. In your SDK, using [SDK Fingerprinting](https://docs.sentry.io/platform-redirect/?next=/usage/sdk-fingerprinting/) + +> Sets a new fingerprint for incoming events based on matchers in the SDK. This doesn't affect already existing issues. Note that is not supported in WebAssembly. + + +Stack trace rules can work as a combination of both SDK and project settings. As a result, we maintain the documentation in one location. + +## [How to View the Fingerprint](https://docs.sentry.io/concepts/data-management/event-grouping/\#how-to-view-the-fingerprint) + +You can see a fingerprint by opening an issue, clicking " View JSON", and finding the _fingerprint_ property in that file. If the default grouping was used, you'll see "default" written there. If a different grouping was used, you'll see the actual fingerprint value itself. + +View Issue Fingerprint + +View Issue Fingerprint + +![Find the "fingerprint" property. Here, the default grouping was used.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/5658b67b-26f6-43e4-b387-5f03fec20a58.png)![Step 3](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/a7572aab-076a-43a1-b9c2-2c13a5b9bddb.png)![Click to open the JSON file.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/75e0d829-0db7-43f6-ac17-4d3a363f7015.png) + +Click to open the JSON file. + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +[iframe](cid:frame-935AB59C0A5CD926EDCF406CE7365D34@mhtml.blink) + +## [Transaction Grouping Algorithms](https://docs.sentry.io/concepts/data-management/event-grouping/\#transaction-grouping-algorithms) + +Sentry groups transactions with performance problems into [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) using the transaction's `spans`. We fingerprint by the span evidence related to the performance problem found in the event. This includes the spans directly involved in the problem, as well as spans that might have caused the problem or are closely related to it. This algorithm isn't currently customizable or extendable. + +## [Learn More](https://docs.sentry.io/concepts/data-management/event-grouping/\#learn-more) + +[Previous\\ +\\ +Data Management](https://docs.sentry.io/concepts/data-management) + +[Next\\ +\\ +Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Permissions & Scopes](https://docs.sentry.io/api/permissions/) + +# Permissions & Scopes + +If you're building on top of Sentry's API (i.e using [Auth Tokens](https://docs.sentry.io/api/auth/)), you'll need certain scopes to access different API endpoints. + +To set the scopes for an [integration token](https://docs.sentry.io/organization/integrations/integration-platform/#permissions), select the scopes from the dropdown. These can be edited later. + +To set the scopes for an auth token, select the scopes from the dropdown when [creating an auth token](https://sentry.io/api/). These cannot be edited later. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-token-create-ZKQIPVXA.png%232396x1404&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-token-create-ZKQIPVXA.png) + +If you're looking for information on membership roles please visit the [membership](https://docs.sentry.io/organization/membership/) documentation. + +### [Organizations](https://docs.sentry.io/api/permissions/\#organizations) + +| | | +| --- | --- | +| **GET** | `org:read` | +| **PUT/POST** | `org:write` | +| **DELETE** | `org:admin` | + +### [Projects](https://docs.sentry.io/api/permissions/\#projects) + +| | | +| --- | --- | +| **GET** | `project:read` | +| **PUT/POST** | `project:write` | +| **DELETE** | `project:admin` | + +##### Note + +The `project:releases` scope will give you access to both **project** and **organization** release endpoints. The available endpoints are listed in the [Releases](https://docs.sentry.io/api/releases/) section of the API Documentation. + +### [Teams](https://docs.sentry.io/api/permissions/\#teams) + +| | | +| --- | --- | +| **GET** | `team:read` | +| **PUT/POST** | `team:write` | +| **DELETE** | `team:admin` | + +### [Members](https://docs.sentry.io/api/permissions/\#members) + +| | | +| --- | --- | +| **GET** | `member:read` | +| **PUT/POST** | `member:write` | +| **DELETE** | `member:admin` | + +### [Issues & Events](https://docs.sentry.io/api/permissions/\#issues--events) + +| | | +| --- | --- | +| **GET** | `event:read` | +| **PUT** | `event:write` | +| **DELETE** | `event:admin` | + +##### Note + +**PUT/DELETE** methods only apply to updating/deleting issues. Events in Sentry are immutable and can only be deleted by deleting the whole issue. + +### [Releases](https://docs.sentry.io/api/permissions/\#releases) + +| | | +| --- | --- | +| **GET/PUT/POST/DELETE** | `project:releases` | + +##### Note + +Be aware that if you're using `sentry-cli` to [manage your releases](https://docs.sentry.io/cli/releases/), you'll need a token which also has `org:read` scope. + +[Previous\\ +\\ +Paginating Results](https://docs.sentry.io/api/pagination) + +[Next\\ +\\ +Rate Limits](https://docs.sentry.io/api/ratelimits) + +- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) + +# Authentication + +[Previous\\ +\\ +Set Up Your Organization](https://docs.sentry.io/organization/getting-started) + +[Next\\ +\\ +Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) + +# Searchable Properties + +## Learn more about searchable properties. + +Sentry's search provides you with reserved keywords, like `is`, `user`, `server`, and `browser`, that you can use to search on the properties of issues, events and replays (as well as the special case of releases). You can also create [custom tags](https://docs.sentry.io/concepts/search/searchable-properties/#custom-tags) on which to search. This page provides guidance for how to use these properties and links you to the respective seachable property lists. + +## [Search Properties](https://docs.sentry.io/concepts/search/searchable-properties/\#search-properties) + +Sentry's searchable properties fall into one of five categories: + +- [Issue properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/) +- [Event properties](https://docs.sentry.io/concepts/search/searchable-properties/events/) +- [Span properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) +- [Session Replay properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/) +- [User Feedback properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/) +- [Release properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/) + +## [Search Tips](https://docs.sentry.io/concepts/search/searchable-properties/\#search-tips) + +Search terms should auto-complete, and when they don't that means you have an invalid dataset. If you enter an invalid search term and tap Return or Enter, an error message is displayed. For example, in **Discover**, you cannot search using a grouping function (properties with a parentheses in the key, for example `epm()`) if you don't already have a grouping function included in the "Results" table columns. + +When you search using a property that's a function, if the key includes a parameter, you still need to add a filter or value to have a complete search token. For example, the function `count_unique(field)` takes whichever field you choose as the parameter and then you add a number as your value to filter on. So a typical search might look like: `count_unique(user):>=20`. + +Other things to note: + +- Search properties that are duration or number types are typically used with a [comparison operator](https://docs.sentry.io/concepts/search/#comparison-operators) rather than just a colon ( `:`) to find exact matches, as an exact match is unlikely to exist. +- Properties with the notation "Doesn't take a parameter" still require a filter or value, but don't take a parameter inside the parentheses. For example, `epm():>12`. +- Default fields/parameters in search functions can be updated. For example, the default parameters `column`, `operator`, and `value` can be updated for `count_if(column,operator,value)`. + +## [Custom Tags](https://docs.sentry.io/concepts/search/searchable-properties/\#custom-tags) + +Additionally, you can use any tag you’ve specified as a token. Tags are various key/value pairs that get assigned to an event, and you can use them later as a breakdown or quick access to finding related events. + +Most SDKs generally support configuring tags by [configuring the scope](https://docs.sentry.io/platform-redirect/?next=%2Fenriching-events%2Ftags%2F). + +Several common uses for tags include: + +- The hostname of the server +- The version of your platform (for example, iOS 5.0) +- The user’s language + +## [Device Classification](https://docs.sentry.io/concepts/search/searchable-properties/\#device-classification) + +`device.class` provides a simple way for developers to understand the performance level of an event's client device in a single searchable property. This is particularly useful for projects that serve a large range of mobile devices, in which case developers would typically have had to parse through a vast range of specs and models across iOS and Android. + +Possible values for `device.class` are `high`, `medium`, and `low`, indicating the estimated performance level of the device. This is a calculated property that is based on the following specs: + +| `device.class` for iOS | `model` | +| --- | --- | +| high | iPhone 12 series or higher | +| medium | iPhone 7 series to iPhone 11 series | +| low | iPhone 6 series or lower | + +| `device.class` for Android | `processor_count` | `processor_frequency` | `memory_size` | +| --- | --- | --- | --- | +| high | >= 8 | >= 2500 MHz | >= 6 GiB | +| medium | >= 8 | >= 2000 MHz | >= 4 GiB | +| low | < 8 | < 2000 MHz | < 4 GiB | + +These classifications are based on an analysis of the mobile devices available in the market today and are subject to change as the market evolves. + +[Previous\\ +\\ +Search](https://docs.sentry.io/concepts/search) + +[Next\\ +\\ +Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) + +# Organization Settings + +## Learn how to configure your organization's Sentry account, including 2FA authentication, user management, and data storage location. + +[Previous\\ +\\ +Account Settings](https://docs.sentry.io/account) + +[Next\\ +\\ +Set Up Your Organization](https://docs.sentry.io/organization/getting-started) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Metrics](https://docs.sentry.io/cli/metrics/) + +# Metrics + +## Learn how Sentry's command line interface can be used for sending metrics. + +##### The Metrics beta has ended on October 7th + +Thank you for participating in our Metrics beta program. After careful consideration, we have ended the beta program and retired the current Metrics solution. We're actively developing a new solution that will make tracking and debugging any issues in your application easier. [Learn more](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Upcoming-API-Changes-to-Metrics). + +Metrics help you track and visualize the data points you care about, making it easier to monitor your application's health and identify issues. Learn more about [Metrics](https://docs.sentry.io/product/explore/metrics/). + +## [Requirements](https://docs.sentry.io/cli/metrics/\#requirements) + +- [Install](https://docs.sentry.io/cli/installation/) the Sentry CLI (min v2.32.0). + +## [Configuration](https://docs.sentry.io/cli/metrics/\#configuration) + +The Sentry CLI uses your project's DSN to authorize sending metrics. To set it up, export the `SENTRY_DSN` environment variable: + +Bash + +`` + +```bash code-highlight +export SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 + +``` + +Alternatively, you can add it to your `~/.sentryclirc` config file: + +Ini + +`~/.sentryclirc` + +```code-highlight ini +[auth] +dsn = https://examplePublicKey@o0.ingest.sentry.io/0 + +``` + +## [Sending metrics](https://docs.sentry.io/cli/metrics/\#sending-metrics) + +You can send metrics using the CLI's `send-metric` command. You need to provide at least the `--name` or `-n` parameter to identify the metric. When emitting a metric that doesn't exist, the metric will be created for you. If it already exists, it will be updated. All metric types support custom units and tags provided with the `-u` and `-t` parameters respectively: + +Bash + +`` + +```bash code-highlight +sentry-cli send-metric increment -n "MyMetric" -u "MyUnit" -t "tag1:val1","tag2:val2" + +``` + +The metric's name, unit, and tags will undergo normalization to only include supported characters. Learn more about [Limits and Restrictions](https://docs.sentry.io/product/explore/metrics/#limits-and-restrictions). + +### [Counters](https://docs.sentry.io/cli/metrics/\#counters) + +To increment a counter metric by one, you only need to provide the `--name` or `-n` parameter. A counter metric can also be incremented by a custom value using the `-v` parameter: + +Bash + +`` + +```bash code-highlight +sentry-cli send-metric increment -n "button_click" -v 2 + +``` + +### [Gauges](https://docs.sentry.io/cli/metrics/\#gauges) + +To emit a gauge metric, you always need to provide the name and value: + +Bash + +`` + +```bash code-highlight +sentry-cli send-metric gauge -n "bundle_size" -v 384 -u "byte" + +``` + +### [Distributions](https://docs.sentry.io/cli/metrics/\#distributions) + +Similar to gauges, you need to provide the name and value to emit a distribution metric: + +Bash + +`` + +```bash code-highlight +sentry-cli send-metric distribution -n "build_time" -v 120 -u "millisecond" + +``` + +### [Sets](https://docs.sentry.io/cli/metrics/\#sets) + +To emit a set metric, you need to provide the name and value where the value can be any number or string: + +Bash + +`` + +```bash code-highlight +sentry-cli send-metric set -n "build_platform" -v "android" + +``` + +[Previous\\ +\\ +Sentry CLI](https://docs.sentry.io/cli) + +[Next\\ +\\ +Installation](https://docs.sentry.io/cli/installation) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/metrics.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Requests](https://docs.sentry.io/api/requests/) + +# Requests + +All API requests should be made to the `/api/0/` prefix, and will return JSON as the response: + +BashHttp + +`` + +```bash code-highlight +curl -i https://sentry.io/api/0/ + +``` + +## [HTTP Verbs](https://docs.sentry.io/api/requests/\#http-verbs) + +Sentry makes an attempt to stick to appropriate HTTP verbs, but we always prioritize usability over correctness. + +| Method | Description | +| --- | --- | +| `DELETE` | Used for deleting resources. | +| `GET` | Used for retrieving resources. | +| `OPTIONS` | Describes the given endpoint. | +| `POST` | Used for creating resources. | +| `PUT` | Used for updating resources. Partial data is accepted where possible. | + +## [Parameters and Data](https://docs.sentry.io/api/requests/\#parameters-and-data) + +Any parameters not included in the URL should be encoded as JSON with a Content-Type of `'application/json'`: + +Bash + +`` + +```bash code-highlight +curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/ \ + -d '{"status": "resolved"}' \ + -H 'Content-Type: application/json' + +``` + +Additional parameters are sometimes specified via the querystring, even for `POST`, `PUT`, and `DELETE` requests: + +Bash + +`` + +```bash code-highlight +curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/?status=unresolved \ + -d '{"status": "resolved"}' \ + -H 'Content-Type: application/json' + +``` + +[Previous\\ +\\ +Rate Limits](https://docs.sentry.io/api/ratelimits) + +[Next\\ +\\ +Alerts & Notifications](https://docs.sentry.io/api/alerts) + +- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) + +# API Reference + +The Sentry web API is used to access the Sentry platform programmatically. You can use the APIs to manage account-level resources, like organizations and teams, as well as manage and export data. + +If you're looking for information about the API surface for Sentry's SDKs, see the [SDK Development](https://develop.sentry.dev/sdk/overview/) docs. + +## [Versioning](https://docs.sentry.io/api/\#versioning) + +The current version of the Sentry's web API is considered **v0**. Our public endpoints are generally stable, but beta endpoints are subject to change. + +## [Getting Started](https://docs.sentry.io/api/\#getting-started) + +- [Authentication](https://docs.sentry.io/api/auth/) +- [Pagination](https://docs.sentry.io/api/pagination/) +- [Permissions](https://docs.sentry.io/api/permissions/) +- [Rate Limits](https://docs.sentry.io/api/ratelimits/) +- [Requests](https://docs.sentry.io/api/requests/) + +### [Sentry API Tutorials](https://docs.sentry.io/api/\#sentry-api-tutorials) + +- [Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) +- [Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial/) + +## [Choosing the Right API Base Domain](https://docs.sentry.io/api/\#choosing-the-right-api-base-domain) + +While many of our APIs use `sentry.io` as the host for API endpoints, if you want to indicate a specific [data storage location](https://docs.sentry.io/organization/data-storage-location/#what-types-of-data-are-stored-where), you should use region-specific domains. + +- US region is hosted on `us.sentry.io` +- DE region is hosted on `de.sentry.io`. + +To find out which API resources are available on region-based domains, see [what types of data are stored where](https://docs.sentry.io/organization/data-storage-location/#what-types-of-data-are-stored-where) for more information. + +[Previous\\ +\\ +Sentry CLI](https://docs.sentry.io/cli) + +[Next\\ +\\ +Authentication](https://docs.sentry.io/api/auth) + +- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Search](https://docs.sentry.io/contributing/pages/search/) + +# Search + +Search is powered by Algolia, and will index all content in `/docs/` that is Markdown or MDX formatted. + +It will _not_ index documents with any of the following in their frontmatter: + +- `draft: true` +- `noindex: true` + +[Previous\\ +\\ +Redirects](https://docs.sentry.io/contributing/pages/redirects) + +[Next\\ +\\ +Banners](https://docs.sentry.io/contributing/pages/banners) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/search.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Account Settings](https://docs.sentry.io/account/) +- [Account Preferences](https://docs.sentry.io/account/user-settings/) + +# Account Preferences + +## Learn how to customize your User Settings for a more personalized Sentry experience. + +[Account preferences](https://sentry.io/settings/account/details/) help you customize your Sentry experience. Manage your account by selecting "User settings" from the dropdown under your organization’s name. On this page, you can control the frequency of your [email notifications](https://docs.sentry.io/account/user-settings/#notifications), [change your primary email](https://docs.sentry.io/account/user-settings/#emails), and update your security settings. + +## [Security Settings](https://docs.sentry.io/account/user-settings/\#security-settings) + +Security Settings include options to reset a password, sign out of all devices, and enable two-factor authentication. + +### [Two-Factor Authentication](https://docs.sentry.io/account/user-settings/\#two-factor-authentication) + +After setting up your two-factor authentication codes, click "View Codes" to download, print, or copy your codes to a secure location. If you cannot receive two-factor authentication codes in the future, such as if you lose your device, use your recovery codes to access your account. + +Clicking "Sign out of all devices" will end your sessions with any device logged in to Sentry using your account. + +## [Notifications](https://docs.sentry.io/account/user-settings/\#notifications) + +In **Notifications**, you can configure your personal settings for the following Sentry notifications: + +- Alerts (issue alerts only) +- Deploy +- Workflow +- Weekly Reports +- My Activity + +You can also set your email routing here. + +Learn more in the [full Notifications documentation](https://docs.sentry.io/product/alerts/notifications/). + +## [Emails](https://docs.sentry.io/account/user-settings/\#emails) + +The email address used to log into your Sentry account is, by default, your primary email address. Add an alternative email address in the [Add Secondary Emails](https://sentry.io/settings/account/emails/) section. After verifying your secondary email, you can set it to become your primary email. + +[![After verifying the secondary email, you can change it to the primary email.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fchange-primary-email-WHCEW7FR.png%231500x514&w=3840&q=75)](https://docs.sentry.io/mdx-images/change-primary-email-WHCEW7FR.png) + +## [Close Account](https://docs.sentry.io/account/user-settings/\#close-account) + +Warning: Deleting your account cannot be undone. + +Closing your Sentry account automatically [removes all data](https://sentry.io/security/#data-removal) associated with your account after a 24-hour waiting period to prevent accidental cancellation. If your account is the sole owner of an organization, this organization will be deleted. Organizations with multiple owners will remain unchanged. For details about termination of service, see [Term, Termination, and Effect of Termination](https://sentry.io/terms/#term-termination-and-effect-of-termination). + +[Previous\\ +\\ +Account Settings](https://docs.sentry.io/account) + +[Next\\ +\\ +Auth Tokens](https://docs.sentry.io/account/auth-tokens) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/user-settings/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) + +# Data & Visualization + +## Learn more about Sentry's data and visualization integrations. + +- [Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/) +- [Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana/) +- [Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment/) +- [Splunk](https://docs.sentry.io/organization/integrations/data-visualization/splunk/) + +[Previous\\ +\\ +Deployment](https://docs.sentry.io/organization/integrations/deployment) + +[Next\\ +\\ +Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling/) + +# Dynamic Sampling + +## Learn how to prioritize important events and increase visibility in lower-volume projects with Dynamic Sampling. + +## [Overview](https://docs.sentry.io/organization/dynamic-sampling/\#overview) + +Projects that generate large event volume can quickly consume your billing quota. This may create an imbalance where high-volume projects get more visibility, leaving insufficient quota for monitoring your other projects. That's where dynamic sampling comes in. + +Dynamic Sampling employs advanced sampling techniques to retain a representative sample of the data you send to Sentry. Its algorithms are designed to prioritize keeping samples that are valuable for debugging and analysis, while reducing the retention of common or redundant data. + +This process is applied directly on Sentry's servers, which allows you to configure and adjust sampling rates for stored spans right from the UI without needing to modify your SDK. This makes it possible for you to make instant updates without waiting for code freezes, app store approvals, or redeployments. + +By analyzing incoming traffic patterns, Dynamic Sampling is able to tailor its decisions to both the actual traffic volume as well as the content of accepted spans. For more details, check out the [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) section. + +Dynamic Sampling including Sampling Priorities has been available on paid plans since November 2022. Configuration of custom sample rates has been available on our latest Enterprise plans since June 2024. + +## [Prerequisites](https://docs.sentry.io/organization/dynamic-sampling/\#prerequisites) + +- [Admin-level permissions](https://docs.sentry.io/organization/membership/). +- Latest version of one of the below SDKs: + - Python: 1.7.2 or later + - JavaScript: 7.6.0 or later + - Apple: 7.23.0 or later + - Android: 6.5.0 or later + - React Native: 4.3.0 or later + - Dart and Flutter: 6.11.0 or later + - PHP: 3.9.0 or later + - Laravel: 3.0.0 or later + - Symfony: 4.4.0 or later + - Ruby: 5.5.0 or later + - Java: 6.5.0 or later + - .NET: 3.22.0 or later + - Go: 0.16.0 or later + +## [Configuration](https://docs.sentry.io/organization/dynamic-sampling/\#configuration) + +In this section, you'll learn how to use Dynamic Sampling in your organization. Dynamic Sampling offers two modes based on the desired sampling control: + +- **Default mode** allows you to set an organization level target sample rate and automatically adjusts project level sampling to match the organization level sample rate. +- **Advanced mode** gives you more granular control by allowing you to manually set the sampling rate at the project level. + +[![The dynamic sampling settings overview](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmode-and-target-sample-rate-KAGWNIMW.png%231625x785&w=3840&q=75)](https://docs.sentry.io/mdx-images/mode-and-target-sample-rate-KAGWNIMW.png) + +### [Default Mode](https://docs.sentry.io/organization/dynamic-sampling/\#default-mode) + +To use Dynamic Sampling in default mode, you have to specify a target sample rate for your entire organization, which determines how much incoming traffic should be stored across all your projects. Dynamic Sampling then distributes this sample rate across your projects automatically. Sample rates are adjusted continuously to account for changes in event volume over time. + +**The following adjustments are performed:** + +- Low-Volume Projects get a higher sample rate, ensuring important data isn’t missed. +- High-Volume Projects have reduced sample rates to balance overall storage. +- Sample rates are continuously adjusted based on recent traffic patterns, using a short sliding window to adapt to seasonal changes like holidays, weekends, and nighttime traffic. + +Dynamic Sampling also prioritizes the most valuable data within each project's allocated sample rate. You can learn more about this in the [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) section. This dynamic system ensures your sampling adapts to changing traffic and maintains balance across projects. + +### [Advanced Mode](https://docs.sentry.io/organization/dynamic-sampling/\#advanced-mode) + +If you want more fine-grained control, you can customize data retention by setting individual sample rates for specific projects by enabling the advanced mode. + +Here you can configure a fixed sample rate for each project in your organization. This value will specify the percentage of incoming traffic that should be stored for each respective project. The sample rate can be between 0% and 100%, defaulting to 100% if not adjusted. + +[![Advanced dynamic sampling settings](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fadvanced-DILP6TJT.png%231623x897&w=3840&q=75)](https://docs.sentry.io/mdx-images/advanced-DILP6TJT.png) + +When you edit the sample rates for individual projects, an estimated overall sample rate for your organization will also be calculated. This is a weighted average based on the volume of traffic for each project. Keep in mind that this value is an estimate and may change as the volume of traffic fluctuates. + +To adjust the sample rates of all your projects at once, edit the overall sample rate for your organization by going to the [Dynamic Sampling settings page](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/). This will proportionally update each project's sample rate to meet your chosen target. The maximum rate is 100%, and adjustments will be made to balance the rates across projects. You'll be able to review and finalize the updated sample rates before saving. Make sure to click the "Apply changes" button to save the new sample rates. + +[![Change all projects at once in Advanced Mode](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fadvanced-org-level-X3NSW7CF.png%231500x631&w=3840&q=75)](https://docs.sentry.io/mdx-images/advanced-org-level-X3NSW7CF.png) + +Whether advanced mode is activated or not, [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) will be applied within each project, boosting certain spans and deprioritizing others. + +When you deactivate advanced mode, the recalibration process will start immediately and the per-project sample rates will be reset to the calculated values. There's no way to restore the manually configured project sample rates once you've deactivated advanced mode. + +### [Project Preview](https://docs.sentry.io/organization/dynamic-sampling/\#project-preview) + +The [project preview](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/) table on the Dynamic Sampling settings page shows you how your projects might be affected by the sample rate you've chosen. The preview shows the dynamically allocated rates for your projects based on either the last 24 hours or the last 30 days of traffic. + +[![The Dynamic Sampling mode and target sample rate setting](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-sample-rate-preview-3CFQ3HW3.png%231884x1160&w=3840&q=75)](https://docs.sentry.io/mdx-images/project-sample-rate-preview-3CFQ3HW3.png) + +Because project rates continuously change, we recommend that you choose the 24-hour preview to get a more accurate view of your current sample rates for real-time analysis. We recommend the 30-day preview for seeing average sample rates in your billing cycle for long-term planning. + +## [Sample Rates for Distributed Traces](https://docs.sentry.io/organization/dynamic-sampling/\#sample-rates-for-distributed-traces) + +Because [distributed traces](https://docs.sentry.io/product/tracing/#whats-distributed-tracing) can originate in one project and have spans going across multiple other projects, it's important to note that Sentry **always applies the sample rate of the project where the trace originated** to every project that's part of that trace. + +For example, if a trace starts in your frontend application, the sample rate you've set there will apply to a connected backend application that's part of the same trace. The same rule applies if the trace starts in a backend application. + +If you navigate to the [project preview](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/) table, you'll see the number of sent spans next to the origin project where the trace started. This includes any spans from propogated traces in other projects that are connected to the origin project. This gives you a direct view of how many spans will be affected by the sample rates you configure. To see the span counts broken down by the project they belong to, click the expand icon to the left of each project in the preview. + +[![Diagram showing the effect of dynamic sampling on distriubuted traces](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fclient-to-backend-accumulated-sampling-effect-55JKSEJV.png%232832x1790&w=3840&q=75)](https://docs.sentry.io/mdx-images/client-to-backend-accumulated-sampling-effect-55JKSEJV.png) + +## [SDK versus Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling/\#sdk-versus-dynamic-sampling) + +SDK sampling happens at the application level, before events are sent to Sentry. It filters events by sending only a set percentage, reducing data volume and instrumentation overhead. This helps with managing high event volumes directly at the source. + +Dynamic sampling, on the other hand, happens at the server level after events are sent to Sentry. Sample rates are adjusted dynamically based on the volume of events received by Sentry, without requiring any changes to the application. + +SDK sample rates can usually only be changed when a new version of the application is deployed, unless a custom mechanism has been implemented making it possible to change the sample rate dynamically. But with Dynamic Sampling, it's possible to configure the sampling rate for each project in your organization dynamically, without requiring any changes to the application. + +Additionally, advanced mode is not active, Dynamic Sampling continuously monitors the traffic for each project and adjusts the sample rate of each to prioritize the most relevant data. + +### [When to Use Dynamic Versus SDK Sampling](https://docs.sentry.io/organization/dynamic-sampling/\#when-to-use-dynamic-versus-sdk-sampling) + +The biggest benefit of Dynamic Sampling is its flexibility. It adjusts the sample rate based on the volume of events received by Sentry. This makes it a great choice for organizations with both high and low-volume projects, as it helps maximize your quota by tailoring the sample rate to each project's event volume. + +Dynamic Sampling can prioritize spans based on their content, offering more insight than SDKs. For example, it can focus on spans from the latest release or low-volume projects, giving you better visibility into the most important parts of your application. + +SDK sampling uses a static rate set in the SDK configuration. It’s ideal for organizations with consistent event volumes that want to limit the percentage of events sent to Sentry. This helps reduce spans to lower overhead, save bandwidth (especially for mobile apps), or decrease the number of accepted spans. + +### [Deciding on Your SDK Sample Rate](https://docs.sentry.io/organization/dynamic-sampling/\#deciding-on-your-sdk-sample-rate) + +To give Sentry the fullest, most accurate picture of your application’s health, we recommend sending us 100% of your events. You can do this by setting your [tracesSampleRate](https://docs.sentry.io/platform-redirect/?next=/performance/) to 1.0. If this isn't feasible for your organization, set a lower value, or switch to sampling selectively by using the [tracesSampler](https://docs.sentry.io/platform-redirect/?next=/performance/) to filter your events based on contextual data. Note, that when calculating throughput, metering is based on received, not stored events. + +Changes to your SDK sampling configuration may affect your quota. If you increase your SDK sampling rate, you'll also be increasing the volume of events you send to Sentry. This may require that you adjust your quota. + +You can use both Dynamic and SDK Sampling together to further optimize your event volume for your specific use case. For example, you can set a low SDK sample rate to ensure that only a certain percentage of events are sent to Sentry, and then use Dynamic Sampling to adjust the sample rate based on the event volume received by Sentry. + +## [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#dynamic-sampling-priorities) + +Below is a list of the strategies Dynamic Sampling employs to prioritize and deprioritize data. They are enabled by default, but can be updated on a per-project basis to better fit your organization's needs. To customize this behavior, go to Project Settings > Performance. + +### [How to Change Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#how-to-change-dynamic-sampling-priorities) + +To make changes to a project's dynamic sampling priorities in Sentry, go to **Settings > Projects**, select the project you're interested in, then scroll down to "Performance" in the "PROCESSING" section and make any updates under "DYNAMIC SAMPLING PRIORITIES" using the toggles. Each of your projects can have an individual set of dynamic sampling priorities. + +General Settings — totes-ma-gotes — Sentry + +General Settings — totes-ma-gotes — Sentry + +![Choose the project you'd like to update retention priorities for.](<Base64-Image-Removed>)![Scroll down to Performance](<Base64-Image-Removed>)![Select Settings, then Projects](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/80f05eeb-d09d-4814-a0d3-3af39c4e1ba0.png) + +Select Settings, then Projects + +![](<Base64-Image-Removed>) + +reCAPTCHA + +Recaptcha requires verification. + +[Privacy](https://www.google.com/intl/en/policies/privacy/) \- [Terms](https://www.google.com/intl/en/policies/terms/) + +protected by **reCAPTCHA** + +[Privacy](https://www.google.com/intl/en/policies/privacy/) \- [Terms](https://www.google.com/intl/en/policies/terms/) + +### [Automatic Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#automatic-priorities) + +Sentry automatically prioritizes or deprioritizes based on the following rules: + +#### [Latest Release](https://docs.sentry.io/organization/dynamic-sampling/\#latest-release) + +Latest releases are a dynamic sampling priority because when you create a new release, we assume you'll want to have more visibility during the early adoption phase, which improves your ability to catch new issues as your release is gaining traction. Because you may want to deploy the same release in different environments, we'll also take your environment into account and prioritize those traces. + +#### [Dev Environments](https://docs.sentry.io/organization/dynamic-sampling/\#dev-environments) + +Since dev environments usually generate a small number of events as compared to prod environments, we prioritize them during your testing phase so you can get meaningful insights. We consider an environment to be a dev environment if its name matches one of the following glob patterns: + +- `*debug*` +- `*dev*` +- `*local*` +- `*qa*` +- `*test*` + +#### [Low Volume Projects](https://docs.sentry.io/organization/dynamic-sampling/\#low-volume-projects) + +You won't be able to disable the Low Volume Projects dynamic sampling priority because it's set on an organization-wide level, not on a per-project basis. + +Some projects within your organization are very high-volume compared to others. This means that low-volume projects might get drowned out if we treat all projects equally. To ensure that you have enough samples regardless of project scale, we prioritize low-volume projects. + +#### [Low Volume Transactions](https://docs.sentry.io/organization/dynamic-sampling/\#low-volume-transactions) + +Spans can be logically grouped by their transaction name within a project. This means that spans with the same transaction name most likely indicate the same operation or code path, while spans with different transaction names usually indicate different operations. We prioritize low-volume transactions for the same reason we prioritize low-volume projects: so they don't get drowned out by high-volume transactions. We want to make sure that low-volume code paths are sampled in enough quantities to generate a complete view of your application. + +#### [Health Checks](https://docs.sentry.io/organization/dynamic-sampling/\#health-checks) + +We deprioritize health check type transactions because while they're important for checking the stability of your application, they don't have any value beyond the task associated with them. We consider a transaction to be a health check if its name matches one of the following glob patterns: + +- `*healthcheck*` +- `*heartbeat*` +- `*/health` +- `*/healthy` +- `*/healthz` +- `*/live` +- `*/livez` +- `*/ready` +- `*/readyz` +- `*/ping` + +### [Get Samples](https://docs.sentry.io/organization/dynamic-sampling/\#get-samples) + +Our automated dynamic sampling priorities work well in a generic manner to collect a baseline of samples because they prioritize retaining data that's valuable for any customer at any given time. However, there are certain scenarios, such as investigating a particular issue, when very specific data becomes temporarily more important. In such cases, the automated sampling priorities may not provide enough samples, so you may want to create investigation rules. + +Investigation rules are sampling rules that can be created through the Sentry UI to temporarily boost the number of events collected for a particular scenario (for example, events with specific tag values). These rules can be created to retain more samples when too few (less than 5) are available. Once created, a rule will be active for up to 48 hours or until 100 samples are collected. You'll be notified via email when enough events have been collected. + +Investigation sampling rules only apply to transactions and don't guarantee that full traces will be sampled. The maximum number of sampling rules that can exist at the same time is 50. + +#### [Creating a New Rule](https://docs.sentry.io/organization/dynamic-sampling/\#creating-a-new-rule) + +When you query transactions either in [Discover](https://docs.sentry.io/product/explore/discover-queries/) or in [Transaction Summary](https://docs.sentry.io/product/performance/transaction-summary/) and receive fewer than 5 samples, you can click "Get Samples" to create a new investigation rule and retain more samples of transactions for the respective query. + +[![Investigation Mode in Discover](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-discover-SEDWQ64B.png%232176x1562&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-discover-SEDWQ64B.png) + +This feature only applies to transactions. Therefore, in Discover, you have to specify `event.type:transaction` in the query to access the feature, whereas in Performance the event type is implicit. + +Clicking this button creates an investigation rule for the query. Once the rule is successfully created, a notification appears, and the button is replaced with a message showing the investigation is in progress and the amount of time it's been active. + +[![Rule successfully created](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-rule-created-Y4JFENSI.png%231970x644&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-rule-created-Y4JFENSI.png) + +If a user performs the same search later and the investigation is still active, the notification will indicate that there's an active rule already collecting data for the query. + +It's also possible to create a rule from the Transaction Summary page in Performance. + +[![Investigation Mode in Transaction Summary](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-tx-summary-CQIO4I7G.png%231834x1532&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-tx-summary-CQIO4I7G.png) + +[Previous\\ +\\ +Data Storage Location (US or EU)](https://docs.sentry.io/organization/data-storage-location) + +[Next\\ +\\ +Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/dynamic-sampling/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) + +# Search + +## Learn more about how to search in Sentry, including the correct query syntax, searchable properties, and custom tags. + +Search is available on several features throughout [sentry.io](https://sentry.io/), such as **Issues**, **Discover** and **Dashboards**. + +## [Query Syntax](https://docs.sentry.io/concepts/search/\#query-syntax) + +You'll only need to use query syntax if you're using a Sentry [API](https://docs.sentry.io/api/). You'll get pre-populated suggestions once you start typing in your search terms when using the search bar anywhere in [Sentry.io](https://sentry.sentry.io/). + +Search queries are constructed using a `key:value` pattern, with an optional raw search at the end. Each `key:value` pair is a `token` and the optional raw search is itself a single `token`. The `key:value` pair `tokens` are treated as issue or event properties. The optional raw search is treated as a single `token` and searches event titles/messages. + +For example: + +Bash + +`` + +```bash code-highlight +is:resolved user.username:"Jane Doe" server:web-8 example error + +``` + +In the example above, there are three keys ( `is:`, `user.username:`, `server:`), but four tokens: + +- `is:resolved` +- `user.username:"Jane Doe"` +- `server:web-8` +- `example error` + +The tokens `is:resolved` and `user.username:"Jane Doe"` are standard search tokens because both use reserved keywords. See [Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/#issue-properties) and [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/#event-properties) for appropriate keyword usage. The token `server:web-8` is pointing to a custom tag sent by the Sentry SDK. See [Custom Tags](https://docs.sentry.io/concepts/search/searchable-properties/#custom-tags) for more information on how to set tags. + +The token `example error` is utilizing the optional raw search and is passed as part of the issue search query (which uses a CONTAINS match similar to SQL). When using the optional raw search, you can provide _one_ string, and the query uses that entire string. + +Search terms should auto-complete, and when they don't, that means your term is incompatible with the dataset. If you complete the term and tap the Return/Enter key, an error message is displayed. + +### [Comparison Operators](https://docs.sentry.io/concepts/search/\#comparison-operators) + +Sentry search supports the use of comparison operators: + +- greater than ( **`>`**) +- less than ( **`<`**) +- greater than or equal to ( **`>=`**) +- less than or equal to ( **`<=`**) + +Typically, when you search using properties that are numbers or durations, you should use comparison operators rather than just a colon ( `:`) to find exact matches, since an exact match isn't likely to exist. + +Here are some examples of valid comparison operator searches: + +- `event.timestamp:>2023-09-28T00:00:00-07:00` +- `count_dead_clicks:<=10` +- `transaction.duration:>5s` + +### [Using `OR` and `AND`](https://docs.sentry.io/concepts/search/\#using-or-and-and) + +`OR` and `AND` search conditions are only available for [Discover](https://docs.sentry.io/product/explore/discover-queries/), [Insights Overview](https://docs.sentry.io/product/insights/overview/), and [Metric Alerts](https://docs.sentry.io/product/alerts-notifications/metric-alerts/). + +Use `OR` and `AND` between tokens, and use parentheses `()` to group conditions. `AND` can also be used between non-aggregates and aggregates. However, `OR` cannot. + +- Non-aggregates filter data based on specific tags or attributes. For example, `user.username:jane` is a non-aggregate field. + +- Aggregates filter data on numerical scales. For example, `count()` is an aggregate function and `count():>100` is an aggregate filter. + + +Some examples of using the `OR` condition: + +Bash + +`` + +```bash code-highlight +# a valid `OR` query +browser:Chrome OR browser:Opera + +# an invalid `OR` query +user.username:janedoe OR count():>100 + +``` + +Also, the queries prioritize `AND` before `OR`. For example, "x `AND` y `OR` z" is the same as "(x `AND` y) `OR` z". Parentheses can be used to change the grouping. For example, "x `AND` (y `OR` z)". + +### [Multiple Values on the Same Key](https://docs.sentry.io/concepts/search/\#multiple-values-on-the-same-key) + +You can search multiple values for the same key by putting the values in a list. For example, "x:\[value1, value2\]" will find the the same results as "x:value1 `OR` x:value2". When you do this, the search returns issues/events that match any search term. + +An example of searching on the same key with a list of values: + +Bash + +`` + +```bash code-highlight +release:[12.0, 13.0] + +``` + +Currently, you can't use this type of search on the keyword `is` and you can't use wildcards with this type of search. + +### [Explicit Tag Syntax](https://docs.sentry.io/concepts/search/\#explicit-tag-syntax) + +We recommend you never use reserved keywords (such as `project_id`) as tags. But if you do, you must use the following syntax to search for it: + +Bash + +`` + +```bash code-highlight +tags[project_id]:tag_value + +``` + +### [Advanced](https://docs.sentry.io/concepts/search/\#advanced) + +Sentry also offers the following advanced search options: + +#### [Exclusion](https://docs.sentry.io/concepts/search/\#exclusion) + +By default, search terms use the `AND` operator; that is, they return the intersection of issues/events that match all search terms. + +To change this, you can use the negation operator `!` to _exclude_ a search parameter. + +Bash + +`` + +```bash code-highlight +is:unresolved !user.email:example@customer.com + +``` + +In the example above, the search query returns all Issues that are unresolved _and_ have not affected the user with the email address `example@customer.com`. + +#### [Wildcards](https://docs.sentry.io/concepts/search/\#wildcards) + +Search supports the wildcard operator `*` as a placeholder for specific characters and strings. + +Bash + +`` + +```bash code-highlight +browser:"Safari 11*" + +``` + +In the example above, the search query will match on `browser` values like `"Safari 11.0.2"`, `"Safari 11.0.3"`, etc. + +You may also combine operators like so: + +Bash + +`` + +```bash code-highlight +!message:"*Timeout" + +``` + +In the above example, the search query returns results which do not have message values like `ConnectionTimeout`, `ReadTimeout`, etc. + +## [Page Filters](https://docs.sentry.io/concepts/search/\#page-filters) + +Page filters allow you to narrow down the results shown on a page by selecting specific projects, environments, and date ranges. After you've set your filters, they'll persist as you navigate across pages in Sentry. + +[![Project selector](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-selector-G2TQ3YHO.png%23407x576&w=828&q=75)](https://docs.sentry.io/mdx-images/project-selector-G2TQ3YHO.png) + +If you want to see data for all your projects, click "Clear" in the project selector to clear any project filters. + +## [Learn more](https://docs.sentry.io/concepts/search/\#learn-more) + +[Previous\\ +\\ +Concepts](https://docs.sentry.io/concepts/key-terms) + +[Next\\ +\\ +Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Linking Variables](https://docs.sentry.io/contributing/linking/) + +# Linking Variables + +We create a variety of links in our documentation, but the most commonly-used link type connects content either between product guides and the platform pages or between platform pages themselves. Each of these may take a different format, depending on whether a platform needs to be specified. + +## [Product & Platform Links](https://docs.sentry.io/contributing/linking/\#product--platform-links) + +### [From Product to Platform](https://docs.sentry.io/contributing/linking/\#from-product-to-platform) + +We use this format when linking from the product guides to the platform content because it allows the user to specify their platform, if it is not already specified. For example: + +`Releases also offer significant additional features when you fully [configure your SDK](/platform-redirect/?next=/configuration/releases/).` + +In the above example, when the user clicks the link to the releases configuration content, but hasn't yet visited a platform page, they will be asked to specify their platform so the page can be populated with the correct code sample when viewed. If they have navigated into product from the platform content, and are now navigating back into their platform, the platform context is maintained. + +### [Within Platforms](https://docs.sentry.io/contributing/linking/\#within-platforms) + +We use this format when linking among or within the platform content: + +`You can set your own <PlatformLink to="/enriching-events/breadcrumbs/">breadcrumbs</PlatformLink> to make them more useful for debugging.` + +In the above example, when the user clicks the link to the breadcrumbs content, they will be navigated to the breadcrumbs content **within their specific platform**. If this link is used in product guides, and no platform is specified, the user will be navigated to the first platform listed, which is currently the Apple family of SDKs. + +### [Hardcoding the Platform](https://docs.sentry.io/contributing/linking/\#hardcoding-the-platform) + +We use this format when there's only one option for the platform, the content is not common to multiple platforms, or we want to force the reader to use this source of truth: + +`[NDK integration](/platforms/android/configuration/using-ndk/) is packed with the SDK and requires API level 16, though other levels are supported.` + +In the above example, there is only one place for users to learn about using Android's NDK, which is nested within the Android directory, so we can hardcode the path. + +### [To Product Pages](https://docs.sentry.io/contributing/linking/\#to-product-pages) + +We use this format when linking with our product content. Product guides do not currently need a platform to be specified. As a result, linking can define the path to the correct content in the `product` folder. For example: + +`You can also customize how events are grouped. Learn more about customized grouping in [Issue Grouping](/concepts/data-management/event-grouping/).` + +### [To External Pages](https://docs.sentry.io/contributing/linking/\#to-external-pages) + +We use this format when linking to external pages. Most typically, this is to the UI: + +`The **Performance** page is the main view in [sentry.io](https://sentry.io) where you can search or browse for transaction data.` + +### [To Sandbox](https://docs.sentry.io/contributing/linking/\#to-sandbox) + +Sandbox allows the user to explore the feature in an actual Sentry application with mocked data. + +`Learn more about this feature in our <SandboxLink scenario="releases">sandbox</SandboxLink>.` + +This will take the user to a project based on the current platform selection. However, you can also manually specify the target project using the `projectSlug` parameter. + +The `scenario` parameter specifies the landing page within the Sandbox application that the user will see, and if it is not specified, we default to the `issues` page. Possible values are: + +- `performance` +- `releases` +- `alerts` +- `discover` +- `dashboards` +- `projects` +- `oneDiscoverQuery` +- `oneIssue` +- `oneBreadcrumb` +- `oneStackTrace` +- `oneTransaction` +- `oneWebVitals` +- `oneTransactionSummary` +- `oneRelease` + +Additionally, you can use the `errorType` parameter to select a particular type of error. + +`Learn more about breadcrumbs in our <SandboxLink scenario="oneBreadcrumb" errorType="EXC_BAD_ACCESS" projectSlug="ios">sandbox</SandboxLink>.` + +## [Anchor Links](https://docs.sentry.io/contributing/linking/\#anchor-links) + +Anchor links (appended by the # symbol) further direct users to a specific section (rather than the general page). + +### [Within the Same Page](https://docs.sentry.io/contributing/linking/\#within-the-same-page) + +We use this format to link users to content that's further down the page (typically beyond the initial fold): + +`On this page, you can control the frequency of your [email notifications](#notifications), [change your primary email](#emails), and update your security settings.` + +### [On Another Page](https://docs.sentry.io/contributing/linking/\#on-another-page) + +We use this format to direct users to a specific heading on another page: + +`To add to your quota or review what happens when you exceed it, see [Increasing Quotas](/pricing/quotas/#increasing-quotas).` + +This type of link can be used also for linking to anchors on external pages: + +`Sessions last for [Django's default session length](https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-cookie-based-sessions), which is two weeks.` + +## [Images](https://docs.sentry.io/contributing/linking/\#images) + +All images live in the `/public/` folder. You can reference images in this folder by using its full path (minus `/public/`). + +For instance, to use the image, `/public/product/alerts/issue-alert.png`, in any file: + +`![Image alt text](product/alerts/issue-alert.png)` + +The folder structure of `docs` is duplicated in `public` so that you can still use relative paths to reference images in your content files. For more details, see [Images](https://docs.sentry.io/contributing/pages/images/). + +## [Email address](https://docs.sentry.io/contributing/linking/\#email-address) + +We use this format when we want to link an email address (often used for Early Adopter or Beta features): + +`For more information about access to Metric Alerts, feel free to reach out at [alerting-feedback@sentry.io](mailto:alerting-feedback@sentry.io).` + +[Previous\\ +\\ +Platforms & Guides](https://docs.sentry.io/contributing/platforms) + +[Next\\ +\\ +Pages](https://docs.sentry.io/contributing/pages) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/linking.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) +- [Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso/) + +# Okta SSO + +## Set up Okta single sign-on (SSO) on Sentry. + +## [Installation](https://docs.sentry.io/organization/authentication/sso/okta-sso/\#installation) + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. + +1. Sign in to your Okta organization with your administrator account. + +2. From the admin console's sidebar, click **Applications > Applications**, then click on "Browse App Catalog" (or "Add Application" for the old interface). + +3. Search for `Sentry`, then click "Add Integration" to be brought to the setup wizard. + +[![Sentry in Okta Gallery of Integrations](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-gallery-N6S553CH.png%232560x1000&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-gallery-N6S553CH.png) + +4. Provide the settings. Note that for "1. General Settings", you will not need to provide any special settings. For "2. Sign On Options", provide the following: + + + - Base URL: `https://sentry.io` Ensure that the Base URL does not have a trailing slash or whitespace at the end as they will break the redirect from Okta to Sentry. + + - Organization Slug: _YOUR\_ORG\_SLUG_ + + - You can find your organization slug in the URL: `https://sentry.io/organizations/YOUR_ORG_SLUG/` + - Email: `Email` + + +[![Configuring Sentry in Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-settings-for-sentry-4MRBQPLO.png%231332x2112&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-settings-for-sentry-4MRBQPLO.png) + +5. Click "Save" to create the Sentry app. + +6. When you're redirected to the app settings page, click "Sign On". + +7. Copy the "Metadata URL" in the set up instructions. + +[![Okta metadata URL in setup instructions](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-setup-instructions-page-3S3DZNQU.png%231890x672&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-setup-instructions-page-3S3DZNQU.png) + +8. Sign in to Sentry. Select **Settings > Auth > Configure Okta**. + +[![Sentry single sign-on configuration page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-sso-settings-page-NHI7KU7L.png%231024x663&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-sso-settings-page-NHI7KU7L.png) + +9. Paste the Metadata URL from Step 8, then click "Continue". + +[![Sentry single sign-on configuration for Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-settings-metadata-url-DNXJPERF.png%231024x292&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-settings-metadata-url-DNXJPERF.png) + + +Sentry will attempt to authenticate and link your account with Okta. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can: + +- Share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. + +- Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Okta. + +- Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. + + +If you make any changes, click "Save Settings" to complete your set up. + +[![Sentry single sign-on settings for Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-settings-for-okta-GIZIAQZJ.png%231024x980&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-settings-for-okta-GIZIAQZJ.png) + +## [SCIM Integration](https://docs.sentry.io/organization/authentication/sso/okta-sso/\#scim-integration) + +- See [Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim). + +[Previous\\ +\\ +Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso) + +[Next\\ +\\ +Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/okta-sso/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) + +# Compliance + +## Learn more about Sentry's compliance integrations. + +- [Truto](https://docs.sentry.io/organization/integrations/compliance/truto/) +- [Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta/) + +[Previous\\ +\\ +Feature Flags](https://docs.sentry.io/organization/integrations/feature-flag) + +[Next\\ +\\ +Truto](https://docs.sentry.io/organization/integrations/compliance/truto) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) + +# Platforms & Guides + +Platform content lives in `docs/platforms` and follows some specific rules to generate content. The content is rendered using the same features as all other [pages](https://docs.sentry.io/contributing/), but has some additional functionality exposed to clone content and encapsulate platforms as portals. + +Directory structure has meaning within the platforms directory, and looks something akin to: + +Bash + +`` + +```bash code-highlight +[platformName]/ + child.mdx + childTwo/ + index.mdx + common/ + aSharedPage.mdx + guides/ + [guideName]/ + uniqueChild.mdx + childTwo/ + index.mdx + +``` + +Platforms will generate a list of "guides" that inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs: + +Bash + +`` + +```bash code-highlight +/platforms/platformName/ +/platforms/platformName/config.yml +/platforms/platformName/child/ +/platforms/platformName/childTwo/ +/platforms/platformName/aSharedPage/ +/platforms/platformName/guides/guideName/ +/platforms/platformName/guides/guideName/config.yml +/platforms/platformName/guides/guideName/child/ +/platforms/platformName/guides/guideName/uniqueChild/ +/platforms/platformName/guides/guideName/childTwo/ +/platforms/platformName/guides/guideName/aSharedPage/ + +``` + +This is generated by inheriting all content with the `common/` directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see `aSharedPage` is loaded at two different URLs, and `childTwo` is overwritten by `guideName`. + +The sidebar on platform pages (handled by `<PlatformSidebar>`) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation. + +## [Configuration](https://docs.sentry.io/contributing/platforms/\#configuration) + +Configuration is read (in order) from `[namespace]/index.mdx` and `[namespace]/config.yml`. This means that a platform's index can be fully rendered via a common page. + +Valid configuration attributes are: + +`title` + +The display name for a platform. + +`supportLevel` + +The level of support. `production` (default) or `community` + +`caseStyle` + +The casing style for code samples. `canonical` (default), `camelCase`, `snake_case`, or `PascalCase` + +`categories` + +A list of categories for future support. Known values are `browser`, `mobile`, `desktop`, and `server`. + +`fallbackPlatform` + +The key to use for defaults. Can use full key syntax of `platformName` or `platformName.guideName`. + +`sdk` + +The name of the SDK, if available. Used to embed SDK information on pages. + +`aliases` + +A list of aliases for this platform. For example, "Cocoa" might apply to Apple, or "C#" might apply to .NET. + +`showIntegrationsInSearch` + +Whether to show integrations in the search results on the home page. + +**Note:** This is only applicable to platforms that have no guides like Python. + +## [Shared Content](https://docs.sentry.io/contributing/platforms/\#shared-content) + +Shared (duplicated) content within an SDK (platform) is available in the `src/platforms/[platformName]/common/` folder. + +All of this content will be automatically duplicated within every guide. This leverages components like `PlatformContent` which can automatically substitute content out. + +### [Page Visibility](https://docs.sentry.io/contributing/platforms/\#page-visibility) + +Sometimes a page may not make sense within the context of a given guide. To control this, you can use the `supported` and `notSupported` frontmatter on common pages in platforms. + +Page visibility works similar to the supported/notSupported attributes in other platform components (such as `PlatformSection`). + +For example, if you wanted to make hide the content for a platform by default, but enable it for a guide, you can do that like so: + +Markdown + +`` + +```code-highlight markdown +--- +supported: + - native.wasm +notSupported: + - native +--- + +``` + +If the page you're conditionally hiding has subpages, you'll need to add the `supported`/ `notSupported` annotations to the subpages as well. + +## [Platform-Specific Components](https://docs.sentry.io/contributing/platforms/\#platform-specific-components) + +There are a number of components that aid the development of platform specific pages, as well as behave differently when a platform is active. For more information, see [components](https://docs.sentry.io/contributing/pages/components/). + +## [Delineation](https://docs.sentry.io/contributing/platforms/\#delineation) + +We differentiate platforms by language and developer interaction. A top-level SDK is considered a platform. A platform may have guides for frameworks that it supports, and these guides often inherit much of their content from their parent platform. + +In general, use this decision tree: + +- Is it a new programming language? -> new platform +- Does it require a separate SDK or way of sending data to Sentry? -> new platform +- Does it count as a "platform" -> new platform +- Otherwise -> add it as a Guide to an existing platform + +### [Example](https://docs.sentry.io/contributing/platforms/\#example) + +JavaScript is a top-level SDK because the frameworks that it supports share much of the same content. + +On the other hand, Android and Java have very little overlap. As a result, they are both top level platforms. + +[Previous\\ +\\ +Our Approach](https://docs.sentry.io/contributing/approach) + +[Next\\ +\\ +Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering/) + +# Inbound Filters + +## Learn about the different methods for filtering data in your project. + +Sentry provides several methods to filter data in your project. Using sentry.io to filter events is a simple method since you don't have to [configure and deploy your SDK to filter projects](https://docs.sentry.io/platform-redirect/?next=/configuration/filtering/). + +## [Inbound Data Filters](https://docs.sentry.io/concepts/data-management/filtering/\#inbound-data-filters) + +Inbound data filters allow you to determine which errors, if any, Sentry should ignore. Explore these by navigating to **\[Project\] > Project Settings > Inbound Filters.** + +These filters are exclusively applied at ingest time and not later in processing. This, for instance, lets you discard an error by error message when the error is ingested through the JSON API. On the other hand, this filter doesn't apply to ingested minidumps. Filtered events do not consume quota, as discussed in [What Counts Toward My Quota](https://docs.sentry.io/pricing/quotas/#what-counts-toward-my-quota-an-overview). + +Inbound filters include: + +- Common browser extension errors +- Transactions coming from health checks and ping requests +- Events coming from legacy browsers +- Events coming from localhost +- Errors from known web crawlers +- React hydration errors +- ChunkLoadErrors +- Events from certain IP addresses +- Events with certain error messages +- Events from specific release versions of your code + +### [Legacy Browser Filters](https://docs.sentry.io/concepts/data-management/filtering/\#legacy-browser-filters) + +The legacy browser filters allow you to filter out certain legacy versions of browsers that are known to cause problems. + +Legacy browser filters were updated in Feb 2024 and will be periodically evaluated to include additional legacy versions. + +If you had a legacy browser filter on before the update, the old filter will appear in your settings as "Deprecated". Deprecated legacy browser filters still work. However, if you turn them off, you won’t be able to turn them on again and will need to use the new filters instead. + +### [Browser Extension Errors](https://docs.sentry.io/concepts/data-management/filtering/\#browser-extension-errors) + +Some browser extensions are known to cause errors. You can filter these out using the browser extension filter, which checks the error message and event source to see if it's a known error coming from a browser extension. To see the full list of errors filtered out by the browser extension filter, see the [source code in relay](https://github.com/getsentry/relay/blob/master/relay-filter/src/browser_extensions.rs#L9-L76). + +### [Web Crawler Errors](https://docs.sentry.io/concepts/data-management/filtering/\#web-crawler-errors) + +Due to their nature, web crawlers often encounter errors that normal users won't see. You can use the web crawler filter to filter out errors from web crawlers, determined by the event's user-agent, from the following sites: Baidu, Yahoo, Sogou, Facebook, Alexa, Slack, Google Indexing, Pingdom, Lytics, AWS Security Scanner, Hubspot, Bytedance, and other generic bots and spiders. Errors from Slack's Slackbot web crawler will not be filtered. + +### [IP Addresses](https://docs.sentry.io/concepts/data-management/filtering/\#ip-addresses) + +Filters events based on the **originating IP address of the client making the request**, not the user IP contained within the user data inside the request. This ensures that filtering decisions rely on the actual source of the request, as determined by network-level information, rather than data provided in the event payload. + +Sentry attempts to identify the request’s origin using the **forwarded IP address**. If no forwarded IP is available, it falls back to the **direct IP** of the client connecting to Sentry’s servers. + +The supported IP address formats are: + +- **IPv4 Addresses**: Standard dotted-decimal notation (e.g., 1.2.3.4, 122.33.230.14, 127.0.0.1). +- **IPv6 Addresses**: Standard colon-separated hexadecimal notation (e.g., aaaa:bbbb::cccc, a:b:c::1). +- **IPv4 Network Ranges (CIDR Notation)**: IPv4 address with a subnet mask (e.g., 122.33.230.0/30, 127.0.0.0/8). +- **IPv6 Network Ranges (CIDR Notation)**: IPv6 address with a subnet mask (e.g., a:b:c::0/126). + +### [Transactions Coming from Health Check](https://docs.sentry.io/concepts/data-management/filtering/\#transactions-coming-from-health-check) + +In essence, the health check filter serves the purpose of excluding transactions that are generated as a part of health check procedures. + +By applying this filter, you effectively bypass transactions that, while crucial for app stability assessment, hold limited value for you beyond their designated function. + +We consider a transaction to be a health check if its name matches one of the following glob patterns: + +- `*healthcheck*` +- `*heartbeat*` +- `*/health` +- `*/healthy` +- `*/healthz` +- `*/_health` +- `*/[_health]` +- `*/live` +- `*/livez` +- `*/ready` +- `*/readyz` +- `*/ping` +- `*/up` + +* * * + +##### Note + +Filters do not apply to [sessions](https://docs.sentry.io/product/releases/health/#session). Error messages from minidumps also do not yet apply. + +Once applied, you can track the filtered events (numbers and cause) using the graph provided at the top of the Inbound Data Filters view. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fbuiltin-inbound-filters-7W2K2Z5Q.png%231928x648&w=3840&q=75)](https://docs.sentry.io/mdx-images/builtin-inbound-filters-7W2K2Z5Q.png) + +## [How Custom Filtering Works](https://docs.sentry.io/concepts/data-management/filtering/\#how-custom-filtering-works) + +This feature is available only if your organization is on [a Trial, Business, or Enterprise plan](https://sentry.io/pricing/). + +Inbound data filters are not case-sensitive. + +### [Error Message](https://docs.sentry.io/concepts/data-management/filtering/\#error-message) + +To use inbound data filters for error messages, keep the following in mind: + +- You can provide multiple patterns, one per line. The filter applies if any of the patterns match. +- On error events, the filter matches the entire error description in the format `{exception.type}: {exception.value}`. We do not recommend matching the full error description including the colon, and suggest you match with wildcards. For example, to match any "ConnectionError", use the filter `*ConnectionError*`. The wildcard matcher can be used at the beginning or end of the string. +- On message events, the filter matches the fully formatted message. +- Transactions are never matched by this filter. + +To ensure you’re adding the correct message to the inbound filter setting, check the JSON for an event in the issue. The filter by error message setting matches the data found in the "title" field near the end of the file. + +### [Releases](https://docs.sentry.io/concepts/data-management/filtering/\#releases) + +To filter releases, keep the following in mind: + +- The filter matches the full release name provided during SDK initialization. If you provide the recommended package prefix, the release is in the format `package@version`, for example: `my-example@1.4.0-beta.1`. +- Globbing rules apply and there is no special casing for SemVer. This allows for matching prefixes, such as `my-example@1.*`. +- The filter never applies to events without a release. + +### [Glob Matching](https://docs.sentry.io/concepts/data-management/filtering/\#glob-matching) + +The error messages and releases filters use glob patterns. Globs are case insensitive and allow you to specify wildcards to match variable input. For example, `*panic*` matches any error that contains the words "panic", "PANIC" or "PaNiC". + +Some symbols, such as the `*` character, receive special meaning as meta characters. To match a literal asterisk, escape it with a backslash: `\*`. Inbound data filters use the following meta characters: + +- `?` matches any single character. +- `*` matches zero or more characters. +- `\` escapes the next character making it literal. If it precedes a non-meta character, the backslash is ignored. +- `[`, `]`, `{`, and `}` are reserved meta characters. +- `!` works for negation, but only within brackets, such as in `[!1-4]` to match any character that is not `[1-4]`. + +Generally, `bash`'s out-of-the-box behavior for globbing is close to what Sentry supports: + +Bash + +`` + +```bash code-highlight +touch 1.2.3 +touch 1.2.4 +echo 1.2.* +echo 1.2.[!3] + +``` + +[Previous\\ +\\ +Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding) + +[Next\\ +\\ +Size Limits](https://docs.sentry.io/concepts/data-management/size-limits) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/filtering/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Development Environment](https://docs.sentry.io/contributing/environment/) + +# Development Environment + +This setup assumes you have [Yarn](https://yarnpkg.com/), [Volta](https://volta.sh/) and [pre-commit](https://pre-commit.com/) installed. + +If you prefer not to use Volta, make sure you're using Node 20. + +First, open a terminal and clone the `sentry-docs` repo: + +Bash + +`` + +```bash code-highlight +# Clone the docs repo +git clone git@github.com:getsentry/sentry-docs.git + +``` + +Next, navigate into the cloned repo and run the following to install dependencies: + +Bash + +`` + +```bash code-highlight +# Install or update application dependencies +make + +``` + +Now, run the development webserver (depending on the docs you want to run): + +Bash + +`` + +```bash code-highlight +# Start dev server for user docs +yarn dev + +# Start dev server for developer docs +yarn dev:developer-docs + +``` + +You will now be able to access docs via [http://localhost:3000](http://localhost:3000/). + +## [Linting](https://docs.sentry.io/contributing/environment/\#linting) + +A few linters are available. Run `yarn lint` to apply them all. + +Some lints can be autofixed with eslint + +Bash + +`` + +```bash code-highlight +yarn lint:eslint:fix + +``` + +Additionally we use prettier to format our code and markdown. Run prettier if you get linting errors in CI: + +Bash + +`` + +```bash code-highlight +yarn lint:prettier:fix + +``` + +[Previous\\ +\\ +Contributing to Docs](https://docs.sentry.io/contributing) + +[Next\\ +\\ +Our Approach](https://docs.sentry.io/contributing/approach) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/environment.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) +- [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) + +# Trace View + +## Learn more about the Trace View page, where you can drill down into the details of a single trace, allowing you to debug slow services, identify related errors, and find other bottlenecks. + +The Trace View page is designed to be your one-stop-shop when debugging performance or errors. It gives you full context on what was happening when an error or performance issue occurred, all in one place. The waterfall Trace View allows you to see everything that may have occurred during a trace, including errors, performance issues, and any profiles that may have been collected. + +In addition, looking at the Trace View allows you to drill down into a single trace so you can visualize the high-level transactions and spans that took place within that trace. This makes debugging slow services, identifying related errors, and rooting out bottlenecks easier and faster, since you no longer have to navigate around multiple pages of the Sentry product. + +## [Product Walkthrough: Trace View Page](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#product-walkthrough-trace-view-page) + +Sentry's default visualization of a trace is a waterfall-like structure, where the entries (transactions and spans) in the list are organized chronologically and through ancestry (child spans will fall under their parents). This allows you to follow the order of operations and drill into sub-operations. + +On the left side is a list of operations, and on the right is their duration and any events, such as errors, which may have occurred in that timeframe. + +By default, the waterfall view shows a list of transactions. If you need more granular data and want to see spans as well, click "+" to the left of a transaction to expand the waterfall. The waterfall view helps surface any performance issues or profiles collected during a given timeframe. + +![Step 3](<Base64-Image-Removed>)![Expand transaction to view which span produced the error.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/9ee9049b-14ca-4c93-8829-e41a05b6fa2b.png) + +![](<Base64-Image-Removed>) + +### [Helpful Tips](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#helpful-tips) + +Because debugging often involves multiple people or teams, we've made it easy to draw attention to specific areas of the trace and share a link that shows what you've highlighted with your colleagues. To do this, click on the row you'd like to draw attention to and share the resulting URL. Your colleague will see exactly what you want them to. + +Whatever you highlight will also be saved if you navigate away from the page and will still be there when you use your browser's back and forward buttons. + +If you're doing a comparison and want an easy way to go back and forth between highlighted areas of interest in your trace, you can pin the tabs. When a tab is pinned, the view will be persistent throughout your session. + +Trace View — Tabbing + +Trace View — Tabbing + +![Pinning a tab will persist it.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/d2c464e2-9c6a-4212-8c9c-f84302a9ecac.png) + +![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/65d725cb-0e5f-4d04-960f-4c7118ddc307.png) + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +Sometimes, duration gaps between entries can be small, but critical to your debugging effort. That's why the Trace View enables you to zoom into certain areas of the trace, either by double clicking on row elements (which zooms into the row) or by using your scroll wheel. + +Trace View — Zooming + +Trace View — Zooming + +![Scroll to move around or scroll + meta key to zoom.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/37fcd5f8-b2b5-4483-b5e5-cd9904dca78d.png)![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/980a208b-3fda-41fd-a52b-09d051b3f7d5.png) + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +The Trace View has other features like search, which makes it easy to visualize matching spans that you can then iterate over using the up or down arrows. You can also tailor the layout to your preference. + +We're going to continue adding features that enable you to perform efficient investigation into whatever issues you might be facing. If you have feedback or requests, please share it with us. We'd love to hear how we can make your life easier and your users happier. + +## [Troubleshooting](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#troubleshooting) + +### [Orphan Traces and Broken Subtraces](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#orphan-traces-and-broken-subtraces) + +In a fully instrumented system, a span in one service will connect to a transaction in a subsequent service. For a variety of reasons, a transaction in a service may not arrive in Sentry. When Sentry encounters these types of transactions within a trace, the transactions are linked with a dashed line since they can no longer be directly connected to the root, creating an orphan trace. + +In addition, broken subtraces can occur when Sentry receives an error for a trace, but the corresponding transaction does not exist. Such errors are linked using dashed lines and clicking on the row takes you to the corresponding **Issue Details** page. + +Also, in these cases you can click "Open In Discover" to see all the events in the trace. + +Broken subtraces may be caused by: + +- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](https://docs.sentry.io/organization/dynamic-sampling/#deciding-on-your-sdk-sample-rate). +- [Ad blockers](https://docs.sentry.io/platforms/javascript/troubleshooting/#dealing-with-ad-blockers) may prevent transactions in browsers being sent, but HTTP requests to backend projects will still create child transactions +- [Rate-limiting](https://docs.sentry.io/product/accounts/quotas/#limiting-events) on a project may cause only some events to be sent to Sentry +- [Project permissions](https://docs.sentry.io/product/accounts/membership/#restricting-access) may mean you do not have access to transactions in another project +- [Differences in quota limits](https://docs.sentry.io/product/accounts/quotas/) between transactions and errors. When a quota limit is reached - for example, for transactions - an error is received, but corresponding transaction is not. +- Exceeding the span limit. Transactions are associated via the child spans of the parent transaction, but if the number of spans exceed the limit, the association cannot be made + +### [Multiple Roots](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#multiple-roots) + +Each trace ID should have only one root, a transaction without any parents. Automatic instrumentation should prevent multiple roots; however, if the trace ID of your transactions is being set using custom instrumentation, you may encounter multiple roots. + +[Previous\\ +\\ +Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) + +[Next\\ +\\ +Search](https://docs.sentry.io/concepts/search) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/trace-view.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Account Settings](https://docs.sentry.io/account/) + +# Account Settings + +## Learn about Sentry's user settings and auth tokens. + +[Next\\ +\\ +Account Preferences](https://docs.sentry.io/account/user-settings) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) +- [Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues/) + +# Merging Issues + +## Learn about merging similar issues that aren't automatically grouped. + +This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. + +Escalating issues currently does not work for merged/unmerged issues, but we're working on fixing this. + +If you have similar-looking issues that have not been grouped together automatically and you want to reduce noise, you can do so by merging them. + +In this example, before merge, there are two issues that are very similar, but have not been grouped together. One issue has 39 events in the past 24 hours, and the other has 76: [![Before merge.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fbefore-merge-V2WAWJEZ.png%231484x444&w=3840&q=75)](https://docs.sentry.io/mdx-images/before-merge-V2WAWJEZ.png) + +After the two issues are merged into one, the event count of 115 on that one issue reflects that they've been grouped together: [![After merge.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fafter-merge-OQJFIWHK.png%231484x389&w=3840&q=75)](https://docs.sentry.io/mdx-images/after-merge-OQJFIWHK.png) + +You can also do this from inside a single issue. Click the "Similar Issues" tab, select all of the issues that you want to merge, and click "Merge": [![Similar Issues](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsimilar-issues-EYK6NV5S.png%231484x617&w=3840&q=75)](https://docs.sentry.io/mdx-images/similar-issues-EYK6NV5S.png) + +If you'd like to unmerge issues, go to the **Issue Details** page and click the “Merged Issues” tab. You will see the fingerprints that have been merged into that issue. Select the appropriate checkbox(es) and click “Unmerge”. + +It's important to note that we don't infer any new grouping rules from how you merge issues. Future events will be added to the merged set of issues by the same criteria as they would've been added to the individual issues that are now in the merged set. + +If Sentry creates more issues than you can merge, or too few issues, you can try updating your [Fingerprinting Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) or [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/). + +[Previous\\ +\\ +Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) + +[Next\\ +\\ +Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/merging-issues/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) + +# Tutorial: Create a Sentry Authentication Token + +To use Sentry's APIs, you must have an authentication token. This tutorial walks you through creating an organizational auth token through an internal integration. Sentry recommends using organizational auth tokens whenever possible, as they aren't linked to specific user accounts. + +See our documentation on [authentication](https://docs.sentry.io/api/auth/) to learn more about the different types of authentication tokens available. + +## [Prerequisites](https://docs.sentry.io/api/guides/create-auth-token/\#prerequisites) + +- A Sentry account with an organization-level role of Manager or Admin. + +## [Create an Internal Integration](https://docs.sentry.io/api/guides/create-auth-token/\#create-an-internal-integration) + +[Internal integrations](https://docs.sentry.io/organization/integrations/integration-platform/internal-integration/) are used to create custom Sentry integrations for your organization. They can also be used to create and manage your organization auth tokens. + +1. Open [sentry.io](https://sentry.io/) + +2. Click "Settings" in the left menu to open the **Organization Settings** page. + +3. Click "Custom Integrations" in the left side panel to create a new internal integration and org-level auth token. + +4. Press the "Create New Integration" button. + +5. Make sure "Internal Integration" is selected in the modal and press "Next". + +6. Enter a name for your integration. + + +[![Sentry.io UX walkthrough of creating an internal integration.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcreate-internal-integration-IFN34264.gif%23800x533&w=1920&q=75)](https://docs.sentry.io/mdx-images/create-internal-integration-IFN34264.gif) + +## [Create a API Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/\#create-a-api-authentication-token) + +1. Under "Permissions" select the permissions required for the APIs you wish to call. + +Each API endpoint docs page lists the required permissions, in the "Scopes" section. For example, the [Create a New Project](https://docs.sentry.io/api/projects/create-a-new-project/) endpoint requires project:write permissions or higher. + +2. Click "Save Changes". + +3. Scroll down to the bottom of the page and copy the generated token under "Tokens". + + +[![Sentry.io UX walkthrough of creating a token and setting it's permissions.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fset-token-permissions-Q4IZFS2Y.gif%23800x533&w=1920&q=75)](https://docs.sentry.io/mdx-images/set-token-permissions-Q4IZFS2Y.gif) + +Keep your auth token around on your clipboard or in an environment variable to use in API calls. + +[Previous\\ +\\ +Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial) + +[Next\\ +\\ +Authentication](https://docs.sentry.io/api/auth) + +- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/) + +# Session Replay Properties + +## Learn more about searchable session replay properties. + +[Session Replay](https://docs.sentry.io/product/explore/session-replay/) provides a video-like reproduction of user interactions on a site or web app. All user interactions, including page visits, mouse movements, clicks, and scrolls, are captured, helping developers connect the dots between a known issue and how a user experienced it in the UI. + +You can search by session replay properties on the **Replay** page. + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the session replay search. + +### [`activity`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#activity) + +Replay activity is calculated based on the number of errors, the number of ui events, and the duration of the replay. It's represented as a number from `1` to `10`. + +- **Type:** number + +### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#browsername) + +Name of the users' web browser. For example, `Chrome`, `Firefox`, or `Safari` + +- **Type:** string + +### [`browser.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#browserversion) + +The version string of the browser. + +- **Type:** string + +### [`click.alt`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickalt) + +The `alt` of an element that was clicked. For example, `"a good dog"` would match the element `<img src="/lassie.jpeg" alt="a good dog" />` + +- **Type:** string + +### [`click.class`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickclass) + +The `class` of an element that was clicked. No leading `.` is necessary. For example, `btn-primary` would match the element `<a class="btn btn-primary">Save</a>` + +- **Type:** string + +### [`click.component_name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickcomponent_name) + +The name of the frontend component that was clicked. For example, `MyAwesomeComponent` would match the React component `<MyAwesomeComponent>`. + +Note: This property requires that your project have [React component name capturing configured](https://docs.sentry.io/platforms/javascript/guides/react/features/component-names/). + +- **Type:** string + +### [`click.id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickid) + +The `id` of an element that was clicked. No leading `#` is necessary. For example, `reset-password` would match the element `<a id="reset-password">Reset</a>` + +- **Type:** string + +### [`click.label`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicklabel) + +The `aria-label` of an element that was clicked. For example, `Expand` would match the element `<button aria-label="Expand"><img src="/icons/expand.png"/></button>` + +- **Type:** string + +### [`click.role`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickrole) + +The `role` of an element that was clicked. For example, `button` would match both `<button>Save</button>` and `<a role="button">Submit</a>` + +- **Type:** string + +### [`click.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickselector) + +An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. + +- **Type:** string + +### [`click.tag`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktag) + +The tag name of an element that was clicked. For example, `input` would match `<input name="username" />` + +- **Type:** string + +### [`click.testid`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktestid) + +The `data-testid` or `data-test-id` of an element that was clicked. For example, `user-name` would match the element `<a data-testid="user-name">User Name</a>` + +- **Type:** string + +### [`click.textContent`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktextcontent) + +The immediate `textContent` of an element that was clicked. For example, `Save` would match `<button>Save</button>` but wouldn't match `<button><h1>Save</h1></button>` + +- **Type:** string + +### [`click.title`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktitle) + +The `title` of an element that was clicked. For example, `Save this comment` would match the element `<a title="Save this comment" class="btn btn-primary">Save</a>` + +- **Type:** string + +### [`count_dead_clicks`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_dead_clicks) + +The number of [dead clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Dead%20Clicks%3A%20User%20clicks%20on%20a%20and%20button%20tags%20that%20do%20not%20result%20in%20any%20page%20activity%20after%207%20seconds) within a replay. + +- **Type:** number + +### [`count_errors`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_errors) + +The number of errors within a replay. + +- **Type:** number + +### [`count_rage_clicks`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_rage_clicks) + +The number of [rage clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Rage%20Clicks%3A%20Five%20or%20more%20clicks%20on%20a%20dead%20element%20(it%20exhibits%20no%20page%20activity%20after%207%20seconds.)%20Rage%20clicks%20are%20a%20subset%20of%20dead%20clicks) within a replay. + +- **Type:** number + +### [`count_segments`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_segments) + +The number of segments within a replay. More segments represent more activity over time. + +- **Type:** number + +### [`count_urls`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_urls) + +The number of URLs that the user visited during a replay recording. + +- **Type:** number + +### [`dead.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#deadselector) + +Similar to the `click.selector` search property, but only queries on [dead clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Dead%20Clicks%3A%20User%20clicks%20on%20a%20and%20button%20tags%20that%20do%20not%20result%20in%20any%20page%20activity%20after%207%20seconds). An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. + +- **Type:** string + +### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicebrand) + +Brand of the device + +- **Type:** string + +### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicefamily) + +Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. + +- **Type:** string + +### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicemodel_id) + +Internal hardware revision to identify the device exactly. + +- **Type:** n/a + +### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicename) + +Details of the device + +- **Type:** string + +### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#dist) + +Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. + +- **Type:** string + +### [`duration`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#duration) + +Duration of a replay in seconds. + +- **Type:** number + +### [`error_ids`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#error_ids) + +Error event IDs that have occurred within a replay. + +- **Type:** array + +### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#id) + +The event or replay id. In **Issues**, use only the ID value without the `id` key. + +- **Type:** UUID + +### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#level) + +Severity of the event (such as: fatal, error, warning). Always set to info for transactions. + +- **Type:** string + +### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#osname) + +The name of the operating system. For example, `Windows`, `Mac OS X`, or `Linux` + +- **Type:** string + +### [`os.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#osversion) + +The version number of the operating system. + +- **Type:** string + +### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#platform) + +Name of the platform. This is only a metrics property for [valid platforms](https://github.com/getsentry/relay/blob/9d0d2dc54233d46043a369e1dacf7db900953c14/relay-general/src/protocol/constants.rs#L1-L21), defaulting to `other`. + +- **Type:** string + +### [`project_id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#project_id) + +The id of the project. + +- **Type:** string + +### [`rage.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#rageselector) + +Similar to the `click.selector` search property, but only queries on [rage clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Rage%20Clicks%3A%20Five%20or%20more%20clicks%20on%20a%20dead%20element%20(it%20exhibits%20no%20page%20activity%20after%207%20seconds.)%20Rage%20clicks%20are%20a%20subset%20of%20dead%20clicks). An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. + +- **Type:** string + +### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#release) + +A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### [`replayType`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#replaytype) + +The reason a replay was triggered. For example, `session` when `replaysSessionSampleRate` takes effect, or `error` when `replaysOnErrorSampleRate` is sampled instead of `session`. + +- **Type:** string + +### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#sdkname) + +Name of the Sentry SDK that sent the event. + +- **Type:** string + +### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#sdkversion) + +Version of the Sentry SDK that sent the event. + +- **Type:** string + +### [`seen_by_me`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#seen_by_me) + +Whether you've seen this replay. Alias: `viewed_by_me` + +- **Type:** boolean + +### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#trace) + +A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. + +- **Type:** UUID + +### [`url`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#url) + +A specific URL that the user visited during the replay. You can also search for multiple URLs at once using `urls` and passing in an array of strings. + +- **Type:** string + +### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#useremail) + +An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. + +- **Type:** string + +### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userid) + +Application-specific internal identifier for the user. + +- **Type:** string + +### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userip) + +User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. + +- **Type:** string + +### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userusername) + +Username, which is typically a better label than the `user.id`. + +- **Type:** string + +[Previous\\ +\\ +Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans) + +[Next\\ +\\ +User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/session-replay.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) +- [Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) + +# Distributed Tracing + +## With distributed tracing, you can track software performance and measure throughput & latency, while seeing the impact of errors across multiple systems. + +Distributed tracing provides a connected view of your application from frontend to backend. It helps track software performance, measure [metrics](https://docs.sentry.io/product/insights/overview/metrics/) like throughput and latency, and display the impact of errors across multiple systems. This makes Sentry a more complete [performance monitoring](https://docs.sentry.io/product/insights/overview/) solution, aiding in diagnosing problems and measuring your application's overall health. + +[Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) in Sentry provides insights such as: + +- What occurred for a specific error event or issue +- The conditions causing bottlenecks or latency issues +- The endpoints or operations consuming the most time + +## [What Is Distributed Tracing?](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#what-is-distributed-tracing) + +A tracing tool focuses on what happened (and when), logging events during a program's execution across multiple systems. Traces often include timestamps, allowing durations to be calculated, but their purpose is broader, showing how interconnected systems interact and how problems in one can affect another. While tracing can be useful if instrumented in just the frontend or backend, it's most powerful when set up for your full stack (distributed tracing). + +It's important to note that tracing is not [profiling](https://docs.sentry.io/product/explore/profiling/). A profiler measures various aspects of an application's operation, resulting in a statistical summary. While both diagnose application problems, they differ in what they measure and how data is recorded. + +Learn more in this [Tracing: Frontend issues with backend solutions](https://sentry.io/resources/tracing-frontend-issues-with-backend-solutions/?original_referrer=https%3A%2F%2Fblog.sentry.io%2F) workshop. + +### [The Tracing Data Model](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#the-tracing-data-model) + +Ultimately, any data structure is defined by the kind of data it contains, and relationships between data structures are defined by how links between them are recorded. Traces, transactions, and spans are no different. + +#### [Traces](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#traces) + +Traces are defined as the collection of all transactions that share a `trace_id` value. + +#### [Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#transactions) + +Transactions share most properties (start and end time, tags, and so on) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. + +Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, or `Sentry.setExtra()`.) + +Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](https://docs.sentry.io/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. + +#### [Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#spans) + +Span data includes: + +- `parent_span_id`: ties the span to its parent span +- `op`: short string identifying the type or category of operation the span is measuring +- `start_timestamp`: when the span was opened +- `end_timestamp`: when the span was closed +- `description`: longer description of the span's operation +- `status`: short code indicating operation's status +- `tags`: key-value pairs holding additional data about the span +- `data`: arbitrarily-structured additional data about the span + +An example use of the `op` and `description` properties together is `op: db.query` and `description: SELECT * FROM users WHERE last_active < %s`. The `status` property indicates the success or failure of the span's operation, or a response code for HTTP requests. `Tags` and `data` attach further contextual information to the span, such as `function: middleware.auth.is_authenticated` for a function call or `request: {url: ..., headers: ... , body: ...}` for an HTTP request. To search span data see [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) + +### [What Can Tracing Help With?](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#what-can-tracing-help-with) + +Applications consist of interconnected components or services. For example, a modern web application may include: + +- Frontend (Single-Page Application) +- Backend (REST API) +- Task Queue +- Database Server +- Cron Job Scheduler + +Each component can be instrumented individually using a Sentry SDK to capture error data or crash reports, but this doesn't provide the full picture. Distributed tracing ties all the data together. + +Distributed tracing allows you to follow a request from the [frontend](https://docs.sentry.io/product/sentry-basics/integrate-frontend/) to the [backend](https://docs.sentry.io/product/sentry-basics/integrate-backend/) and back, pulling in data from any background tasks or notification jobs that request creates. This helps correlate Sentry error reports and gain insights into which services may negatively impact your application's performance. + +## [Traces, Transactions, and Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#traces-transactions-and-spans) + +A **trace** represents the record of the entire operation you want to measure or track, like page load or a user action. When a trace includes work in multiple services, it's called a **distributed trace**. + +Each trace consists of one or more tree-like structures called [**transactions**](https://docs.sentry.io/product/insights/overview/transaction-summary/), with nodes called **spans**. Each transaction represents a single instance of a service being called, and each span represents a single unit of work. Here's an example trace, broken down into transactions and spans: + +[![Diagram illustrating how a trace is composed of multiple transactions, and each transaction is composed of multiple spans.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-trace-LTDLDUUH.png%231800x1031&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-trace-LTDLDUUH.png) + +Top-level spans can be broken down into smaller spans, mirroring the way one function may call others. Every span may be the **parent span** to multiple **child spans**. One span in every transaction represents the transaction itself, with all other spans descending from that root span. Here's a zoomed-in view of one of the transactions from the diagram above: + +[![Diagram illustrating the parent-child relationship between spans within a single transaction.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-spans-55HVFBGN.png%231801x927&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-spans-55HVFBGN.png) + +### [Tracing Example: Investigating Slow Page Load](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#tracing-example-investigating-slow-page-load) + +Suppose your web application is slow to load. A lot has to happen for your app to get to a usable state: multiple requests to your backend, calls to your database or external APIs, and browser processing. Which part is slowing things down? + +In this simplified example, when a user loads the app in their browser, the following happens: + +- _Browser_ + - 1 request each for HTML, CSS, and JavaScript + - 1 rendering task, which sets off 2 requests for JSON data +- _Backend_ + - 3 requests to serve static files (HTML, CSS, JS) + - 2 requests for JSON data - 1 requiring a database call, 1 requiring an external API call and processing +- _Database Server_ + - 1 request requiring 2 queries (authentication and data retrieval) + +_Note:_ The external API is not listed as it's external and can't be seen inside. + +The entire page-loading process is represented by a single **trace**. That trace consists of the following **transactions**: + +- 1 browser transaction (for page load) +- 5 backend transactions (one for each request) +- 1 database server transaction (for the single DB request) + +Each transaction is broken down into **spans**: + +- _Browser Page-load Transaction_: 7 spans + - 1 root span for the entire page load + - 1 span each (3 total) for HTML, CSS, and JS requests + - 1 span for the rendering task, containing 2 child spans for each JSON request + +Some spans in the browser transaction correspond to backend transactions. When a span in one service gives rise to a transaction in another, the original span is a parent span to both the transaction and its root span. In the diagram below, squiggly lines represent this parent-child relationship. + +[![Diagram illustrating the trace-transaction-span relationship applied to the example.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-example-G467OIQ5.png%231800x1031&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-example-G467OIQ5.png) + +In our example, every transaction other than the initial browser page-load transaction is the child of a span in another service. In a fully-instrumented system, this pattern always holds true. The only parentless span is the root of the initial transaction; every other span has a parent. Parents and children live in the same service, except when the child span is the root of a child transaction, in which case the parent span lives in the calling service and the child transaction/child root span lives in the called service. + +A fully-instrumented system creates a trace which is a connected tree, with each transaction a subtree. The boundaries between subtrees/transactions are the boundaries between services. The diagram above shows one branch of our example's full trace tree. + +Now, back to our spans: + +- _Backend HTML/CSS/JS Request Transactions_: 1 span each + - 1 root span for the entire request (child of a browser span) +- _Backend Request with DB Call Transaction_: 2 spans + - 1 root span for the entire request (child of a browser span) + - 1 span for querying the database (parent of the database server transaction) +- _Backend Request with API Call Transaction_: 3 spans + - 1 root span for the entire request (child of a browser span) + - 1 span for the API request (not a parent span, as the API is external) + - 1 span for processing the API data +- _Database Server Request Transaction_: 3 spans + - 1 root span for the entire request (child of the backend span above) + - 1 span for the authentication query + - 1 span for the data retrieval query + +After instrumenting all services, you might discover that the auth query in your database server is causing the slowdown. Tracing can't tell you _why_ it's happening, but now you know where to look! + +### [Further Examples of Tracing, Transactions & Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#further-examples-of-tracing-transactions--spans) + +#### [Measuring a Specific User Action](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#measuring-a-specific-user-action) + +For an e-commerce application, you might measure the time between a user clicking "Submit Order" and the order confirmation appearing. This process is one trace, with transactions ( _T_) and spans ( _S_) for: + +- Browser's full process ( _T_ and root span _S_) + - XHR request to backend\* ( _S_) + - Rendering confirmation screen ( _S_) +- Backend's processing of the request ( _T_ and root span _S_) + - Function call to compute total ( _S_) + - DB call to store order\* ( _S_) + - API call to payment processor ( _S_) + - Queuing of email confirmation\* ( _S_) +- Database's work updating the customer's order history ( _T_ and root span _S_) + - Individual SQL queries ( _S_) +- Queued task of sending the email ( _T_ and root span _S_) + - Function call to populate email template ( _S_) + - API call to email-sending service ( _S_) + +\\* Starred spans are parents of later transactions (and their root spans). + +#### [Monitoring a Background Process](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#monitoring-a-background-process) + +For a backend periodically polling for data from an external service, processing it, caching it, and forwarding it to an internal service, each instance is a trace, with transactions ( _T_) and spans ( _S_) for: + +- Cron job completing the entire process ( _T_ and root span _S_) + - API call to external service ( _S_) + - Processing function ( _S_) + - Call to caching service\* ( _S_) + - API call to internal service\* ( _S_) +- Work done in your caching service ( _T_ and root span _S_) + - Checking cache for existing data ( _S_) + - Storing new data in cache ( _S_) +- Internal service's processing of the request ( _T_ and root span _S_) + - Handling the request ( _S_) + +\\* Starred spans are parents of later transactions (and their root spans). + +### [Important Information About Tracing, Spans & Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#important-information-about-tracing-spans--transactions) + +#### [Trace Duration](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#trace-duration) + +A trace begins when the earliest transaction starts, and ends when the last transaction ends. You can't "start" or "end" a trace, but you can initiate a transaction which will triggers a trace. Completing all transactions ends a trace. + +#### [Async Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#async-transactions) + +Child transactions may outlive the transactions containing their parent spans. For example, if a backend API call sets off a long-running task and then immediately returns a response, the backend transaction will finish long before the async task transaction does. Asynchronicity means that the order in which transactions are sent to Sentry won't depend on the order they were created. However, order of receipt for transactions in the same trace is correlated with order of completion. + +#### [Orphan Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#orphan-transactions) + +In a fully instrumented system, each trace should contain only one transaction and one span (the transaction's root) without a parent. However, you may not have tracing enabled in every service, or an instrumented service may fail to report a transaction. This can result in gaps in your trace hierarchy, with non-originating, parentless transactions called **orphan transactions**. + +#### [Nested Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#nested-spans) + +There's no set limit to how deep the nesting of spans can go, but practical limits exist: transaction payloads sent to Sentry have a maximum allowed size, and there's a balance between data granularity and usability. + +#### [Zero-duration Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#zero-duration-spans) + +A span can have equal start and end times which will be recorded as taking no time. This can occur if the span is being used as a marker, for example, in the browser's [performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark), or if the operation's duration is less than the measurement resolution (which will vary by service). + +#### [Clock Skew](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#clock-skew) + +Collecting transactions from multiple machines may result in **clock skew**, where timestamps in one transaction don't align with timestamps in another. To reduce this, use Network Time Protocol (NTP) or your cloud provider's clock synchronization services. + +#### [How Data is Sent](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#how-data-is-sent) + +Individual spans aren't sent to Sentry; the entire transaction is sent as one unit. No span data is recorded by Sentry's servers until the transaction is closed and dispatched. Transactions are still valid and sent even if they only contain their root span. + +## [Data Sampling](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#data-sampling) + +When you enable sampling, you choose a percentage of collected transactions to send to Sentry. For example, a sampling rate of `0.25` for an endpoint receiving 1000 requests per minute results in approximately 250 transactions being sent to Sentry each minute. Sampling helps manage the number of events sent to Sentry and balances performance and volume concerns with data accuracy. + +### [Consistency Within a Trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#consistency-within-a-trace) + +Sentry uses a "head-based" approach: a sampling decision is made in the originating service and passed to subsequent services. For example, if a browser makes requests to your backend, it includes the sampling decision in the headers. The backend collects transaction and span data if the decision is "yes" and passes the decision to subsequent services. This ensures either all transactions for a given trace are collected, or none are. + +Dynamic sampling ensures complete traces by retaining all transactions associated with a trace if the head transaction is preserved. However, transactions or other items may still be missing from a trace when rate limiting or quota enforcement drops them. + +## [Viewing Trace Data](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#viewing-trace-data) + +Use the [Trace Explorer](https://docs.sentry.io/product/explore/traces/) to search for traces containing spans that meet your specific query conditions. This helps you find distributed traces that give you a connected view of your application and can help you debug and optimize your code. + +Through [Performance](https://docs.sentry.io/product/insights/overview/) and [Discover](https://docs.sentry.io/product/explore/discover-queries/), you can also view trace data in the [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) page. + +[Previous\\ +\\ +Tracing](https://docs.sentry.io/concepts/key-terms/tracing) + +[Next\\ +\\ +Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/distributed-tracing.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) + +# Data Source Name (DSN) + +## A Data Source Name (DSN) tells Sentry where to send events so they’re associated with the correct project. Learn more about DSN structure and use here. + +Sentry automatically assigns you a Data Source Name (DSN) when you create a project to start monitoring events in your app. + +### [What the Data Source Name (DSN) Does](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#what-the-data-source-name-dsn-does) + +A DSN tells a Sentry SDK where to send events so the events are associated with the correct project. + +If this value is not provided, SDKs will try to read it from the `SENTRY_DSN` environment variable, where applicable. This fallback does not apply in cases like a web browser, where the concept of environment variables does not exist. + +If an SDK is not initialized or if it is initialized with an empty DSN, the SDK will not send any data over the network, such as captured exceptions. + +### [DSN Utilization](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#dsn-utilization) + +DSNs are safe to keep public because they only allow submission of new events and related event data; they do not allow read access to any information. + +While there is a risk of abusing a DSN, where any user can send events to your organization with any information they want, this is a rare occurrence. Sentry provides controls to [block IPs](https://docs.sentry.io/platform-redirect/?next=/configuration/options/) and similar concerns. You can also rotate (and revoke) DSNs by navigating to **\[Project\] > Settings > Client Keys (DSN)**. + +If your application is shipped to client devices, if possible, we recommend having a way to configure the DSN dynamically. In an ideal scenario, you can "ship" a new DSN to your application without the customer downloading the latest version. We recognize that this may not always be practical, but we cannot offer further advice as this scenario is implementation specific. + +### [Where to Find Your Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#where-to-find-your-data-source-name-dsn) + +If you're in the process of setting up a project, you can find your DSN in the installation or configuration code snippets provided in [sentry.io](https://sentry.io/) during setup: + +[![DSN in code snippet](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcreate-new-project-04-VZTPA47T.png%231400x766&w=3840&q=75)](https://docs.sentry.io/mdx-images/create-new-project-04-VZTPA47T.png) + +You can also find the DSN in your project settings by navigating to **\[Project\] > Settings > Client Keys (DSN)** in [sentry.io](https://sentry.io/). + +### [The Parts of the Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#the-parts-of-the-data-source-name-dsn) + +The DSN configures the protocol, public key, server address, and project identifier. It is composed of the following parts: + +`{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}` + +For example: + +JavaScript + +`` + +```javascript code-highlight +Sentry.init({ dsn: "https://public@sentry.example.com/1" }); + +``` + +Has the following settings: + +- URI = [https://sentry.example.com](https://sentry.example.com/) +- Public Key = public +- Project ID = 1 + +The secret part of the DSN is optional and effectively deprecated. While clients will still honor it, if supplied, future versions of Sentry will entirely ignore it. + +[Previous\\ +\\ +Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms) + +[Next\\ +\\ +Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/dsn-explainer.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) +- [Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana/) + +# Grafana + +## Learn about Sentry's Grafana integration, which alows you to query and visualize Sentry data within Grafana. + +If you make changes to your organization slug, you'll need to update your configuration for this integration. Learn more in our [troubleshooting guide](https://docs.sentry.io/organization/integrations/troubleshooting/). + +Visualize your Sentry [Issues](https://docs.sentry.io/product/issues/) and [Stats](https://docs.sentry.io/product/stats/) data in Grafana with the Sentry [data source plugin](https://grafana.com/grafana/plugins/grafana-sentry-datasource/). Once installed, you can combine Sentry data with that of other sources, like your infrastructure data through Prometheus or your business data from your data warehouse, in a single dashboard. + +[Previous\\ +\\ +Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs) + +[Next\\ +\\ +Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/grafana.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs/) + +# Product Documentation Structure + +The topics in this section describe how to create Sentry product documentation. + +[Previous\\ +\\ +SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) + +[Next\\ +\\ +How to Write - Index Pages](https://docs.sentry.io/contributing/approach/product-docs/write-index) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/product-docs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) +- [Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/) + +# Cloudflare Workers + +## Learn more about how you can use Sentry to monitor errors in your Cloudflare Workers applications. + +Cloudflare Workers allow you to deploy serverless applications instantly across the globe with exceptional performance, reliability, and scale. + +This integration is maintained and supported by the company that created it. For more details or questions, please contact Cloudflare through their support portal: [https://developers.cloudflare.com/support/contacting-cloudflare-support/](https://developers.cloudflare.com/support/contacting-cloudflare-support/) + +## [Install and Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/\#install-and-configure) + +Sentry owner, manager, or admin permissions are required to install this integration. + +1. Navigate to **Settings > Integrations > Cloudflare Workers** + +2. Follow the full [Cloudflare Workers installation instructions](https://developers.cloudflare.com/workers/observability/sentry-integration/). + + +[Previous\\ +\\ +AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) + +[Next\\ +\\ +Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/cloudflare-workers/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Environments](https://docs.sentry.io/concepts/key-terms/environments/) + +# Environments + +## Learn more about how environments can help you better filter issues, releases, and user feedback in the Issue Details page on sentry.io. + +`Environment` is a Sentry-supported tag that you can (and should) add to your SDK. Generally, the tag accepts any value, but it's intended to refer to your code deployments' naming convention, such as _development_, _testing_, _staging_, or _production_. + +Environments help you better filter issues, releases, and user feedback in the **Issue Details** page of [sentry.io](https://sentry.io/). On that page, you can view information about a specific environment, focusing on the most recent release. If you’re using a multi-staged release process, you can also select a different default environment and set conditions that match the `environment` attribute to restrict alerts to only specific release stages. + +Use projects to separate different services or applications, and environments to separate different environments or release stages within each. If you've selected one or more projects in the filters of Sentry's web UI, the environment selector shows only environments associated with events from the selected projects. + +[![All Envs dropdown](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-env-LUSK3KCI.png%232550x824&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-env-LUSK3KCI.png) + +Environments are unique to each organization. Environment settings, however, are defined per project since you can hide environments per project. + +## [Creating Environments](https://docs.sentry.io/concepts/key-terms/environments/\#creating-environments) + +Sentry automatically creates environments when it receives an event with the environment tag. Environments are case-sensitive. You can also create an environment when you first `init` your SDK, [as documented for each SDK](https://docs.sentry.io/platform-redirect/?next=/configuration/environments/). + +## [Environment Filter](https://docs.sentry.io/concepts/key-terms/environments/\#environment-filter) + +### [Issues](https://docs.sentry.io/concepts/key-terms/environments/\#issues) + +If an issue has events from multiple environments, the issue will appear when you select any of those environments. Sentry defines an issue as a grouping of similar events. If you tag one or more events within an issue with a specific environment, that issue will appear in your view when filtered by that environment. For example, if an issue is composed of one event tagged with `Production` and one event tagged with `Staging`, the issue will appear in your view when filtering by `Production`, as well as by `Staging`. + +Also, the environment filter affects all issue-related metrics, such as the count of users affected, times series graphs, and event count. + +### [Releases](https://docs.sentry.io/concepts/key-terms/environments/\#releases) + +A release by itself is not associated with an environment but can be deployed to different environments. When you select an environment on the releases page, it shows releases that were deployed to that environment. For example, a release deployed to the `QA` and `Prod` environment will appear in your view when filtering by `QA`, as well as `Prod`. All issue-related metrics within a given release will be affected by the environment filter. A deploy must have an environment. + +For more details about configuring releases and deploys, see the [full documentation on Releases](https://docs.sentry.io/product/releases/). + +## [Hidden Environments](https://docs.sentry.io/concepts/key-terms/environments/\#hidden-environments) + +Since you can't delete environments, Sentry has an option to hide it from the UI. Hiding environments can be useful when you're no longer sending events from an environment, or you've accidentally created an environment you no longer want. You can hide environments from your environments dropdown by navigating to **Project Settings > Environments**, and selecting "Hide", but events sent to that environment **will still count against your quota**. + +If a project is hidden, you won't see that environment in the environment selector, unless another project with events from the same environment is also selected (and doesn't have it hidden in its project settings). + +Follow along with the interactive demo below to see how to hide and unhide environments. + +Environments - Hide/show + +Environments - Hide/show + +![Click to manage the project's environments.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/86a983ea-b01e-4467-b279-8acb0b6380cb.png)![Click to hide this environment.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/8e47441a-fe6b-4a44-a917-e59603034d0a.png)![Open this project's settings.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/5a1e819b-d387-475c-be8f-84bba1b6f1e2.png) + +Open this project's settings. + +![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) + +[Previous\\ +\\ +Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates) + +[Next\\ +\\ +Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/environments/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [Release Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/) + +# Release Properties + +## Learn more about searchable release properties. + +In **Releases**, you can only search by the following properties: + +- [`release`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#release) +- [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasebuild) +- [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasepackage) +- [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasestage) +- [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releaseversion) + +However, these properties are also searchable in the other pages of [sentry.io](https://sentry.io/) listed above (under [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/#event-properties)). + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the release search. + +### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#release) + +A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasebuild) + +The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** number + +### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasepackage) + +The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasestage) + +The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). + +- **Type:** string + +### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releaseversion) + +A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +[Previous\\ +\\ +User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback) + +[Next\\ +\\ +Saved Searches](https://docs.sentry.io/concepts/search/saved-searches) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/releases.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Redirects](https://docs.sentry.io/contributing/pages/redirects/) + +# Redirects + +Redirects allow you to automatically redirect an incoming request path to a new destination path. When you move or rename a file, you should make sure to set up a redirect from the old path to the new path, so that the old URL still takes users to the right place. + +## [Add a New Redirect](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect) + +There are two ways to add redirects in the Sentry docs: + +- [Add a New Redirect in `middleware.ts` (Recommended)](https://docs.sentry.io/contributing/pages/redirects/#add-a-new-redirect-in-middlewarets-recommended) +- [Add a New Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/#example-redirect-in-redirectsjs) + +Both files make the distinction between SDK docs (ie. end user docs) and developer docs. + +Because Sentry has a limited number of `next.config.js` redirects, you should configure your redirects in `middleware.ts` whenever possible. You should only use `redirects.js` ie ( `next.config.js`) if you need to use regular expressions and wildcard path segments in your redirects. + +It's no longer recommended to use `vercel.json` for redirects due to its limitations (doesn't work on localhost, requires a static file ...) + +### [Add a New Redirect in `middleware.ts` (Recommended)](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect-in-middlewarets-recommended) + +Set up all simple one-to-one redirects in `src/middleware.ts`. + +To add a new redirect in [`src/middleware.ts`](https://github.com/getsentry/sentry-docs/blob/master/src/middleware.ts), add a new object to `REDIRECTS` with the following properties: + +- `from`: The incoming request path. +- `to`: The new destination path you want to route to. + +#### [Example Redirect in `middleware.ts`](https://docs.sentry.io/contributing/pages/redirects/\#example-redirect-in-middlewarets) + +The example below redirects `https://docs.sentry.io/performance/` to `https://docs.sentry.io/product/performance/`: + +TypeScript + +`middleware.ts` + +```code-highlight typescript +const REDIRECTS: { from: PathWithTrailingSlash; to: string }[] = [\ + {\ + from: "/performance/",\ + to: "/product/performance/",\ + },\ +]; + +``` + +### [Add a New Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect-in-redirectsjs) + +Sentry has a limited number of Vercel redirects, so you should only configure redirects in `vercel.json` if your redirects need to use regular expressions. Otherwise, use [`middleware.ts`](https://docs.sentry.io/contributing/pages/redirects/#add-a-new-redirect-in-middlewarets-recommended). + +To add a new redirect in `redirects.js` (which is consumed by `next.config.js`'s [`redirects`](https://nextjs.org/docs/app/api-reference/next-config-js/redirects)), add a new object to the corresponding redirects with the following properties: + +- `source`: The incoming request path pattern. +- `destination`: The new destination path you want to route to. + +#### [Example Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/\#example-redirect-in-redirectsjs) + +The example below redirects URLs like `https://docs.sentry.io/cli/:path*` to `https://docs.sentry.io/product/cli/:path*` with a [path pattern](https://nextjs.org/docs/app/api-reference/next-config-js/redirects#path-matching) or a [Regex](https://nextjs.org/docs/app/api-reference/next-config-js/redirects#regex-path-matching). + +For example, `https://docs.sentry.io/cli/installation/` would be redirected to `https://docs.sentry.io/product/cli/installation/`. + +JSON + +`redirects.js` + +```code-highlight json + "redirects": [\ + {\ + "source": "/cli/:path*",\ + "destination": "/product/cli/:path*",\ + },\ + ] + +``` + +[Previous\\ +\\ +Markdown Variables](https://docs.sentry.io/contributing/pages/variables) + +[Next\\ +\\ +Search](https://docs.sentry.io/contributing/pages/search) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/redirects.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Two-Factor Authentication (2FA)](https://docs.sentry.io/organization/authentication/two-factor-authentication/) + +# Two-Factor Authentication (2FA) + +## Learn about adding two-factor authentication (2FA) across your organization. + +For an added layer of security, you can require your organization members to sign in to Sentry with two-factor authentication (2FA). + +## [Preface](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#preface) + +Sentry owner permissions are required to enforce two-factor authentication across your organization. + +1. Before you can require organization members to use 2FA, you must [enable two-factor authentication](https://sentry.io/settings/account/security/) for your own user account. + +2. We recommend notifying your organization members, and asking them to setup 2FA for their accounts before requiring two-factor authentication. You can see which members are enrolled on your organization's members page. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-members-MDCYZAVC.png%232302x644&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-members-MDCYZAVC.png) + + +## [Setup Require 2FA](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#setup-require-2fa) + +When you require two-factor authentication, members who are not enrolled in 2FA will be removed from your organization. They will lose access to your organization's projects and notifications, and will be sent an email to setup 2FA. They can reinstate their access and settings within three months of their removal from your organization. + +1. Go to **Organization Settings** >\> General Settings. + +2. Under Security & Privacy, toggle the **Require Two-Factor Authentication** switch. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-switch-PEMDTERA.png%232268x510&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-switch-PEMDTERA.png) + +3. Click **Confirm**. + + +## [View Removed Members](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#view-removed-members) + +To view members who were removed from your organization for 2FA non-compliance, you can look at your organization's audit log. + +1. Go to **Organization Settings** >\> Audit Log. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-audit-log-I7U3UAPT.png%231151x314&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-audit-log-I7U3UAPT.png) + +2. You can filter for action **member.pending** to see removed organization members, and action **org.edit** to see when the require\_2fa organization setting was changed. + + +## [Require 2FA and SSO](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#require-2fa-and-sso) + +Require 2FA is currently not available with single sign-on (SSO), so you would need to require two-factor authentication with your identity provider. + +## [Steps to Rejoin an Organization](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#steps-to-rejoin-an-organization) + +To reinstate your access and previous settings, you need to setup 2FA within three months of being removed from your organization. + +If you were removed from an organization due to 2FA non-compliance, follow these steps to rejoin the organization and reinstate your access and settings: + +1. Look in your inbox for an email from Sentry titled **Mandatory: Enable Two-Factor Authentication**. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-email-LIDX2RQV.png%231452x716&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-email-LIDX2RQV.png) + +2. Click the **Enable Two-Factor Authentication** button. + +3. If you can't find the email, ask an organization Owner or Manager to go to the **Organization Settings** >\> Members page and resend your invite. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-resend-invite-5O5DOKPB.png%232300x508&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-resend-invite-5O5DOKPB.png) + +4. After clicking through the email, you will be prompted to **Setup Two-Factor Authentication** before rejoining the organization. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-rejoin-7FOGWUDE.png%231594x718&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-rejoin-7FOGWUDE.png) + +5. This will take you to your **Account Settings** >\> [Security](https://sentry.io/settings/account/security/) page where you need to setup at least one form of two-factor authentication. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-add-auth-6XIZZ7ZY.png%231804x1158&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-add-auth-6XIZZ7ZY.png) + +6. Once you've enrolled in 2FA, remember to save your recovery codes in a safe place and consider adding a backup phone number. + +7. Then use the left sidebar to navigate to your organization. + + +[Previous\\ +\\ +Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) + +[Next\\ +\\ +Organization and User Management](https://docs.sentry.io/organization/membership) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/two-factor-authentication/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) +- [AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) + +# AWS Lambda + +## Learn more about Sentry's AWS Lambda integration and how you can automatically instrument your Node or Python Lambda functions with Sentry without changing your code. + +This method of setting up Sentry in your Lambda functions only works if your Lambda functions are run in Node CommonJS ( `require` syntax) or in Python. For all other setups, check out these docs for [Node](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/) or [Python](https://docs.sentry.io/platforms/python/integrations/aws-lambda/) instead. + +Connect Sentry to your AWS account to automatically add Sentry error and performance monitoring to your Node/Python Lambda functions. + +## [Install](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#install) + +Sentry owner, manager, or admin permissions are required to install this integration. + +1. Navigate to **Settings > Integrations > AWS Lambda**. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdirectory-YJU2HMO4.png%23784x148&w=1920&q=75)](https://docs.sentry.io/mdx-images/directory-YJU2HMO4.png) + +2. Press **Add Installation** to open the installation modal. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fintegration_detail-N2MWP2PA.png%23766x358&w=1920&q=75)](https://docs.sentry.io/mdx-images/integration_detail-N2MWP2PA.png) + +3. Select the project for your Lambda integration. **Note:** This project cannot be changed after installation is complete. If you only have a single project, you'll skip this step. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-Z67O7VPA.png%23807x817&w=1920&q=75)](https://docs.sentry.io/mdx-images/project-Z67O7VPA.png) + +4. Click **Go To AWS**. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Faws_account_1-HPNEZBRF.png%23831x874&w=1920&q=75)](https://docs.sentry.io/mdx-images/aws_account_1-HPNEZBRF.png) + +5. Scroll to the bottom of the Create Stack page, check the box, then press **Create Stack** to create a CloudFormation stack in your current region. This stack allows Sentry to automatically instrument your Lambda functions. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcloudformation-create-stack-7BTDG2LP.png%23843x954&w=1920&q=75)](https://docs.sentry.io/mdx-images/cloudformation-create-stack-7BTDG2LP.png) + +6. Wait for the stack to be created. Once it's confirmed and the status changes to **Create Complete**, click **I've created the stack** in the Sentry popup. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcloudformation-stack-create-complete-EEVLPRGY.png%23816x429&w=1920&q=75)](https://docs.sentry.io/mdx-images/cloudformation-stack-create-complete-EEVLPRGY.png) + +7. Now copy your AWS Account ID, select the region you want to use, and press **Next**. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Faws_account_2-NJCMJDLP.png%23772x806&w=1920&q=75)](https://docs.sentry.io/mdx-images/aws_account_2-NJCMJDLP.png) + + +You need to create the CloudFormation stack only once per account, even when installing the integration in multiple regions. If you are setting up the integration in a second region, copy the externalId from the existing CloudFormation stack on the "Parameters" tab into the form shown above. + +8. Select the Lambda functions to automatically add the Sentry layer and necessary environment variables when you **Finish Setup**. **Note:** You can enable or disable Sentry on Lambda functions after installation. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fselect_lambdas-X5V2NHJW.png%23817x976&w=1920&q=75)](https://docs.sentry.io/mdx-images/select_lambdas-X5V2NHJW.png) + + +Wait a few minutes as the Lambda functions are enabled. If any functions failed to instrument, follow the suggestions in Troubleshooting. + +### [Troubleshooting](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#troubleshooting) + +If you need help solving issues with your Sentry AWS Lamba integration, you can read the edge cases documented here. If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. + +- #### [Error `SentryRole already exists`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-sentryrole-already-exists) + + +The stack already exists in your account; you can proceed to the next step and add your AWS account information. + +- #### [Error `Invalid existing layer`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-invalid-existing-layer) + + +Your Lambda function has a layer that no longer exists. Please remove the problematic layer, then enable Sentry on the Lambda in the configuration view for the integration. + +- #### [Error `Please validate the CloudFormation stack was created successfully`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-please-validate-the-cloudformation-stack-was-created-successfully) + + +Sentry is unable to access your AWS account through your CloudFormation stack. This means either the stack has not been created or the external ID used doesn't match the one in your installation. You can go to the Parameters tab of the CloudFormation stack to copy the value of the external ID and paste it into the form field. + +- #### [Error `Invalid role associated with the lambda function`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-invalid-role-associated-with-the-lambda-function) + + +The role associated with your Lambda function no longer exists. Please add a new role to your Lambda function, then enable Sentry on the Lambda in the configuration view for the integration. + + +## [Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#configure) + +The integration configuration view in Sentry allows you to do the following with your Lambda functions: + +- Enable Sentry +- Disable Sentry +- Update the Sentry Lambda Layer to the latest version + +In the table view, you will also see the version of the Lambda layer below the name. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-manage-functions-YDXF7XDR.png%23885x296&w=1920&q=75)](https://docs.sentry.io/mdx-images/sentry-manage-functions-YDXF7XDR.png) + +## [Verify](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#verify) + +Run your AWS Lambda function. Performance data will be sent to Sentry and will show up on the **Performance** page in Sentry. If your function raises an error it will show up on the **Issues** page in Sentry. + +## [Remove Installation](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#remove-installation) + +Note that when the integration is uninstalled, your Lambda functions will still be instrumented with Sentry and you will continue to receive errors. If you want to disable Sentry for all your Lambda functions, you should disable Sentry for each function before uninstalling. Note, you can also uninstall and then reinstall if you would like to change the Sentry project for your Lambdas. + +Learn more about [how this integration works](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/). + +## [Notes on Specific Frameworks](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#notes-on-specific-frameworks) + +### [Serverless Framework](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#serverless-framework) + +If you're using [Serverless framework](https://www.serverless.com/), note that this integration will configure your existing Lambda functions correctly to use the SDK layer and set the appropriate environment variables. Learn more about it [here](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/). + +You can confirm that the output works by inputting `aws lambda get-function-configuration --function-name <yourFunctionName>`. However, when you perform a subsequent `sls deploy` the environment variables aren't maintained even though it looks like the reference to the layer is retained. + +You can set the layer definition and environment variables in `serverless.yml` as a workaround, but you'll have to do two things manually: maintain the latest layer version and add the reference to the SDK layer for every function you want "Sentrified". + +**Serverless Framework Using Node:** + +YAML + +`serverless.yml` + +```yaml code-highlight +# other configuration + +provider: + # more configuration + region: <AWS_REGION> + environment: + SENTRY_TRACES_SAMPLE_RATE: "1.0" + SENTRY_DSN: "<SENTRY_DSN>" + NODE_OPTIONS: "-r @sentry/aws-serverless/dist/awslambda-auto" + +custom: + layers: + - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryNodeServerlessSDK:26 +# - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryNodeServerlessSDK:latest + +functions: + <yourFunctionName>: + handler: <yourLambdaHandlerFunctionPath> + layers: ${self:custom.layers} + +``` + +**Serverless Framework Using Python:** + +YAML + +`serverless.yml` + +```yaml code-highlight +# other configuration + +provider: + # more configuration + region: <AWS_REGION> + environment: + SENTRY_TRACES_SAMPLE_RATE: "1.0" + SENTRY_DSN: "<SENTRY_DSN>" + +custom: + layers: + - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryPythonServerlessSDK:6 +# - arn:aws:lambda:${self:provider.region:943013980633:layer:SentryPythonServerlessSDK:latest + +functions: + <yourFunctionName>: + handler: sentry_sdk.integrations.init_serverless_sdk.sentry_lambda_handler + environment: + SENTRY_INITIAL_HANDLER: "<yourLambdaHandlerFunctionPath>" + layers: ${self:custom.layers} + +``` + +Currently, there's no way of using the [latest layer plugin](https://www.npmjs.com/package/serverless-latest-layer-version) since the `lambda:ListLayerVersions on resource: arn:aws:lambda:eu-west-1:943013980633:layer:SentryNodeServerlessSDK` hasn't been given the necessary permissions. + +### [SST](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#sst) + +If you use Node functions in [SST](https://serverless-stack.com/) and you want to use this integration, you'll need to: + +1. Import the [Lambda layer](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/layer/) using the [`LayerVersion`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-lambda.LayerVersion.html) construct and set it by calling [`addDefaultFunctionLayers`](https://docs.serverless-stack.com/constructs/Stack#adddefaultfunctionlayers). +2. Then set the `NODE_OPTIONS`, `SENTRY_DSN`, and `SENTRY_TRACES_SAMPLE_RATE` environment variables with the [`addDefaultFunctionEnv`](https://docs.serverless-stack.com/constructs/Stack#adddefaultfunctionenv) method. + +Read [how this integration works](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/) and [the SST docs](https://docs.serverless-stack.com/monitoring-your-app-in-prod#sentry) for more information. + +[Previous\\ +\\ +Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring) + +[Next\\ +\\ +Lambda Layer Modifications](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/aws-lambda/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/) + +# User Feedback Properties + +## Learn more about searchable user feedback properties. + +[User Feedback](https://docs.sentry.io/product/user-feedback/) allows your users to create bug reports so they can let you know about sneaky issues right away. Every report will automatically include related replays, tags, and errors, making fixing the issue dead simple. + +You can search by user feedback properties on the **User Feedback** page. + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the user feedback search. + +### [`assigned`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#assigned) + +Returns user feedback submissions assigned to the defined user(s) or team(s). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee, `my_teams` or `#team-name` for teams you belong to. + +- **Type:** team or org user + +### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#browsername) + +Name of the browser. + +- **Type:** string + +### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicebrand) + +Brand of the device. + +- **Type:** string + +### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicefamily) + +Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. + +- **Type:** string + +### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicemodel_id) + +Internal hardware revision to identify the device exactly. + +- **Type:** n/a + +### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicename) + +Name of the device. + +- **Type:** string + +### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#dist) + +Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. + +- **Type:** string + +### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#environment) + +The environment that the event was first seen in. + +- **Type:** string + +### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#id) + +The feedback ID. + +- **Type:** UUID + +### [`is`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#is) + +The properties of a user feedback submission. Values can be: `unresolved`, `resolved`, `assigned`, `unassigned`, `linked`, or `unlinked`. The `linked` and `unlinked` values return user feedback submissions based on whether they are linked to an external issue tracker or not. + +- **Type:** status + +### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#level) + +The severity of the user feedback submissions. If the feedback came in through the crash-report modal then the level is tied to the error experienced by the end-user. For feedback from the user feedback widget, the level is `info`. + +- **Type:** string + +### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#osname) + +The name of the operating system. + +- **Type:** string + +### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#sdkname) + +Name of the Sentry SDK that sent the event. + +- **Type:** string + +### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#sdkversion) + +Version of the Sentry SDK that sent the event. + +- **Type:** string + +### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#timestamp) + +The finish timestamp of the transaction. Returns events with matching datetime. + +- **Type:** datetime + +### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#transaction) + +The error or transaction name identifier. + +- **Type:** string + +### [`url`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#url) + +The URL of the page that the feedback is triggered on. + +- **Type:** string + +### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#useremail) + +The user's email address exists only if Sentry received it from the `Sentry.setUser` SDK option as a tag. This property does not apply to emails entered inside the user feedback widget, which are not searchable. + +- **Type:** string + +### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userid) + +Application-specific internal identifier for the user. + +- **Type:** string + +### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userip) + +User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. + +- **Type:** string + +### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userusername) + +Username, which is typically a better label than the `user.id`. + +- **Type:** string + +[Previous\\ +\\ +Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay) + +[Next\\ +\\ +Release Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/user-feedback.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Configuration and Authentication](https://docs.sentry.io/cli/configuration/) + +# Configuration and Authentication + +## Learn about the functionality of Sentry's command line interface and how you can install, configure, authenticate, set up release management, debug information files, and send events. + +For most functionality you need to authenticate with Sentry. Setting this up can be done either automatically, using `sentry-cli`, or manually via [Organization Auth Tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/). + +## [To use the automatic option:](https://docs.sentry.io/cli/configuration/\#to-use-the-automatic-option) + +Bash + +`` + +```bash code-highlight +sentry-cli login + +``` + +This will give you the option to visit your auth token user settings, where you can create a new auth token, or simply copy an existing one. When you return to the CLI, you'll paste in your token and it will get added to `~/.sentryclirc` automatically. + +By default, `sentry-cli` will connect to sentry.io, but for self-hosted you can also sign in elsewhere: + +Bash + +`` + +```bash code-highlight +sentry-cli --url https://myserver.invalid/ login + +``` + +## [To Authenticate Manually:](https://docs.sentry.io/cli/configuration/\#to-authenticate-manually) + +You can manually create an [Organization Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) and pass it to sentry-cli. + +You can also sign in to your Sentry account (if you're not already) and create an Auth Token directly from this page. + +Some CLI functionality, such as [Crons Monitoring](https://docs.sentry.io/product/crons/getting-started/cli/), is dependent on DSN authentication. + +You can create an Auth Token from this page in one of the following three ways: + +- add it to `~/.sentryclirc`: + + + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). + +Ini + +`` + +```code-highlight ini +[auth] +token=sntrys_YOUR_TOKEN_HERE + +``` + +- export it as an environment variable: + + + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). + +Bash + +`` + +```bash code-highlight +export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE + +``` + +- pass it as a parameter when you invoke `sentry-cli`: + + + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). + +Bash + +`` + +```bash code-highlight +$ sentry-cli login --auth-token sntrys_YOUR_TOKEN_HERE + +``` + + +## [Configuration File](https://docs.sentry.io/cli/configuration/\#configuration-file) + +The `sentry-cli` tool can be configured with a config file named `.sentryclirc` as well as environment variables and `.env` files. The config file is looked for upwards from the current path and defaults from `~/.sentryclirc` are always loaded. You can also override these settings from command line parameters. + +The config file uses standard INI syntax. + +By default `sentry-cli` will connect to sentry.io. For on-prem you can export the `SENTRY_URL` environment variable and point it to your installation: + +Bash + +`` + +```bash code-highlight +export SENTRY_URL=https://mysentry.invalid/ + +``` + +Alternatively you can add it to your `~/.sentryclirc` config. This is also what the `login` command does: + +Ini + +`` + +```code-highlight ini +[defaults] +url = https://mysentry.invalid/ + +``` + +## [Configuration Values](https://docs.sentry.io/cli/configuration/\#configuration-values) + +The following settings are available (first is the environment variable, the value in the parentheses is the config key in the config file): + +`SENTRY_AUTH_TOKEN` ( _auth.token_): + +The authentication token to use for all communication with Sentry. + +`SENTRY_API_KEY` ( _auth.api\_key_): + +The legacy API key for authentication if you have one. + +`SENTRY_DSN` ( _auth.dsn_): + +The DSN to use to connect to Sentry. + +`SENTRY_URL` ( _defaults.url_): + +The URL to use to connect to Sentry. This defaults to `https://sentry.io/`. + +`SENTRY_ORG` ( _defaults.org_): + +The ID or slug of the organization to use for a command. + +`SENTRY_PROJECT` ( _defaults.project_): + +The ID or slug of the project to use for a command. + +`SENTRY_VCS_REMOTE` ( _defaults.vcs\_remote_): + +The name of the _remote_ in the versioning control system. This defaults to `origin`. + +`SENTRY_PIPELINE` ( _defaults.pipeline_): + +The name of the environment to be appended to `User-Agent` header. + +`CUSTOM_HEADER` ( _defaults.custom\_header_): + +The header that will be added to every outgoing request in `key:value` format. + +`SENTRY_ALLOW_FAILURE` + +Note: This option will ignore the CLI's failure when uploading symbols. **BE AWARE** this will unblock your CI in case Sentry has issues, but you won't have unminified/unsymbolicated crashes in production. When using this flag, you should download your sourcemaps/debug files from CI, to re-run the upload symbols command at a later point once Sentry is available. + +( _http.keepalive_): + +This ini only setting is used to control the behavior of the SDK with regards to HTTP keepalives. The default is _true_ but it can be set to _false_ to disable keepalive support. + +`http_proxy` ( _http.proxy\_url_): + +The URL that should be used for the HTTP proxy. The standard `http_proxy` environment variable is also honored. Note that it is lowercase. + +( _http.proxy\_username_): + +This ini only setting sets the proxy username in case proxy authentication is required. + +( _http.proxy\_password_): + +This ini only setting sets the proxy password in case proxy authentication is required. + +( _http.verify\_ssl_): + +This can be used to disable SSL verification when set to false. You should never do that unless you are working with a known self signed server locally. + +( _http.check\_ssl\_revoke_): + +If this is set to false then SSL revocation checks are disabled on Windows. This can be useful when working with a corporate SSL MITM proxy that does not properly implement revocation checks. Do not use this unless absolutely necessary. + +`SENTRY_HTTP_MAX_RETRIES` ( _http.max\_retries_): + +Sets the maximum number of retry attempts for upload operations (e.g., uploads of release files and debug symbols). The default is `5`. + +( _ui.show\_notifications_): + +If this is set to false some operating system notifications are disabled. This currently primarily affects xcode builds which will not show notifications for background builds. + +`SENTRY_LOG_LEVEL` ( _log.level_): + +Configures the log level for the SDK. The default is `warn`. If you want to see what the library is doing you can set it to `info` which will spit out more information which might help to debug some issues with permissions. Possible values are `trace`, `debug`, `info`, `warn`, and `error`. + +( _dif.max\_upload\_size_): + +Sets the maximum upload size in bytes (before compression) of debug symbols into one batch. The default is 35MB or 100MB (depending on the version of sentry-cli) which is suitable for sentry.io but if you are using a different Sentry server you might want to change this limit if necessary. (Prior to version 1.72.0, this option was called `dsym.max_upload_size`.) + +( _dif.max\_item\_size_): + +Sets the maximum file size of a single file inside DIF bundle. The default is 1MB. + +`SENTRY_DISABLE_UPDATE_CHECK` ( _update.disable\_check_): + +If set to `true`, then the automatic update check in sentry-cli is disabled. The update check is also not enabled for npm based installations of sentry-cli at the moment. + +`SENTRY_NO_PROGRESS_BAR`: + +If set to `1`, then `sentry-cli` will not display progress bars for any operations. + +`SENTRY_LOAD_DOTENV`: + +Set to `0` to prevent sentry-cli from loading an `.env` file. + +`SENTRY_DOTENV_PATH`: + +Specify a path to `.env` file to be loaded during setup. This was introduced in version 1.70. + +`DEVICE_FAMILY` ( _device.family_): + +Device family value reported to Sentry. + +`DEVICE_MODEL` ( _device.model_): + +Device model value reported to Sentry. + +## [Validating The Config](https://docs.sentry.io/cli/configuration/\#validating-the-config) + +To make sure everything works you can run `sentry-cli info` and it should print out some basic information about the Sentry installation you connect to as well as some authentication information. + +## [Working with Projects](https://docs.sentry.io/cli/configuration/\#working-with-projects) + +Many commands require you to specify the organization and project to work with. There are multiple ways in which you can specify this. + +### [Config Defaults](https://docs.sentry.io/cli/configuration/\#config-defaults) + +If you are always working with the same projects you can set it in the `.sentryclirc` file: + +Ini + +`` + +```code-highlight ini +[defaults] +project=my-project +org=my-org + +``` + +### [Environment Variables](https://docs.sentry.io/cli/configuration/\#environment-variables) + +You can also set these defaults in environment variables. There are two environment variables that control this ( `SENTRY_ORG` and `SENTRY_PROJECT`) which you can export: + +Bash + +`` + +```bash code-highlight +export SENTRY_ORG=my-org +export SENTRY_PROJECT=my-project + +``` + +### [Properties Files](https://docs.sentry.io/cli/configuration/\#properties-files) + +Additionally `sentry-cli` supports loading configuration values from `.properties` files (common in the Java environment). You can instruct `sentry-cli` to load config files from there by exporting the path to a properties file in the `SENTRY_PROPERTIES` environment variable. This is commonly done automatically for some of our client integrations like Java and React Native. + +Inside the properties files you just use the dotted notation to set values. Example: + +Ini + +`` + +```code-highlight ini +defaults.url=https://mysentry.invalid/ + +``` + +To then instruct `sentry-cli` to use that file use this: + +Bash + +`` + +```bash code-highlight +export SENTRY_PROPERTIES=/path/to/sentry.properties +sentry-cli ... + +``` + +### [Explicit Options](https://docs.sentry.io/cli/configuration/\#explicit-options) + +Lastly you can also provide these values explicitly to the command you are executing. The parameters are always called `--org` or `-o` for the organization and `--project` or `-p` for the project. + +Note that they do not always go to the same command. For instance if you are managing releases (which are shared across the organization) you usually supply the organization to the `releases` command but the projects to the subcommand on it: + +Bash + +`` + +```bash code-highlight +sentry-cli releases -o my-org new -p my-project 1.0 + +``` + +For more information use the `help` command which will display documentation for all parameters. + +[Previous\\ +\\ +Installation](https://docs.sentry.io/cli/installation) + +[Next\\ +\\ +Release Management](https://docs.sentry.io/cli/releases) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/configuration.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) +- [Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons/) + +# Platform Icons + +To have consistent icons for all supported platforms across all of Sentry (the product, the docs, landing pages, etc.) we created a repo for managing those icons, called [platformicons](https://github.com/getsentry/platformicons). + +If a new platform is added, follow these steps to add a new icon that can be used in the docs: + +1. **Add the new icon to `platformicons`:** + +Create a [new issue in the platformicons repository](https://github.com/getsentry/platformicons/issues) that specifies how the icon should be named and includes a link to the platform's website. Also, make sure to specify whether it is a top-level icon (like `python`) or a subitem that is only available in one specific platform (like `python.celery`). + +You can also create a PR in the `platformicons` repository where you add two versions of the icon. See the [README](https://github.com/getsentry/platformicons) for more info on formatting.\`\`\` + +2. **Release a new version of `platformicons` to NPM.** + +If you are a Sentry employee, follow the [README.md](https://github.com/getsentry/platformicons) on how to do a release. + +If you are not a Sentry employee, ask on our [Discord server](https://discord.com/invite/Ww9hbqr) so someone can review your contribution and trigger the release. + +3. **Update the `platformicons` version used in the docs repository.** + +Update the version of your newly released `platformicons` in `package.json` and run `yarn install` to also have the new version in `yarn.lock`. + +4. **Make it available as a component in the docs repository.** + +Update [platformIcon.tsx](https://github.com/getsentry/sentry-docs/blob/master/src/components/platformIcon.tsx) to include your new icon. Make sure to: + + - Add two imports (one for each version of the icon). + - Add the icons to `formatToSVG`. + - Add a mapping for the platform and icon to `PLATFORM_TO_ICON`. + +Now the new icon is available in the docs and will be used wherever icons are rendered! + +[Previous\\ +\\ +Platforms & Guides](https://docs.sentry.io/contributing/platforms) + +[Next\\ +\\ +Versioning](https://docs.sentry.io/contributing/platforms/versioning) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/platform-icons/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)Edit this banner on \`/src/components/banner/index.tsx\` [CTA](https://docs.sentry.io/contributing/pages/banners/) + +× + +- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Banners](https://docs.sentry.io/contributing/pages/banners/) + +# Banners + +You can add arbitrary banners to the top of a page by adding adding an entry to the `BANNERS` array on the `banner/index.tsx` file. The `BANNERS` array is an array of objects with the following properties: + +TypeScript + +`banner/index.tsx` + +```typescript code-highlight +type BannerType = { + /** This is an array of strings or RegExps to feed into new RegExp() */ + appearsOn: (string | RegExp)[]; + /** The label for the call to action button */ + linkText: string; + /** The destination url of the call to action button */ + linkURL: string; + /** The main text of the banner */ + text: string; + /** Optional ISO Date string that will hide the banner after this date without the need for a rebuild */ + expiresOn?: string; +}; + +``` + +You can add as many banners as you like. If you need to disable all banners, simply delete them from the array. + +Each banner is evaluated in order, and the first one that matches will be shown. + +Examples: + +TypeScript + +`banner/index.tsx` + +```typescript code-highlight +// ... +// appearsOn = []; // This is disabled +// appearsOn = ['^/$']; // This is enabled on the home page +// appearsOn = ['^/welcome/']; // This is enabled on the "/welcome" page +// ... + +const BANNERS = [\ + // This one will take precedence over the last banner in the array\ + // (which matches all /platforms pages), because it matches first.\ + {\ + appearsOn: ["^/platforms/javascript/guides/astro/"],\ + text: "This banner appears on the Astro guide",\ + linkURL: "https://sentry.io/thought-leadership",\ + linkText: "Get webinarly",\ + },\ +\ + // This one will match the /welcome page and all /for pages\ + {\ + appearsOn: ["^/$", "^/platforms/"],\ + text: "This banner appears on the home page and all /platforms pages",\ + linkURL: "https://sentry.io/thought-leadership",\ + linkText: "Get webinarly",\ + },\ +]; + +``` + +Optionally, you can add an `expiresOn` property to a banner to hide it after a certain date without requiring a rebuild or manual removeal. the ISO Date string should be in the format `YYYY-MM-DDTHH:MM:SSZ` to be parsed correctly and account for timezones. + +TypeScript + +`banner/index.tsx` + +```typescript code-highlight +const BANNERS = [\ + {\ + appearsOn: ["^/$"],\ + text: "This home page banner will disappear after 2024-12-06",\ + linkURL: "https://sentry.io/party",\ + linkText: "RSVP",\ + expiresOn: "2024-12-06T00:00:00Z",\ + },\ +]; + +``` + +[Previous\\ +\\ +Search](https://docs.sentry.io/contributing/pages/search) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/banners.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) +- [Truto](https://docs.sentry.io/organization/integrations/compliance/truto/) + +# Truto + +## Learn about Sentry's Truto integration. + +This integration is maintained and supported by the company that created it. For more details, or questions, feel free to contact [support@truto.one](mailto:support@truto.one). + +## [Install and Configure](https://docs.sentry.io/organization/integrations/compliance/truto/\#install-and-configure) + +Sentry Owner, Manager, or Admin permissions are required to install this integration. + +1. Navigate to **Settings > Integrations > Truto** + +2. Follow the full [Truto installation instructions](https://truto.one/docs/integration-guides/sentry#sentry). + + +[Previous\\ +\\ +Compliance](https://docs.sentry.io/organization/integrations/compliance) + +[Next\\ +\\ +Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/truto/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) + +# Data Forwarding + +## Learn about forwarding processed events to third-party providers. + +This feature is available only if your organization is on [a Trial, Business, or Enterprise plan](https://sentry.io/pricing/). + +Sentry provides the ability to forward processed error events to certain third-party providers, such as [Segment](https://segment.com/) and [Amazon SQS](https://aws.amazon.com/sqs/). + +This is often useful when you may want to analyze exceptions more deeply, or empower other teams, such as a Business Intelligence function. + +Configure Data Forwarding by navigating to your **\[Project\] » Settings » Data Forwarding**, then providing the required information for the given integration. + +Only error events will be forwarded. Forwarding of transaction events is not supported. + +## [Amazon SQS](https://docs.sentry.io/concepts/data-management/data-forwarding/\#amazon-sqs) + +Integration with Amazon SQS makes it quick and easy to pipe exceptions back into your own systems. + +The payload for Amazon is identical to our standard API event payload, and will evolve over time. For more details on the format of this data, see our [API documentation](https://docs.sentry.io/api/events/retrieve-an-event-for-a-project/). + +## [Segment](https://docs.sentry.io/concepts/data-management/data-forwarding/\#segment) + +The Segment integration will generate _Error Captured_ events within your data pipeline. These events will **only** be captured for `error` events, and only when an ID is present the user context. The general shape of the event will look roughly similar to: + +JSON + +`` + +```json code-highlight +{ + "userId": "1", + "event": "Error Captured", + "properties": { + "environment": "production", + "eventId": "002c8bbde8324dae9f12a0b96f5b1e51", + "exceptionType": "ValueError", + "release": "a2def1", + "transaction": "/api/0/users/{user}/", + "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:54.0) Gecko/20100101 Firefox/54.0", + "page": { + "url": "https://sentry.io/api/0/users/{user}/", + "method": "GET", + "search": "", + "referer": "https://sentry.io/" + } + }, + "timestamp": "2017-05-20T15:29:06Z" +} + +``` + +## [Splunk](https://docs.sentry.io/concepts/data-management/data-forwarding/\#splunk) + +For details on the Splunk integration, visit the dedicated [Splunk integration documentation](https://docs.sentry.io/organization/integrations/data-visualization/splunk/). + +[Previous\\ +\\ +Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) + +[Next\\ +\\ +Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/data-forwarding.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Usage](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/) + +# How to Write - Usage + +The Usage section of the content covers how to manually capture events and message. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/usage` \- feel free to peruse the files in that directory to help answer questions. + +Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. + +Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions, if any arise, by opening an issue on GitHub. + +### [Index file](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/\#index-file) + +This file is `index.mdx`. It explains how to manually capture events. + +Add the code sample to these directories: + +- `/src/platform-includes/capture-error/` +- `/src/platform-includes/capture-message/` + +### [Set the Level](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/\#set-the-level) + +This file is `set-level.mdx`. It explains how to set the level of the event. Add the code sample to this directory: + +- `/src/platform-includes/set-level/` + +[Previous\\ +\\ +How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance) + +[Next\\ +\\ +Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-usage.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) +- [Versioning](https://docs.sentry.io/contributing/platforms/versioning/) + +# Versioning + +Versioning allows for the maintenance of multiple versions of the same documentation, which is crucial for supporting different SDK releases. This guide explains how to create versioned documentation in the docs platform. + +## [Creating a Versioned Page](https://docs.sentry.io/contributing/platforms/versioning/\#creating-a-versioned-page) + +To create a versioned page: + +1. Ensure the original page already exists. +2. Create a new file with the same name as the original, but append `__v{VERSION}` (two underscores) to the filename before the extension. + +**The version should follow one of these two formats:** + +- Major version only (for general version ranges): `__v{MAJOR}.x` +- Full semantic version (for specific versions): `__v{MAJOR}.{MINOR}.{PATCH}` + +For example: + +Bash + +`` + +```bash code-highlight +index.mdx (original) +index__v7.x.mdx (version 7.x.x) +index__v7.1.0.mdx (specific version 7.1.0) + +``` + +## [Versioning Platform Includes](https://docs.sentry.io/contributing/platforms/versioning/\#versioning-platform-includes) + +Pages in the `platform-includes` folder can be versioned using the same method. However, the root page referencing these includes must also be versioned. + +## [File Structure Example](https://docs.sentry.io/contributing/platforms/versioning/\#file-structure-example) + +Bash + +`` + +```bash code-highlight +docs/ +├── getting-started/ +│ ├── index.mdx +│ └── index__v7.x.mdx +└── platform-includes/ + └── configuration/ + ├── example.mdx + └── example__v7.x.mdx + +``` + +## [Version Selection and User Experience](https://docs.sentry.io/contributing/platforms/versioning/\#version-selection-and-user-experience) + +When multiple versions of a page exist: + +1. A dropdown menu appears below the platform selector, displaying all available versions for the current file. + +2. When a user selects a version: + + +- They are redirected to the chosen version of the page. +- A preference is stored in localStorage, specific to the current guide or platform. + +3. An alert is displayed when viewing "non-latest" pages to inform users they're not on the most recent version. + +4. If a user has a stored version preference: + + +- The app will perform a client-side redirect to this version whenever it's available for other pages. + +This approach ensures users can easily navigate between versions and keep their version preference across the documentation. + +## [Best Practices](https://docs.sentry.io/contributing/platforms/versioning/\#best-practices) + +1. Only add versioning to pages when necessary, to avoid content duplication and save build times. +2. Ensure all related content (including `platform-includes`) is versioned consistently. + +## [Limitations and Considerations](https://docs.sentry.io/contributing/platforms/versioning/\#limitations-and-considerations) + +- Versioning is only available for existing pages. +- The versioning system relies on the file naming convention, so it's important to follow the `__v{VERSION}` format precisely. + +By following these guidelines, it's possible to effectively manage multiple versions of documentation, ensuring users can access the appropriate information for their specific version of the software or API. + +[Previous\\ +\\ +Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons) + +[Next\\ +\\ +Linking Variables](https://docs.sentry.io/contributing/linking) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/versioning.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) +- [Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso/) + +# Ping Identity SSO + +## Set up Ping Identity Single Sign-On (SSO) on Sentry. + +## [Installation](https://docs.sentry.io/organization/authentication/sso/ping-sso/\#installation) + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. + +01. Log in to [Ping Identity](https://www.pingidentity.com/en/account/sign-on.html). + +02. Go to the "Adminstrators" environment for your organization. + +03. If you don't require a permission group for Sentry, skip to step 5. + +04. In the sidebar, click on "Identities", then "Groups", and navigate to it. From there, create a new group and add yourself and other members to it. For more details about group creation, see the [Ping ID docs](https://docs.pingidentity.com/bundle/pingone/page/vdz1610472224361.html). + +05. In the sidebar, click on "Connections", then "Applications". Click on "+ Application" and for the application type, select "Web App" and "SAML". + + [![Create web application for Ping](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fping-new-app-VKZCD57R.png%233584x1702&w=3840&q=75)](https://docs.sentry.io/mdx-images/ping-new-app-VKZCD57R.png) + +06. For section (1), labeled "Create App Profile", you can get the Sentry logo from [here](https://sentry.io/branding/). + +07. For section (2), labeled "Configure SAML", select "Manually Enter". Enter the following data in each line and save your changes. + + - Assertion Consumer Service (ACS) URL: `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` + + - Entity ID: `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` + + - Single-Logout (SLO) Endpoint: `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` + + - Target Application URL: `https://sentry.io/organizations/YOUR_ORG_SLUG/` +08. In section (3), labeled "Attribute Mappings", for "Application Attribute" ← "Outgoing Value", use: + + - `saml_subject` ← `Email address` + + - `email` ← `Email address` + + - `first_name` ← `Given Name` + + - `last_name` ← `Family Name` + + You can use custom key values, but you will need to amend the steps below. For more details about advanced attribute mappings for custom configs, see [this guide from Ping ID](https://support.pingidentity.com/s/article/PingOne-Using-Advanced-Attribute-Mapping). +09. Once the application is created, click on the Sentry application and navigate to "Configuration" and copy "IDP Metadata URL". This URL will be used in the subsequent step on Sentry. + + [![Ping configuration for Sentry](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fping-configure-sentry-INWYPDRP.png%233584x1442&w=3840&q=75)](https://docs.sentry.io/mdx-images/ping-configure-sentry-INWYPDRP.png) + +10. Go back to [Sentry](https://sentry.io/). Navigate to **Settings > Auth** (or go to `https://sentry.io/settings/YOUR_ORG_SLUG/auth/`) and click on "Configure" for SAML2. + +11. Paste the IDP Metadata URL from above and click "Get Metadata". + +12. On the next page, enter the following keys in their respective fields to map the Ping ID attributes to Sentry, and then save them: + + - IdP User ID: `saml_subject` + + - User Email: `email` + + - First Name: `first_name` + + - Last Name: `last_name` +13. Sentry will attempt to authenticate and link your account with Ping Identity. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can take the following actions: + + - You can share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. + + - Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Ping. + + - Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. + + - If you made changes, click "Save Settings" to complete your setup. + +[Previous\\ +\\ +Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) + +[Next\\ +\\ +Custom SAML Provider](https://docs.sentry.io/organization/authentication/sso/saml2) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/ping-sso.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) + +# Single Sign-On (SSO) + +## Learn about single sign-on (SSO) and how it helps manage your organization. + +Single sign-on (or SSO) allows you to manage your organization’s entire membership via a third-party provider. + +## [Preface](https://docs.sentry.io/organization/authentication/sso/\#preface) + +Before you get around to actually turning on SSO, you’ll want to keep in mind that once it’s activated, all existing users will need to link their account before they are able to continue using Sentry. Because of that we recommend coordinating with your team during off-peak hours. That said, it’s super quick to link accounts, so we don’t consider it a true hurdle. + +## [Getting Started](https://docs.sentry.io/organization/authentication/sso/\#getting-started) + +With that out of the way, head on over to your organization home. You’ll see an “Auth” link in the sidebar if you have access to SSO. Start by hitting that, and then continue to the “Configure” link next to provider you wish to configure. + +Additionally we’ll automatically send each pre-existing member an email with instructions on linking their account. This will happen automatically once SSO is successfully configured. Even if they don't click the link, the next time they try to hit any page within the organization we’ll require them to link their account (with the same auth flow you just went through). + +## [Default Membership](https://docs.sentry.io/organization/authentication/sso/\#default-membership) + +Every member who creates a new account via SSO will be given global organization access with a member role. This means that they can access events from any team, but they won’t be able to create new projects or administer current ones. + +## [Security](https://docs.sentry.io/organization/authentication/sso/\#security) + +Our SSO implementation prioritizes security. We aggressively monitor linked accounts and will disable them if there's any reasonable sign that the account’s access may have been revoked. Generally this will be transparent to you, but if the provider is functioning in an unexpected way you may experience more frequent re-authorization requests. + +Sessions last for [Django's default session length](https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-cookie-based-sessions), which is two weeks. For individual organizations with single sign-on, we expire organization access after one day (20 hours). + +## [Providers](https://docs.sentry.io/organization/authentication/sso/\#providers) + +### [Google Business App](https://docs.sentry.io/organization/authentication/sso/\#google-business-app) + +This feature is available only if your organization is on [a Trial, Team, or higher plan](https://sentry.io/pricing/). + +Enabling the Google integration will ask you to authenticate against a Google Apps account. Once done, membership will be restricted to only members of the given Apps domain (i.e. `sentry.io`). + +If you need to allow users across multiple domains to access your organization or change your Google domain, please contact our support team. + +### [GitHub Organizations](https://docs.sentry.io/organization/authentication/sso/\#github-organizations) + +This feature is available only if your organization is on [a Trial, Team, or higher plan](https://sentry.io/pricing/). + +The GitHub integration will authenticate against all organizations, and once complete prompt you for the organization which you wish to restrict access by. + +### [SAML2 Identity Providers](https://docs.sentry.io/organization/authentication/sso/\#saml2-identity-providers) + +This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. + +Sentry provides [SAML2 based authentication](https://en.wikipedia.org/wiki/SAML_2.0) which may be configured manually using the generic SAML2 provider, or a specific provider listed below that provides defaults specific to that identity provider: + +- [AuthO](https://docs.sentry.io/organization/authentication/sso/#auth0) +- [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/#azure-active-directory) +- [Okta](https://docs.sentry.io/organization/authentication/sso/#okta) +- [OneLogin](https://docs.sentry.io/organization/authentication/sso/#onelogin) +- [Rippling](https://docs.sentry.io/organization/authentication/sso/#rippling) +- [Jumpcloud](https://docs.sentry.io/organization/authentication/sso/#jumpcloud) + +Sentry supports the following SAML services: + +- Identity and Service Provider initiated SSO +- Identity Provider initiated SLO (Single Logout) + +Sentry’s Assertion Consumer Service uses the HTTP-POST bindings. + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SSO/SAML configuration values. + +Sentry’s SAML endpoints are as follows, where the `[organization_slug]` is substituted for your organization slug: + +| ACS: | `https://sentry.io/saml/acs/[organization_slug]/` | +| SLS: | `https://sentry.io/saml/sls/[organization_slug]/` | +| Metadata: | `https://sentry.io/saml/metadata/[organization_slug]/` | + +#### [Auth0](https://docs.sentry.io/organization/authentication/sso/\#auth0) + +In your Auth0 dashboard, locate the Sentry app under the SSO Integrations page and add it to your organization. + +As part of the Auth0 SSO configuration, you must provide the Auth0 Identity Provider metadata to Sentry. This URL is available under the Tutorial tab of the Sentry SSO integration. + +You may refer to the [Auth0 documentation](https://auth0.com/docs/integrations/sso/sentry) for more detailed setup instructions. + +#### [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/\#azure-active-directory) + +In your Azure AD dashboard, locate the Sentry app under Enterprise Applications and add it to your organization. + +You may refer to [our documentation](https://docs.sentry.io/organization/authentication/sso/azure-sso/) for more detailed setup instructions. + +#### [Okta](https://docs.sentry.io/organization/authentication/sso/\#okta) + +In your Okta admin dashboard, locate the Sentry app in the Okta Application Network and add it to your organization. + +As part of the Okta SSO configuration, you must provide the Okta Identity Provider metadata to Sentry. This URL can be located under the Sign-On Methods SAML2 settings panel, look for the ‘Identity Provider metadata’ link which can may right click and copy link address. + +You may refer to [our documentation](https://docs.sentry.io/organization/authentication/sso/okta-sso/) for more detailed setup instructions. + +#### [OneLogin](https://docs.sentry.io/organization/authentication/sso/\#onelogin) + +In your OneLogin dashboard, locate the Sentry app in the app catalog and add it to your organization. + +As part of OneLogin SSO configuration, you must to provide the OneLogin identity provider issuer URL to Sentry. This URL is specific to your OneLogin account and can be found under the "SSO" tab on the Sentry OneLogin application configuration page. + +You may refer to the [OneLogin documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=1d199dcfdbdc5700d5505eea4b96196a) for more detailed setup instructions. + +#### [Rippling](https://docs.sentry.io/organization/authentication/sso/\#rippling) + +In your Rippling admin dashboard, locate the Sentry app in the list of suggested apps and select it. + +When prompted with the Rippling Metadata URL, copy this into the Sentry Rippling provider configuration. You will have to complete the Rippling application configuration before completing the Sentry provider configuration. + +#### [Jumpcloud](https://docs.sentry.io/organization/authentication/sso/\#jumpcloud) + +In your Jumploud Admin portal: + +1. Navigate to **User Authentication > SSO**. +2. Add a new SSO application and search for Sentry. +3. Click "Configure". +4. Under the SSO menu, update the SP Entity ID and ACS URLs for your tenant. They should be in the format as described [here](https://docs.sentry.io/organization/authentication/sso/saml2/#register-sentry-with-idp). +5. Click "save". + +Be sure that you have assigned yourself to the Sentry app in Jumpcloud before attempting these next steps. + +1. In [sentry.io](https://sentry.io/), navigate to **Settings > Auth** in your organization. +2. Click "Configure" on the Jumpcloud provider. +3. Go to the "XML" within the register page. +4. Download your Jumpcloud metadata under the "SSO" tab in your Jumpcloud Sentry SSO app by clicking "Export Metadata". +5. Paste your XML metadata into the text field and click "Parse Metadata". +6. On the "Map Identity Provider" page, fill in 'uniqueID', 'email', 'firstname', and 'lastname' if you have left your Jumpcloud attributes as the defaults for the Sentry app. + +Now, Sentry should be configured for Jumpcloud SSO. + +#### [Custom SAML2 Integration](https://docs.sentry.io/organization/authentication/sso/\#custom-saml2-integration) + +For other SAML2 SSO providers not listed above, Sentry provides generic connectors for [SAML2 based authentication](https://docs.sentry.io/organization/authentication/sso/saml2/), which may be configured manually. + +## [SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/\#scim-provisioning) + +This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. + +If you change your organization slug, you'll need to make the same update in places where you enter the configuration values when setting up SCIM. + +System for Cross-Domain Identity Management ( [SCIM](http://www.simplecloud.info/)) is a standard implemented by Identity Providers and applications to facilitate automated identity management. Sentry supports a subset of the specification for provisioning organization members and teams. See the relevant documentation for your use case: + +- [Okta SCIM Setup](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) +- [Azure AD SCIM Setup](https://docs.sentry.io/organization/authentication/sso/azure-sso/#scim-integration) +- If your Provider is not listed here, SCIM may be supported as it is a common standard. If you are having issues please contact our support team. + +[Previous\\ +\\ +Authentication](https://docs.sentry.io/organization/authentication) + +[Next\\ +\\ +Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Images](https://docs.sentry.io/contributing/pages/images/) + +# Images + +If you want to add images to your docs, you can add them in a `./img` folder in the same directory as your `.mdx` files. You don't have to follow a rigid folder structure as long as the relative path (starts with `./`) to the image is correct. See [local images](https://docs.sentry.io/contributing/pages/images/#local-images). + +If an image is used in multiple places, it's best to put it in `includes/common-imgs/imgs` and reference it in a local [`include` file](https://docs.sentry.io/contributing/approach/product-docs/write-index/#includes) to be used in the target `mdx` file. See [common images](https://docs.sentry.io/contributing/pages/images/#common-images). + +Alternatively, images can also be added to the `public` folder and referenced using their relative or full path within the folder. See [public images](https://docs.sentry.io/contributing/pages/images/#public-images) + +Every image path that starts with `/` (instead of `./`) is considered to be in the `public` folder. + +### [Examples](https://docs.sentry.io/contributing/pages/images/\#examples) + +#### [Local Images](https://docs.sentry.io/contributing/pages/images/\#local-images) + +The file, `docs/product/alerts/alert-types.mdx`, can reference the local `docs/product/alerts/img/alert-details-example.png` image like so : + +Markdown + +`docs/product/alerts/alert-types.mdx` + +```markdown code-highlight +![Alert details ...](./img/alert-details-example.png) + +``` + +#### [Common Images](https://docs.sentry.io/contributing/pages/images/\#common-images) + +Images that are reused in multiple files should be single-sourced as an `include` file. For example, the common image, `includes/common-imgs/imgs/tags.png`, is referenced in the `include` file, `includes/common-imgs/tags.mdx`, like so: + +Markdown + +`includes/common-imgs/tags.mdx` + +```markdown code-highlight +![Tags](./img/tags.png) + +``` + +The image can then be used in multiple places (such as `docs/platforms/ruby/common/enriching-events/tags/index.mdx`) by referencing the `include` file with the following syntax: + +Markdown + +`docs/platforms/ruby/common/enriching-events/tags/index.mdx` + +```markdown code-highlight +<Include name="common-imgs/tags" /> + +``` + +#### [Public Images](https://docs.sentry.io/contributing/pages/images/\#public-images) + +While we recommend storing images locally with the files that reference them, you can also put them in the `public` folder. By default, the docs platform assumes images referenced with paths starting with `/` live in the `public` folder, so you don't need to include `public` in the image path. + +The folder structure of `public` mimics that of `docs` so that you can reference these images with relative paths. For example, the file, `docs/product/alerts/alert-types.mdx`, can reference the image, `public/product/alerts/issue-alert.png`, like so : + +Markdown + +`docs/product/alerts/alert-types.mdx` + +```markdown code-highlight +![Issue alert](issue-alert.png) + +``` + +Content files living elsewhere can also reference public images by using their full paths (excluding `public`). For example, the file, `docs/platform/apple/index.mdx`, can also reference the same image, `public/product/alerts/issue-alert.png`, like so: + +Markdown + +`docs/platform/apple/index.mdx` + +```markdown code-highlight +![Issue alert](/product/alerts/issue-alert.png) + +``` + +## [Image Optimization](https://docs.sentry.io/contributing/pages/images/\#image-optimization) + +To save space and ensure consistency, we ask that all image files be compressed and cropped to the dimensions listed below. When adding an image, please makes sure that it's high-resolution and crisp and that text is big enough to read. + +### [Recommended Dimensions](https://docs.sentry.io/contributing/pages/images/\#recommended-dimensions) + +- If you want the image to take up the full width of the page, make it **1484 pixels** wide. + +- If you want the image to be indented once (for example, if it's under a list item), make it **1400 pixels** wide. + + +### [Image Compression](https://docs.sentry.io/contributing/pages/images/\#image-compression) + +For performance reasons, images should be compressed. We recommend using ImageOptim. Here are the steps to follow: + +1. Download and install [https://imageoptim.com/](https://imageoptim.com/). +2. Drag and drop your image(s) into the tool. The files will be compressed in place. +3. Wait until a green checkmark appears, then add the compressed image to the appropriate path in the `public` folder of the docs repo. + +[Previous\\ +\\ +Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter) + +[Next\\ +\\ +Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/images.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) + +# Concepts & Reference + +## Learn the basic concepts of Sentry such as searchable properties and data management settings. + +[Previous\\ +\\ +Security, Legal, & PII](https://docs.sentry.io/security-legal-pii) + +[Next\\ +\\ +Concepts](https://docs.sentry.io/concepts/key-terms) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Authentication](https://docs.sentry.io/api/auth/) + +# Authentication + +## [Auth Tokens](https://docs.sentry.io/api/auth/\#auth-tokens) + +Authentication tokens are passed using an auth header, and are used to authenticate as a user or organization account with the API. In our documentation, we have several placeholders that appear between curly braces or chevrons, such as `{API_KEY}` or `<auth_token>`, which you will need to replace with one of your authentication tokens in order to use the API call effectively. + +For example, when the documentation says: + +Bash + +`` + +```bash code-highlight +curl -H 'Authorization: Bearer {TOKEN}' https://sentry.io/api/0/organizations/{organization_slug}/projects/ + +``` + +If your authentication token is `1a2b3c`, and your organization slug is `acme` then the command should be: + +Bash + +`` + +```bash code-highlight +curl -H 'Authorization: Bearer 1a2b3c' https://sentry.io/api/0/organizations/acme/projects/ + +``` + +You can create authentication tokens within Sentry by [creating an internal integration](https://docs.sentry.io/organization/integrations/integration-platform/#internal-integrations). This is also available for self-hosted Sentry. + +### [User authentication tokens](https://docs.sentry.io/api/auth/\#user-authentication-tokens) + +Some API endpoints require an authentication token that's associated with your user account, rather than an authentication token from an internal integration. These auth tokens can be created within Sentry on the "User settings" page ( **User settings > User Auth Tokens**) and assigned specific scopes. + +The endpoints that require a user authentication token are specific to your user, such as [Retrieve an Organization](https://docs.sentry.io/api/organizations/retrieve-an-organization/). + +## [DSN Authentication](https://docs.sentry.io/api/auth/\#dsn-authentication) + +Some API endpoints may allow DSN-based authentication. This is generally very limited and an endpoint will describe if its supported. This works similar to Bearer token authentication, but uses your DSN (Client Key). + +Bash + +`` + +```bash code-highlight +curl -H 'Authorization: DSN {DSN}' https://sentry.io/api/0/{organization_slug}/{project_slug}/user-reports/ + +``` + +## [API Keys](https://docs.sentry.io/api/auth/\#api-keys) + +##### Note + +API keys are a legacy means of authenticating. They will still be supported but are disabled for new accounts. You should use **authentication tokens** wherever possible. + +API keys are passed using HTTP Basic auth where the username is your api key, and the password is an empty value. + +As an example, to get information about the project which your key is bound to, you might make a request like so: + +Bash + +`` + +```bash code-highlight +curl -u {API_KEY}: https://sentry.io/api/0/organizations/{organization_slug}/projects/ + +``` + +You **must** pass a value for the password, which is the reason the `:` is present in our example. + +[Previous\\ +\\ +API Reference](https://docs.sentry.io/api) + +[Next\\ +\\ +Paginating Results](https://docs.sentry.io/api/pagination) + +- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/) + +# Issue Properties + +## Learn more about searchable issue properties. + +[Issues](https://docs.sentry.io/product/issues/) are an aggregate of one or more error events. Searchable issues properties include status, assignment, aggregate counts, and age. If you have set up [evaluation tracking for feature flags](https://docs.sentry.io/product/issues/issue-details/feature-flags/#evaluation-tracking), you can search for issues that have error events where the feature flag evaluated value is `true` or `false`. You can search by issue properties in the **Issues** page and in **Dashboards** in the widget builder, depending on your dataset selection. + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the issues search. + +You'll only need to use query syntax for **datetime** and **relative time** searchable property types if you're using the Sentry [API](https://docs.sentry.io/api/). + +### [`age`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#age) + +Returns issues created since the time defined by the value. The syntax is similar to the Unix find command. Supported suffixes: `m - minutes`, `h - hours`, `d - days`, `w - weeks`. For example, `age:-24h` returns isssues that are new in the last 24 hours, while `age:+12h` returns ones that are older than 12 hours. Entering `age:+12h age:-24h` would return issues created between 12 and 24 hours ago. + +- **Type:** relative time + +### [`app.in_foreground`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#appin_foreground) + +Indicates if the app is in the foreground or background. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`assigned`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#assigned) + +Returns issues assigned to the defined user(s) or team(s). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee, `my_teams` or `#team-name` for teams you belong to. + +- **Type:** team or org user + +### [`assigned_or_suggested`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#assigned_or_suggested) + +Returns issues that are assigned to or suggested to be assigned to the defined user(s) or team(s). Suggested assignees are found by matching [ownership rules](https://docs.sentry.io/product/issues/ownership-rules/) and [suspect commits](https://docs.sentry.io/product/issues/suspect-commits/). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee/suggestion, `my_teams` or `#team-name` for teams you belong to. + +- **Type:** team or org user + +### [`bookmarks`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#bookmarks) + +Returns issues bookmarked by the defined user. Values can be your user ID (your email address) or `me` for yourself. + +- **Type:** team or org user + +### [`device.arch`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicearch) + +CPU architecture + +- **Type:** string + +### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicebrand) + +Brand of the device + +- **Type:** string + +### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicefamily) + +Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. + +- **Type:** string + +### [`device.locale`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicelocale) + +Deprecated + +- **Type:** string + +### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicemodel_id) + +Internal hardware revision to identify the device exactly. + +- **Type:** n/a + +### [`device.orientation`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#deviceorientation) + +Describes the orientation of the device and can be either `portrait` or `landscape`. + +- **Type:** string + +### [`device.screen_density`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_density) + +Device screen density in pixels. + +- **Type:** string + +### [`device.screen_dpi`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_dpi) + +Number of dots per inch of the device screen. + +- **Type:** string + +### [`device.screen_height_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_height_pixels) + +Device screen height in pixels. + +- **Type:** string + +### [`device.screen_width_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_width_pixels) + +Device screen width in pixels. + +- **Type:** string + +### [`device.uuid`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#deviceuuid) + +Deprecated + +- **Type:** UUID + +### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#dist) + +Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. + +- **Type:** string + +### [`error.handled`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorhandled) + +Indicates whether the user has handled the exception — for example, using try...catch. An error is considered handled if all stack traces handle the error. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`error.main_thread`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errormain_thread) + +Indicates if the error occurred on the main thread. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`error.mechanism`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errormechanism) + +An object describing the mechanism that created this exception. + +- **Type:** array + +### [`error.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errortype) + +The type of exception. For example, `ValueError`. + +- **Type:** array + +### [`error.unhandled`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorunhandled) + +The inversion of `error.handled`. + +- **Type:** boolean + +### [`error.value`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorvalue) + +Original value of a field that causes or exhibits the error. + +- **Type:** array + +### [`event.timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#eventtimestamp) + +Returns issues with matching datetime. + +- **Type:** datetime + +### [`event.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#eventtype) + +Type of the event (transaction, error, default, csp, and so on). The transaction type is unavailable in **Issues**. + +- **Type:** string + +### [`firstRelease`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#firstrelease) + +Returns issues first seen within the given release. Can be an exact match on the version of a release, or `first-release:latest` to pick the most recent release. + +- **Type:** datetime + +### [`firstSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#firstseen) + +Returns issues with a matching first time seen. Syntax is the same as `age`. + +- **Type:** datetime + +### [`flags`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#flags) + +For [feature flag evaluations](https://docs.sentry.io/product/issues/issue-details/feature-flags/#evaluation-tracking) set to `true` or `false`, the name of the feature flag. + +- **Type:** boolean + +### [`geo.city`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#geocity) + +Full name of the city + +- **Type:** string + +### [`geo.country_code`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#geocountry_code) + +ISO 3166-1 country code + +- **Type:** string + +### [`geo.region`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#georegion) + +Full name of the country + +- **Type:** string + +### [`has`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#has) + +Returns results with the defined tag or field, but not the value of that tag or field. For example, entering `has:user` would find events with the `user` tag. + +- **Type:** error + +### [`http.method`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpmethod) + +HTTP method of the [request](https://develop.sentry.dev/sdk/data-model/event-payloads/request/) that created the event. + +- **Type:** string + +### [`http.referer`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpreferer) + +Identifies the web page from which the resource was requested. + +- **Type:** string + +### [`http.status_code`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpstatus_code) + +HTTP status code, which indicates whether a response was successful. For example, `200` or `404`. + +- **Type:** string + +### [`http.url`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpurl) + +Full URL of the request that caused the error, but without any parameters + +- **Type:** string + +### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#id) + +The event or replay id. In **Issues**, use only the ID value without the `id` key. + +- **Type:** UUID + +### [`is`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#is) + +The properties of an issue. Values can be: `unresolved`, `resolved`, `archived`, `assigned`, `unassigned`, `for_review`, `linked`, or `unlinked`. The `for_review` value filters unresolved issues and only shows the recently unresolved or new issues that haven't been marked as "reviewed". The `linked` and `unlinked` values return issues based on whether they're linked to an external issue tracker or not. + +- **Type:** status + +### [`issue`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issue) + +The short issue code, for example `SENTRY-ABC`. + +- **Type:** string + +### [`issue.category`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issuecategory) + +The category of the issue. For example: `error`, `performance`, `replay` and `cron`. + +- **Type:** string + +### [`issue.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issuetype) + +The specific type of issue. For example `issue.type:performance_n_plus_one_db_queries ` returns the n plus one db query performance issues. + +- **Type:** string + +### [`lastSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#lastseen) + +Datetime when the event was last seen. For example, `lastSeen:+30d` returns issues last seen 30 days ago or more; `lastSeen:-2d` returns issues last seen within the past two days. This is similar to `age`. + +- **Type:** datetime + +### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#level) + +Severity of the event (such as: fatal, error, warning). Always set to info for transactions. + +- **Type:** string + +### [`location`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#location) + +Location where the error happened. + +- **Type:** string + +### [`message`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#message) + +Returns errors with the matching message or transactions with matching transaction name. Also matches on any message containing the supplied value.Searching `message:undefined` will match an event with a message of `undefined is not an object`. Raw text searches (searches without the `message` key) are also checked against this field. For errors, the message can be a concatenatenation of elements, so searches might include unexpected results. + +- **Type:** string + +### [`os.build`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osbuild) + +The internal build revision of the operating system. + +- **Type:** string + +### [`os.kernel_version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#oskernel_version) + +The independent kernel version string. This is typically the entire output of the `uname` syscall. + +- **Type:** string + +### [`os.distribution_name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osdistribution_name) + +The Linux distribution name. This maps to `ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). + +- **Type:** string + +### [`os.distribution_version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osdistribution_version) + +The Linux distribution version. This maps to `VERSION_ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). + +- **Type:** string + +### [`platform.name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#platformname) + +Name of the platform + +- **Type:** string + +### [`project`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#project) + +The name of the project. In some pages of [sentry.io](https://sentry.io/), you can also filter on project using a dropdown. + +- **Type:** string + +### [`project.id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#projectid) + +The id of the project. + +- **Type:** number + +### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#release) + +A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasebuild) + +The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** number + +### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasepackage) + +The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasestage) + +The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). + +- **Type:** string + +### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releaseversion) + +A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#sdkname) + +Name of the Sentry SDK that sent the event. + +- **Type:** string + +### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#sdkversion) + +Version of the Sentry SDK that sent the event. + +- **Type:** string + +### [`stack.abs_path`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackabs_path) + +The absolute path to the source file. In events, this is an array; in issues, this is a single value. + +- **Type:** array, single value + +### [`stack.filename`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackfilename) + +The path to the source file relative to the project root directory. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.function`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackfunction) + +Name of the function being called. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.module`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackmodule) + +Platform-specific module path. For example, `sentry.interfaces.Stacktrace`. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.package`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackpackage) + +The "package" the frame was contained in. Depending on the platform, this can be different things. For C#, it can be the name of the assembly. For native code, it can be the path of the dynamic library or something else. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`timesSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#timesseen) + +Returns results with a matching count. (Same as `count()` in events.) + +- **Type:** number + +### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#timestamp) + +The finish timestamp of the transaction. Returns events with matching datetime. + +- **Type:** datetime + +### [`title`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#title) + +Title of the error or the transaction name. + +- **Type:** string + +### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#trace) + +A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. + +- **Type:** UUID + +### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#transaction) + +For [transactions](https://docs.sentry.io/product/insights/overview/transaction-summary/#what-is-a-transaction), the name of the transaction. For errors, the name of the associated transaction. + +- **Type:** string + +### [`unreal.crash_type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#unrealcrash_type) + +The [Unreal Crash Context Type](https://docs.unrealengine.com/4.27/en-US/API/Runtime/Core/GenericPlatform/ECrashContextType/) + +- **Type:** string + +### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#useremail) + +An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. + +- **Type:** string + +### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userid) + +Application-specific internal identifier for the user. + +- **Type:** string + +### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userip) + +User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. + +- **Type:** string + +### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userusername) + +Username, which is typically a better label than the `user.id`. + +- **Type:** string + +[Previous\\ +\\ +Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) + +[Next\\ +\\ +Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/issues.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) + +# Concepts + +## Learn about important concepts that are essential to using Sentry. + +[Previous\\ +\\ +Concepts & Reference](https://docs.sentry.io/concepts) + +[Next\\ +\\ +Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [MDX Components](https://docs.sentry.io/contributing/pages/components/) + +# MDX Components + +## [Alert](https://docs.sentry.io/contributing/pages/components/\#alert) + +Render an alert (sometimes called a callout) to highlight important information. + +##### Note + +This is an info alert. Use this to emphasize information that users should read. + +##### Important + +This is a warning alert. Use this to alert users to potential risks they should be aware of. + +##### Tip + +This is a success alert. Use this to provide optional information that can help users be more successful. + +This is an alert without a title. `warning` alerts should always have titles to emphasize their importance. + +This is a multi-line alert without a title. Keep information brief and to the point. If this is challenging, consider whether the topic needs documentation on another page or if using the [Expandable](https://docs.sentry.io/contributing/pages/components/#expandable) component would be a better fit. + +##### List + +- You can create lists +- and **format** _your_ `text` + +InfoWarningSuccessNo Title + +`` + +```markdown code-highlight +<Alert title="Note"> +This is an info alert. +</Alert> + +``` + +Attributes: + +- `title` (string) - optional +- `level` (string: `'info' | 'warning' | 'success'`) \- optional, defaults to `'info'` + +**Where to place alerts:** + +Make sure your alerts aren't breaking the flow of the content. For example, don't put an alert between two paragraphs that explain a single concept. Use alerts sparingly; too many alerts on a single page can be overwhelming. + +**When to use which alert level:** + +- **Info**: Use this to emphasize information that users should read. For example: + + - information needed for users to succeed + - information you'd typically wrap in a note callout +- **Warning**: Use this to alert users to potential risks they should be aware of. For example: + + + - warnings about potential errors, such as ones caused by common oversights in project configuration + - warnings regarding breaking changes + +Best practices: + + - always use a title with this alert level +- **Success**: Use this to provide optional information that can help users be more successful. For example: + + - information that helps improve an already successful task, such as a link to additional reading material + - tips for best practices + +## [Arcade embeds](https://docs.sentry.io/contributing/pages/components/\#arcade-embeds) + +Render an [Arcade](https://arcade.software/) embed. + +Create Internal Integration & Alert Rule + +Create Internal Integration & Alert Rule + +![Select "Internal Integration" then click "Next".](<Base64-Image-Removed>)![Enter a name for your integration.](<Base64-Image-Removed>)![Click to create a new integration.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/c16e1f56-ecbc-4abd-ad6f-9cf8d0299105.png) + +![](<Base64-Image-Removed>) + +Example + +`` + +```markdown code-highlight +<Arcade src="https://demo.arcade.software/v7uhzmdV6Q5PDzoVPAE6?embed&show_copy_link=true" /> + +``` + +Attributes: + +- `src` (string) - the URL of the Arcade embed + +## [Expandable](https://docs.sentry.io/contributing/pages/components/\#expandable) + +Render an expandable section to provide additional information to users on demand. + +##### Here's something worth noting + +##### [With permalink](https://docs.sentry.io/contributing/pages/components/\#with-permalink) + +##### This could be important to some users + +##### Want some tips to improve something? + +ExamplePermalinkWarningSuccess + +`` + +```markdown code-highlight +<Expandable title="Here's something worth noting"> + This is an expandable section in an `'info'` alert style. +</Expandable> + +``` + +Attributes: + +- `title` (string) +- `permalink` (boolean) - optional: wraps the title in a link and shows it in the table of contents. + +**When to use expandables:** + +Expandables help keep our documentation clutter-free, allowing users to focus on important information while providing them the option to explore additional relevant details. + +For example, use expandables to: + +- offer information that is useful to some users but not all, like troubleshooting tips +- provide background information or insights into related concepts + +**Best practices** + +- Write the expandable title as a question or statement to clarify what users can expect from the content within: + - Do you want to learn more about these features? + - Are you using Node.js version 15 or lower? + - Advanced configuration options for XY use case. +- When you need to share important information that users should read, consider using an [alert](https://docs.sentry.io/contributing/pages/components/#alert) instead since its content is visible by default. +- Avoid overusing this component and make sure to provide valuable information that is relevant to the current topic. + +## [Code Blocks](https://docs.sentry.io/contributing/pages/components/\#code-blocks) + +Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages: + +Example + +`` + +````markdown code-highlight +```javascript +function foo() { +return "bar"; +} +``` + +```python +def foo(): +return 'bar' +``` + +```` + +Sometimes you may not want this behavior. To solve this, you can either break up the code blocks with some additional text, or use the `<Break />` component. + +Additionally code blocks also support `tabTitle` and `filename` properties: + +Example + +`` + +````markdown code-highlight +```javascript {tabTitle: Hello} {filename: index.js} +var foo = "bar"; +``` + +```` + +You can bring attention to specific lines in a code block using the `{fromLineA-toLineB}` for ranges, or `{lineA,lineB}` for specific lines (or a combination of the two): + +ExampleSource + +`` + +```code-highlight javascript +function foo() { + let lookat = "me"; + return "bar"; +} + +``` + +You can also highlight diffs using the `diff` language: + +Example + +`` + +````markdown code-highlight +```diff +- minus one ++ plus one +``` + +```` + +If you want to preserve syntax highlighting, you can add `diff` metadata to any code block then annotate the diff with `+` and `-`: + +ExampleSource + +`` + +```code-highlight javascript code-diff +function foo() { +- return "bar"; ++ return "baz"; +} + +``` + +## [ConfigKey](https://docs.sentry.io/contributing/pages/components/\#configkey) + +Render a heading with a configuration key in the correctly cased format for a given platform. + +If content is specified, it will automatically hide the content when the given `platform` is not selected in context. + +Example + +`` + +```markdown code-highlight +<ConfigKey name="send-default-pii" notSupported={["javascript"]}> + +Description of send-default-pii + +</ConfigKey> + +``` + +Attributes: + +- `name` (string) +- `platform` (string) - defaults to the `platform` value from the page context +- `supported` (string\[\]) +- `notSupported` (string\[\]) + +## [PageGrid](https://docs.sentry.io/contributing/pages/components/\#pagegrid) + +Render all `next_steps` of this document or default child pages, including their `description` if available. + +You can specify `next_steps` in the frontmatter of a page to include them in the grid. It supports relative paths and will automatically resolve them. + +Example + +`` + +```markdown code-highlight +--- +# in the frontmatter of a page: +next_steps: + - ./child-one + - ./child-two + - ../parent/child-three +--- + +<PageGrid /> + +``` + +Attributes: + +- `header` (string) - optional header value to include, rendered as an H2 + +- `nextPages` (boolean) - only render pages which come next based on sidebar ordering + +- `exclude` (string\[\]) - an array of pages to exclude from the grid. Specify the file name of the page, for example, `"index"` for `index.mdx`. + + +## [PlatformContent](https://docs.sentry.io/contributing/pages/components/\#platformcontent) + +Render an include based on the currently selected `platform` in context. + +Example + +`` + +```markdown code-highlight +<PlatformContent includePath="sdk-init" /> + +``` + +Attributes: + +- `includePath` (string) - the subfolder within `/includes` to map to +- `platform` (string) - defaults to the `platform` value from the page context + +Some notes: + +- When the current platform comes from the page context and no matching include is found, the content will be hidden. + +- Similar to `PlatformSection`, you can embed content in the block which will render _before_ the given include, but only when an include is available. + +- A file named `_default` will be used if no other content matches. + + +Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it. + +## [PlatformIdentifier](https://docs.sentry.io/contributing/pages/components/\#platformidentifier) + +Render terms in the correct case within the body text of a page (not in code samples) based on the platform case\_style setting: + +Example + +`` + +```markdown code-highlight +<PlatformIdentifier name="before-send" /> + +``` + +For example, if you use `<PlatformIdentifier name="before-send" />`, it will render as: + +- `beforeSend` if case\_style=camelCase +- `before_send` if case\_style=snake\_case +- `BeforeSend` if case\_style=PascalCase + +This component only works properly in platform pages. + +## [PlatformLink](https://docs.sentry.io/contributing/pages/components/\#platformlink) + +Useful for linking to platform-specific content when there's not a specific platform already selected. + +Example + +`` + +```markdown code-highlight +<PlatformLink to="/enriching-events/" /> + +``` + +This will direct users to a page where they can choose the platform, and then to the appropriate link. If they're within a page that already has an active platform, it will simply link to the appropriate page and skip the redirect. + +## [PlatformSection](https://docs.sentry.io/contributing/pages/components/\#platformsection) + +Render a section based on the currently selected `platform` in context. When the platform is not valid, the content will be hidden. + +Example + +`` + +```markdown code-highlight +<PlatformSection notSupported={["javascript"]}> + +Something that applies to all platforms, but not javascript or node. + +</PlatformSection> + +``` + +Attributes: + +- `platform` (string) - defaults to the `platform` value from the page context +- `supported` (string\[\]) +- `notSupported` (string\[\]) +- `noGuides` (boolean) - hide this on all guides (takes precedence over `supported`/ `notSupported`) + +## [Onboarding Options](https://docs.sentry.io/contributing/pages/components/\#onboarding-options) + +If you're writing product feature specific docs, you can specify code block `onboardingOptions` metadata: + +Markdown + +`` + +````markdown code-highlight +```go {"onboardingOptions": {"performance": "13-17"}} +// your code here +``` + +```` + +the general syntax is `{"onboardingOptions": {"feature": "range"}}` where `feature` is the feature id and `range` is the corresponding line range (similar to the line highlighting syntax). + +You can specify multiple features by separating them with a comma: + +`{"onboardingOptions": {"performance": "13-17", "profiling": "5-6"}}` + +The range visibility will be controlled by the `OnboardingOptionButtons` component: + +JSX + +`` + +```code-highlight jsx code-diff +<OnboardingOptionButtons + options={["error-monitoring", "profiling", "performance"]} +/> + +``` + +- `options` can either be either an object of this shape: + +TypeScript + +`` + +```code-highlight typescript +{ + id: 'error-monitoring' | 'performance' | 'profiling' | 'session-replay', + disabled: boolean, + checked: boolean +} + +``` + +or a string (one of these `id` s 👆) for convenience when using defaults. + +##### Important + +The underlying implementation relies on the `onboardingOptions` metadata in the code blocks to be valid JSON syntax. + +- default values: `checked: false` and `disabled: false` ( `true` for `error-monitoring`). + +Example (output of the above): + +Error MonitoringTracingProfiling + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//contributing/pages/components/). + +Go + +`` + +```code-highlight go +import ( + "fmt" + "net/http" + + "github.com/getsentry/sentry-go" + sentrygin "github.com/getsentry/sentry-go/gin" + "github.com/gin-gonic/gin" +) + +// To initialize Sentry's handler, you need to initialize Sentry itself beforehand +if err := sentry.Init(sentry.ClientOptions{ + Dsn: "https://examplePublicKey@o0.ingest.sentry.io/0", + EnableTracing: true, + // Set TracesSampleRate to 1.0 to capture 100% + // of transactions for performance monitoring. + // We recommend adjusting this value in production, + TracesSampleRate: 1.0, +}); err != nil { + fmt.Printf("Sentry initialization failed: %v\n", err) +} + +// Then create your app +app := gin.Default() + +// Once it's done, you can attach the handler as one of your middleware +app.Use(sentrygin.New(sentrygin.Options{})) + +// Set up routes +app.GET("/", func(ctx *gin.Context) { + ctx.String(http.StatusOK, "Hello world!") +}) + +// And run it +app.Run(":3000") + +``` + +You can conditionally render content based on the selected onboarding options using the `OnboardingOption` component + +Or you can use the `hideForThisOption` prop to hide the content for the selected option. + +Markdown + +`` + +````markdown code-highlight +```jsx +<OnboardingOption optionId="profiling" hideForThisOption> +Hide this section for `profiling` option. +</OnboardingOption> +``` + +```` + +Example: + +- toggle the `performance` option above to see the effect: + +JSX + +`` + +```code-highlight jsx +<OnboardingOption optionId="performance"> + This code block is wrapped in a `OnboardingOption` component and will + only be rendered when the `performance` option is selected. +</OnboardingOption>; + +``` + +- toggle the `profiling` option above to see the effect: + +JSX + +`` + +```code-highlight jsx +<OnboardingOption optionId="profiling" hideForThisOption> + This code block is wrapped in a `OnboardingOption` component and will + only be rendered when the `profiling` option is NOT selected. +</OnboardingOption>; + +``` + + +[Previous\\ +\\ +Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams) + +[Next\\ +\\ +Markdown Variables](https://docs.sentry.io/contributing/pages/variables) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/components.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Saved Searches](https://docs.sentry.io/concepts/search/saved-searches/) + +# Saved Searches + +## Learn more about default, recommended, and saved searches. + +Saved Searches has been deprecated and will be removed soon. Your saved searches will still be available in the "Add View" menu on the **Issues** page. Any saved search can be converted to an Issue View. + +Sentry allows you to save searches you've made on the **Issues** page. At the top of the page, next to the search bar, click "Custom Search" to access the "Saved Searches" sidebar. + +[![UI walkthrough of the Saved Searches feature.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaved-searches-PE2VA6OM.gif%23800x391&w=1920&q=75)](https://docs.sentry.io/mdx-images/saved-searches-PE2VA6OM.gif) + +## [Recommended Searches](https://docs.sentry.io/concepts/search/saved-searches/\#recommended-searches) + +Recommended searches are common search terms that we think you're likely to use. These premade searches are listed under "Recommended Searches" in the "Saved Searches" sidebar. + +[![Recommended searches section in the saved searches sidebar.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsearch-recommended-QHFYWJYQ.png%23337x220&w=750&q=75)](https://docs.sentry.io/mdx-images/search-recommended-QHFYWJYQ.png) + +## [Custom Saved Searches](https://docs.sentry.io/concepts/search/saved-searches/\#custom-saved-searches) + +Organization users in all roles can create their own saved searches. These searches are only visible to the person who created them and apply to all their projects. If you're an organization owner or manager, you have the option to make your saved searches visible only to yourself or to your entire organization. Organization-wide saved searches are not associated with a specific project, but with all projects across the organization. + +1. In the "Saved Searches" sidebar, click "Add saved search" to create a new custom search. + +2. In the modal that opens, name the search and set your query filters and sort order. If you're an organization owner or manager, you'll also have the option to make the search visible to all users in your organization. Then click "Save". + +3. The new search will be added to the "Saved Searches" sidebar. Click the name of the search to apply it. + + +[![UI walkthrough of the Custom Saved Searches feature.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcustom-saved-searches-3W6JBFST.gif%23800x391&w=1920&q=75)](https://docs.sentry.io/mdx-images/custom-saved-searches-3W6JBFST.gif) + +## [Edit or Delete a Saved Search](https://docs.sentry.io/concepts/search/saved-searches/\#edit-or-delete-a-saved-search) + +You can edit or delete any of your personal saved searches, as well as organization-wide searches if you're an organization owner or manager. To do so, hover over the search in the sidebar and click the more options icon ("...") to access the "Edit" and "Delete" buttons. + +[![A saved search with an open overflow menu with edit and delete options](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsearch-saved-search-edit-delete-5EADMAF4.png%23335x239&w=750&q=75)](https://docs.sentry.io/mdx-images/search-saved-search-edit-delete-5EADMAF4.png) + +## [Set a Default Search](https://docs.sentry.io/concepts/search/saved-searches/\#set-a-default-search) + +You can set a search query as the default view you see on the **Issues** page. The default search is only visible to you and is applied across your projects. + +1. Enter search terms into the search bar, or select a saved search from the sidebar. + +2. Click the "Set as Default" button located in the header. + +[![Cursor mousing over the "Set as Default" button.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fset_default_search-RSGUJYJJ.png%232159x368&w=3840&q=75)](https://docs.sentry.io/mdx-images/set_default_search-RSGUJYJJ.png) + + +Once defaulted, Sentry will name the search "My Default Search" and return to it whenever you navigate to the **Issues** page. + +[![Issues page with a default search set.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmy_default_search-X2PKX2W4.png%232135x370&w=3840&q=75)](https://docs.sentry.io/mdx-images/my_default_search-X2PKX2W4.png) + +[Previous\\ +\\ +Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) + +[Next\\ +\\ +Data Management](https://docs.sentry.io/concepts/data-management) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/saved-searches.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/) + +# How to Write - Performance + +The Performance section of the content covers performance instrumentation for our SDKs. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/performance` \- feel free to peruse the files in that directory to help answer any questions. + +Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions or suggestions. + +## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#start-here) + +Determine if the page applies: + +- If the content **does not apply**, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. +- If the content **does apply**, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting that customers open an issue for the missing sample. + +### [Set Up](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#set-up) + +The set up page is where readers may start, though the note at the beginning directs into the instrumentation content, if applicable. The reader path depends on whether the SDK has already been instrumented for performance monitoring in the refreshed Getting Started page. For folks adopting this feature later, this page covers how to set up. + +We expect this content to apply to all SDKS, as supported. + +This file is `index.mdx`. It explains how to install or set up (if appropriate) as well as how to enable tracing. + +To develop content for this file: + +1. If the guide is still a work-in-progress and is exposed as an experimental or an early access feature, add the platform to the `<PlatformSection>` wrapping the appropriate alert located at the beginning of the content for the page. + +2. If the guide is expected to be used in a high-throughput environment, add the platform to the following `<PlatformSection>` which advises testing before deploying to production. + +3. If automatic instrumentation is still in preview/beta for the guide, add your platform to the next `<PlatformSection>` that wraps around text that discusses this. + +4. If automatic instrumentation is supported, add your platform to the `<PlatformSection>` immediately following **Verify** which advises users to either use auto or custom (or manual) instrumentation to verify the feature. Either omit the platform from the `supported` list or add the platform to the `notSupported` list if auto instrumentation is not available. + +5. Add a code sample to `/src/platform-includes/performance/configure-sample-rate/` that covers how to set sample rates. Make sure to update `/docs/platforms/<SDK>/common/configuration/sampling.mdx` and **Tracing Options** in `/docs/platforms/<SDK>/common/configuration/options.mdx`. + +6. Do one of the following based on whether automatic instrumentation is available for the guide or not: a. If automatic instrumentation is supported, add your platform to the `<PlatformSection>` immediately following **Verify** which advises users to either use auto or custom (a.k.a. manual) instrumentation to verify the feature. Either omit the platform from `supported` or the platform to `notSupported`. + +b. If automatic instrumentation is not supported, add your platform to the second `<PlatformSection>` after **Verify** which advises users to test out tracing using custom (manual) instrumentation. Omit the platform from the `supported` list or add it to the `notSupported` list if automatic instrumentation is available. + +7. Determine if the paragraph regarding pageload and navigation applies to the guide. If so, add the guide to the `Supported` list in the `<PlatformSection>`. If not, either omit the guide from the `supported` list or add the guide to the `notSupported` list, which will prevent the content from displaying for this guide. + + +### [Custom Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#custom-instrumentation) + +We expect this content to apply to all SDKS. + +This file is `performance/instrumentation/custom-instrumentation.mdx`. It explains how to manually instrument transactions. + +If custom instrumentation for the framework is exposed as an experimental or an early access feature, add the guide to the `<PlatformSection>` wrapping the appropriate alert located at the beginning of the content for the page. + +To develop content for this file, add code samples to these directories: + +- `/src/platform-includes/performance/enable-manual-instrumentation/` +- `/src/platform-includes/performance/add-spans-example/` +- `/src/platform-includes/performance/retrieve-transaction/` + +If any of the above files are not applicable to your framework, find the `<PlatformSection>` wrapping the `<PlatformContent>` pointing to the unsupported file, and add your guide to its `notSupported` list. If such a `<PlatformSection>` doesn't already exist, create one and add your guide to its `notSupported` list. + +Then, determine whether to provide a code sample illustrating how to connect errors and spans. If so, add the SDK to the `Supported` list in the appropriate `<PlatformSection>`, then add a code sample `/src/platform-includes/performance/connect-errors-spans/`. + +### [Automatic Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#automatic-instrumentation) + +Populate the `sdk_name/common/performance/instrumentation/` directory with the file `automatic-instrumentation.mdx`. + +### [Troubleshooting](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#troubleshooting) + +This file is `troubleshooting-performance.mdx`. It explains corner cases and how to solve known issues. + +1. Determine if the framework needs an illustration of how to group transactions. If so, add the framework to `Supported` list in the `<PlatformSection>`, then add a code sample to `performance/group-transaction-example/`. If not, add the framework to `notSupported` list, which will prevent the **Group Transactions** heading from displaying for this framework. + +2. Add an example to `src/platform-includes/performance/control-data-truncation/` + + +### [Sampling](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#sampling) + +Guidelines TBD. + +[Previous\\ +\\ +How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management) + +[Next\\ +\\ +How to Write - Usage](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-performance.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates/) + +# Sample Rates + +## Learn how to manage the amount of data you send and are billed for in Sentry by adjusting the sample rates of various Sentry products including Traces and Session Replays. + +## [Overview](https://docs.sentry.io/concepts/key-terms/sample-rates/\#overview) + +### [What Is a Sample Rate?](https://docs.sentry.io/concepts/key-terms/sample-rates/\#what-is-a-sample-rate) + +Adding Sentry to your app gives you a lot of valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. You can use sample rates to capture only a specified percentage of events like errors and traces. + +### [Why Not Capture All Events?](https://docs.sentry.io/concepts/key-terms/sample-rates/\#why-not-capture-all-events) + +We recommend sampling your transactions for two reasons: + +1. Capturing a single trace involves minimal overhead, but capturing traces for every page load or API request may add an undesirable load to your system. + +2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs and budget. + + +Choose a sampling rate that balances data accuracy with performance and storage concerns. You should aim to collect enough data to get meaningful insights without overloading resources. If unsure, start with a low rate and gradually increase it as you understand your traffic patterns better. + +## [Sampling Rate Options](https://docs.sentry.io/concepts/key-terms/sample-rates/\#sampling-rate-options) + +Some of the options below aren't available in every SDK; check out our platform-specific docs for more info. + +### [Error Events](https://docs.sentry.io/concepts/key-terms/sample-rates/\#error-events) + +- **SampleRate** \- Configures the sample rate for error events, in the range of 0.0 to 1.0. The default is 1.0, which means that 100% of error events will be sent. If set to 0.1, only 10% of error events will be sent. Events are picked randomly. + +### [Tracing](https://docs.sentry.io/concepts/key-terms/sample-rates/\#tracing) + +- **tracesSampleRate** \- A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. ( `0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. Either this or `tracesSampler` must be defined to enable tracing. + +- **tracesSampler** \- A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between 0 (0% chance of being sent) and 1 (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or `tracesSampleRate` must be defined to enable tracing. + + +Learn more about [tracing](https://docs.sentry.io/product/tracing/) in Sentry. + +### [Session Replay](https://docs.sentry.io/concepts/key-terms/sample-rates/\#session-replay) + +- **replaysSessionSampleRate** \- The sample rate for replays that begin recording immediately and last the entirety of the user's session. 1.0 collects all replays, and 0 collects none. + +- **replaysOnErrorSampleRate** \- The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends. 1.0 captures all sessions with an error, and 0 captures none. + + +Learn more about [session replay](https://docs.sentry.io/product/explore/session-replay/) in Sentry. + +[Previous\\ +\\ +Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer) + +[Next\\ +\\ +Environments](https://docs.sentry.io/concepts/key-terms/environments) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/sample-rates.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) +- [Custom SAML Provider](https://docs.sentry.io/organization/authentication/sso/saml2/) + +# Custom SAML Provider + +## Learn about how to integrate the Custom SAML Provider. + +This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. + +Sentry provides a generic auth provider for [SAML2 based authentication](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language), which allows Owners of a Sentry organization to manually configure any SAML2-enabled IdP system. Documented below are the general steps for integration. + +# [Setup](https://docs.sentry.io/organization/authentication/sso/saml2/\#setup) + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. + +Sentry supports the following SAML services: + +- Identity and Service Provider initiated SSO +- Identity Provider initiated SLO (Single Logout) + +## [Register Sentry with IdP](https://docs.sentry.io/organization/authentication/sso/saml2/\#register-sentry-with-idp) + +Before connecting Sentry to the Identity Provider (IdP), it’s important to first register Sentry as an application on the IdP’s side. Sentry’s SAML endpoints are as follows, where `YOUR_ORG_SLUG` is substituted for your organization slug: + +| ACS: | `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` | +| SLS: | `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` | +| Metadata: | `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` | + +**What are these three things?** + +- `ACS` means _Assertion Consumer Service_. It is used for establishing a session based on rules made between your IdP and the service provider with which it is integrating. Please note that Sentry’s ACS endpoint uses HTTP-POST bindings. +- `SLS` stands for _Single Logout Service_, and is used to address logout requests from the IdP. +- `Metadata`, alternatively referred to as the `entityID` in some systems, refers to the configuration data for an IdP or an SP. In this case, the metadata endpoint in Sentry refers to your Sentry organization’s metadata on the Service Provider end. + +When setting these values up on the IdP end, it’s important to remember that Sentry does not need to provide a signing certificate for the integration to work. + +## [Register IdP with Sentry](https://docs.sentry.io/organization/authentication/sso/saml2/\#register-idp-with-sentry) + +There are three distinct methods for registering your IdP with Sentry: Metadata, XML, and data fields. Each method is broken down below, and will produce the same end result. + +### [Using Metadata URL](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-metadata-url) + +This method only requires a Metadata URL provided by the IdP platform. After it has been supplied, Sentry will automatically fetch the metadata it needs. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-metadata-url-T7USEQX5.png%231372x672&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-metadata-url-T7USEQX5.png) + +### [Using Provider XML](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-provider-xml) + +For this method to work, an administrator needs to provide the contents of the IdP’s generated metadata file. Once the contents are pasted directly into the text field, Sentry will do the rest. Please note that Sentry does not require a signing certificate. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-provider-xml-IMRZOZ22.png%231366x894&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-provider-xml-IMRZOZ22.png) + +Here’s an example of what the Metadata XML contents look like. + +Xml + +`` + +```xml code-highlight +<?xml version="1.0" encoding="UTF-8" ?> +<md:EntityDescriptor + xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" + entityID="http://www.okta.com/SENTRY_APP_ID" +> + <md:IDPSSODescriptor + WantAuthnRequestsSigned="false" + protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" + > + <md:KeyDescriptor use="signing"> + <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> + <ds:X509Data> + <ds:X509Certificate>...</ds:X509Certificate> + </ds:X509Data> + </ds:KeyInfo> + </md:KeyDescriptor> + <md:NameIDFormat + >urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> + <md:NameIDFormat + >urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> + <md:SingleSignOnService + Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" + Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" + /> + <md:SingleSignOnService + Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" + Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" + /> + </md:IDPSSODescriptor> +</md:EntityDescriptor> + +``` + +### [Using Provider Data](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-provider-data) + +This registration method is the most involved, and requires matching up the data fields from an IdP. The easiest way to accomplish this is to look for the values in a metadata file such as the one provided above. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-provider-data-ODNIXIX2.png%231356x1374&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-provider-data-ODNIXIX2.png) + +Based on the XML file example above, the field values to plug in are as follows: + +- `EntityID` +- `X509Certificate` +- `SingleSignOnService` + +In this example, the `SingleLogoutService` isn’t provided by the IdP, and is treated as an optional value within Sentry. + +## [Map IdP Attributes](https://docs.sentry.io/organization/authentication/sso/saml2/\#map-idp-attributes) + +##### Note on field names + +Metadata field names can vary from one provider to another. For example, Microsoft Azure AD refers to these very metadata fields as **Claims**, while Okta refers to them as **Attributes**. Similarly, one platform might use **user.email**, while another vendor uses **emailaddress**. + +Here, the field values of Sentry members need to be matched up with the corresponding values for members in the IdP. The basic required fields are the IdP's User ID and email address, but Sentry can also optionally pull first and last name values from there as well. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-map-attributes-WT26H7MA.png%23687x652&w=1920&q=75)](https://docs.sentry.io/mdx-images/saml2-map-attributes-WT26H7MA.png) + +## [Confirm successful registration](https://docs.sentry.io/organization/authentication/sso/saml2/\#confirm-successful-registration) + +Once the SAML integration flow is complete, the related Auth page will reflect the status of a successful integration. From here, you can send reminders to any existing members who existed prior to the integration, and they will receive an email prompt to link their accounts. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-success-JNXCPXPG.png%231600x742&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-success-JNXCPXPG.png) + +Because Sentry uses Just-In-Time (JIT) provisioning, new members are registered with Sentry automatically during their first login attempt with SAML SSO. These accounts will have their membership types delegated based on what the default membership role is in your Organization Settings in Sentry. + +## [SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/saml2/\#scim-provisioning) + +SCIM is available for automatic user provisioning, deprovisioning, and team assignment for SAML2 IdPs. [Configure Sentry for SCIM](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/#sentry-configuration), and then follow your IdP's documentation for further setup. Learn more about the Sentry SCIM API endpoints in the [SCIM API documentation](https://docs.sentry.io/api/scim/). + +## [FAQ](https://docs.sentry.io/organization/authentication/sso/saml2/\#faq) + +#### [What is the process for adding new members to a SAML2-enabled Sentry organization?](https://docs.sentry.io/organization/authentication/sso/saml2/\#what-is-the-process-for-adding-new-members-to-a-saml2-enabled-sentry-organization) + +Sentry makes use of Just-In-Time provisioning for member accounts; any new member created within an Identity Provider will have an account automatically created in Sentry when that member attempts to sign into Sentry for the first time. + +#### [What happens to Sentry accounts that exist prior to SAML being enabled/enforced?](https://docs.sentry.io/organization/authentication/sso/saml2/\#what-happens-to-sentry-accounts-that-exist-prior-to-saml-being-enabledenforced) + +Existing members will receive an email notifying them of the new SAML authentication option once it is turned on (regardless of enforcement) and they'll be able to link the accounts in the IdP system with their Sentry memberships. + +#### [Does Sentry deprovision members if they are no longer present in the Identity Provider?](https://docs.sentry.io/organization/authentication/sso/saml2/\#does-sentry-deprovision-members-if-they-are-no-longer-present-in-the-identity-provider) + +At this time, Sentry's SAML2 integration does not automatically deprovision inactive user accounts. Instead, the member remains inside of Sentry without any means to log in, as they can no longer access the IdP platform for sign-on. For now, inactive member accounts will need to be removed manually by a Manager or an Owner in Sentry. + +#### [Attempting to set up SAML2 SSO with an IdP results in a failure with the message “The provider did not return a valid user identity.” What is happening here?](https://docs.sentry.io/organization/authentication/sso/saml2/\#attempting-to-set-up-saml2-sso-with-an-idp-results-in-a-failure-with-the-message-the-provider-did-not-return-a-valid-user-identity-what-is-happening-here) + +The crux of the problem here is that different IdP platforms (Okta, Azure AD, etc) use different terms and conventions for the fields necessary for the integration to work. As a result, it’s possible to map up incorrect values into Sentry, causing SSO to fail with this error message. + +[Previous\\ +\\ +Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso) + +[Next\\ +\\ +Two-Factor Authentication (2FA)](https://docs.sentry.io/organization/authentication/two-factor-authentication) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/saml2.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) +- [Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/) + +# Google Cloud Run + +## Learn more about how you can use Sentry with your Google Cloud Run applications. + +Cloud Run helps developers save time in building and deploying their applications. Sentry helps save time in resolving production issues by providing detailed debugging capabilities. + +## [Install and Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/\#install-and-configure) + +Sentry owner, manager, or admin permissions are required to install this integration. + +1. [Create an account](https://sentry.io/signup/) (or [Login](https://sentry.io/auth/login/)) on Sentry + +2. Choose your application platform + +[![Sentry Choose Platform](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-choose-platform-6HFWB2RY.png%231195x400&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-choose-platform-6HFWB2RY.png) + +3. Follow instructions to instrument your Cloud Run application. Detailed platform docs [here](https://docs.sentry.io/platforms/). + +4. Deploy your Cloud Run application with GCP. + + +[Previous\\ +\\ +Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers) + +[Next\\ +\\ +Troubleshooting Integrations](https://docs.sentry.io/organization/integrations/troubleshooting) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/gcp-cloud-run/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) + +# Data Management + +## Learn more about managing data using the Settings for your project and organization. Server-side data management options include issue grouping, data forwarding, and inbound filters. + +Please refer to [the SDK documentation for a general introduction to managing sensitive data](https://docs.sentry.io/platform-redirect/?next=%2Fdata-management%2Fsensitive-data%2F). This page documents only the server-side options. + +[Previous\\ +\\ +Search](https://docs.sentry.io/concepts/search) + +[Next\\ +\\ +Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) + +# SDK Documentation Structure + +Our structure for SDK content focuses on getting a user up and running quickly, then learning about all the features that can be configured or enabled in subpages. These subpages provide reference material, with code examples specific to the SDK. + +## [Content Sections](https://docs.sentry.io/contributing/approach/sdk-docs/\#content-sections) + +SDKs provide content that focus on 10 sections (two of which are auto-generated) that rely on common content. Each section is explained in detail on its own page. A quick overview: + +1. **Getting Started** + +A single, critical page. + +**[How to Write - Getting Started](https://docs.sentry.io/contributing/approach/write-getting-started/)** + +This content is used in two different areas for Sentry customers: + +1. [docs.sentry.io](https://docs.sentry.io/) +2. In-app wizard for customers creating or adding a project + +2. **Configuration** + +Covers all the ways customers can manage their implementation of the SDK. It consists of subpages (all of which can be turned on or off, as appropriate to the SDK). + +**[How to Update: Configuration](https://docs.sentry.io/contributing/approach/write-configuration/)** + +3. **Usage** + +Covers how to capture errors and messages, with a subpage to set the Level. + +**[How to Update: Usage](https://docs.sentry.io/contributing/approach/write-usage/)** + +4. **Troubleshooting** + +Covers corner and edge cases we know of. This content is developed at the primary SDK level, so is shared by the primary SDK and its associated guides. It is not common to all SDKs/platforms. + +The content resides in this directory `/docs/platforms/<SDK>/common/troubleshooting/` + +5. (Optional) **Migration Guide** + +Provided for customers who need to upgrade from the Raven version of the SDK. Not needed for newer SDKs. + +6. **Tracing** section + +Covers how to enable tracing (for customers who previously only used error monitoring) as enabled by each SDK, as well as subpages on Sampling and Transactions. + +_This section is a WIP._ + +7. **Enriching Events** section + +Covers the data sent to Sentry, as well as how to customize it. + +**[How to Update: Enriching Events](https://docs.sentry.io/contributing/approach/write-enriching-events/)** + +8. **Data Management** section + +Covers our algorithm for grouping and how it can be modified, as well as how to scrub sensitive data using the SDK. + +**[How to Update: Data Management](https://docs.sentry.io/contributing/approach/write-data-management/)** + +9. (Auto-generated) **Other Guides** + +Lists the other related platforms/integrations/SDKs for this SDK. + +10. (Auto-generated) **Other Platforms** + +Lists the other primary SDK/platforms. + + +This model is quite flexible - some SDKs will incorporate more information- others will require less information. + +We have several goals to using this format: + +- Ensure customers have a single page that gets them started quickly. +- Update the SDK content so that it is both **technically accurate** and **complete**. +- Ensure we've architected to support the structure of our docs, which separates Platform/SDK content from Product content. Think of this as "Platform/SDK docs help a customer send data to Sentry" and "Product docs help a customer understand what's in [sentry.io](http://sentry.io/), then determine an appropriate response" + +## [Where to Start](https://docs.sentry.io/contributing/approach/sdk-docs/\#where-to-start) + +1. Read the [contributor guidelines](https://docs.sentry.io/contributing/). The guidelines will help you set up your docs environment (the move to our new tooling is significant) and provide key technical details about SDK content, search, redirects, and the Wizard pages. If you need help, ask for help by opening an issue in GitHub. +2. Use the "How to" pages to understand what content is covered where. +3. Use the files and folder structure in JavaScript as a model. +4. Create a PR and please request getsentry/docs as reviewers. + +## [What Not To Do](https://docs.sentry.io/contributing/approach/sdk-docs/\#what-not-to-do) + +- Wonder and ponder. The model is not meant to work 100% of the time. It's anticipated that some of the content won't work neatly. If you're not sure where content should display, ask a question by opening an issue in GitHub. +- Don't forget to update the Wizard Pages that use the Getting Started content to help direct customers on sentry.io +- Don't forget to update the listing of SDKs that support performance monitoring, as appropriate. + +## [SDK Documentation Guides](https://docs.sentry.io/contributing/approach/sdk-docs/\#sdk-documentation-guides) + +[Previous\\ +\\ +Our Approach](https://docs.sentry.io/contributing/approach) + +[Next\\ +\\ +Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/) + +# How to Write - Enriching Events + +The Enriching Events section of the content covers how customers can add context to the data sent to Sentry. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/enriching-events` \- feel free to peruse the files in that directory to answer any questions. + +Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. + +Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions by opening an issue on GitHub. + +## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#start-here) + +Determine if the page applies: + +- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. +- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting customers open an issue for the missing sample. +- The JS family of content needs to import the SDK for the code samples to make sense on each page. Add the import statement to `/src/platform-includes/enriching-events/enriching-events/import`. + +### [Add Context](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#add-context) + +This file is `context.mdx`. It explains how to enable custom contexts. Add the code sample to this directory: + +- `/src/platform-includes/enriching-events/set-context/` + +If the guide can pass context directly, add it to the list of supported guides immediately above "Passing Context Directly". + +### [Identify Users](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#identify-users) + +This file is `identify-user.mdx`. It explains how to capture the user. Add the code samples to these directories: + +- `/src/platform-includes/enriching-events/set-user/` +- `/src/platform-includes/enriching-events/unset-user/` + +### [Set Transaction Name](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#set-transaction-name) + +This file is `transaction-name.mdx`. It explains how to override the transaction name. Add the code sample to this directory: + +- `/src/platform-includes/enriching-events/set-transaction-name/` + +If the guide can control the starting and stopping of transactions, add it to the list of supported guides that refers customers to our tracing docs. + +### [Customize Tags](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#customize-tags) + +This file is `tags.mdx`. It explains how to customize tags for an event. Add the code sample to this directory: + +- `/src/platform-includes/enriching-events/set-tag/` + +If the guide doesn't bind tags to the current scope, add it to the list of guides that don't support this option. + +### [Attachments](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#attachments) + +This file is `/attachments/index.mdx`. It explains attaching files along with the event. Add the code sample to this directory: + +- `/src/platform-includes/enriching-events/add-attachment/` + +If the guide is part of the native family, add it to the list of guides that support the native content regarding: + +- Debug information files and built-in support for native crashes +- Large crash reports +- The section on "Crash Reports and Privacy" +- The paragraph regarding limiting crash reports per issue + +This file is `breadcrumbs.mdx`. It explains manual breadcrumbs. Add the code sample to manually add record a breadcrumb to this directory: + +- `/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/` +- `/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/` + +One nuance: + +- Update, as appropriate, the supported guide list in the `PlatformSection supported` that precedes "The available breadcrumb keys..." + +### [User Feedback](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#user-feedback) + +This file is `user-feedback.mdx`. It explains how to use the embeddable JS widget or the API. + +- Update, as appropriate, the supported SDK list in the `PlatformSection supported` that precedes "User Feedback API". Then add the code sample to the `src/platform-includes/user-feedback/sdk-api-example` directory +- For the .NET family, if the User Feedback API has a specific integration, add it to the `PlatformSection supported` that precedes the "Use the .NET SDK", and add the appropriate link. +- Update, as appropriate, the SDKs that don't support the JS widget in the listed `PlatformSection notSupported` that precedes "Embeddeable JavaScript Widget". +- For the SDKs that use the JS widget, add the code sample to `/src/platform-includes/user-feedback/user-feedback-example-widget/` + +### [Scopes](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#scopes) + +This file is `scopes.mdx`. It explains managing scopes. Add the code samples to these directories: + +- `/src/platform-includes/enriching-events/scopes/configure-scope/` +- `/src/platform-includes/enriching-events/unset-user/` +- `/src/platform-includes/enriching-events/scopes/with-scope/` + +[Previous\\ +\\ +How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration) + +[Next\\ +\\ +How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-enriching-events.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Moving to SaaS](https://docs.sentry.io/concepts/migration/) + +# Moving to SaaS + +## Learn more about the reasons to move to Sentry's SaaS solution, which for many customers is less expensive to maintain, and easier to scale and support. + +Sentry offers a cloud-hosted, software-as-a-service (SaaS) solution in addition to a self-hosted solution, which are both functionally the same. However, many customers find that self-hosted Sentry can quickly become expensive to maintain, scale, and support, making our SaaS product the better and less costly option. To facilitate moving from self-hosted to SaaS, we provide a self-serve process known as "relocation". + +Check out this video on [**Migrating to Sentry SaaS**](https://sentry.io/resources/migrate-to-sentry-saas-workshop/) to learn about our relocation tooling. + +For additional reading on considering SaaS, take a look at: + +- [Self Hosted or Cloud Sentry?](https://sentry.io/_/resources/about-sentry/self-hosted-vs-cloud/) +- [XS:Code > Open Source is Free - But Expensive](https://dev.to/helad11/open-source-is-free-but-expensive-3h8a) +- [Frequently asked migration questions](https://sentry.io/from/self-hosted/) + +## [Relocating to Cloud](https://docs.sentry.io/concepts/migration/\#relocating-to-cloud) + +If your organization started with self-hosted Sentry, you've invested time and effort in configuring and customizing your Sentry org. Your work won't be wasted if you decide to move to a SaaS account because you won't have to start from scratch. You'll be able to relocate a lot of what you've configured into your new account. + +To make this relocation as seamless as possible, Sentry has a workflow that allows you to retain most of your account's settings and configurations as you move to SaaS. All you'll need is owner access to your self-hosted install, and a way to access it via the terminal. + +### [What you'll keep](https://docs.sentry.io/concepts/migration/\#what-youll-keep) + +All of the configurations, team and project structure, and most metadata will be relocated. Specifically, for every organization you [choose to relocate](https://docs.sentry.io/concepts/migration/#2-choose-which-organizations-to-relocate) this includes: + +- All organization settings +- User accounts and options for all organization members +- Projects and their settings +- Teams and their settings +- Alert rules +- Crons +- Dashboards +- Enabled data scrubbers +- Repositories +- Recent and saved searches + +### [What gets left behind](https://docs.sentry.io/concepts/migration/\#what-gets-left-behind) + +Any data related to specific issues, events, stack traces, or files like replays and source maps won't be transferred. Additionally, for security reasons, you'll need to reconnect and re-authenticate all of your integrations, and your users will need to re-connect their 2FA and create new API tokens after relocating. + +Below is a non-exhaustive list of some items that will not be relocated: + +- Integrations, including parts of relocated items that depend on them (ex: if an Alert Rule triggers Slack notifications, that trigger will be omitted) +- Webhooks +- Issues +- Events +- Replays and/or other [Event Attachments](https://docs.sentry.io/platforms/javascript/enriching-events/attachments/) +- Source Maps, [Debug Information Files](https://docs.sentry.io/cli/dif/) and/or [Artifact Bundles](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) +- Release information, including any references to external repositories via specific Pull Requests +- Deployment information +- Custom Avatars + +One thing to note is that while we won't be able to transfer over historical event data, new incoming events will populate the projects in your relocated organization as soon as you [update your DSNs](https://docs.sentry.io/concepts/migration/#5-update-your-dsns). All relocated organization members will be automatically notified and re-invited via email once the relocation completes. + +### [Version support window](https://docs.sentry.io/concepts/migration/\#version-support-window) + +Self-serve relocation is only possible from the two most up-to-date minor self-hosted releases. That is, if the latest self-hosted release is version 24.2.3, your self-hosted install must be on at least version 24.1.0 to be successfully relocated. + +If you'd like to relocate from an earlier release, we ask that you [update](https://develop.sentry.dev/self-hosted/releases/) your self-hosted install to the latest version first. If there is some reason that this is not possible, please [contact support](https://sentry.io/contact/enterprise/) for more guidance. + +### [Data security](https://docs.sentry.io/concepts/migration/\#data-security) + +Your data will be encrypted end-to-end during the relocation process. The only file that will pass over the network will be an encrypted tarball that we'll never store in plaintext, and will delete within 30 days of the start of your relocation. + +## [How to Relocate](https://docs.sentry.io/concepts/migration/\#how-to-relocate) + +### [1\. Sign up with a promo code](https://docs.sentry.io/concepts/migration/\#1-sign-up-with-a-promo-code) + +Before you begin the relocation process, [sign up](https://sentry.io/signup/relocate/) for a new account on Sentry. If you already have a Sentry account, login and navigate to the [relocation landing page](https://sentry.io/relocation/). In either case, you should see a page like this: + +[![Relocation getting started page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frelocation-landing-page-UPZS4K4S.png%231122x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/relocation-landing-page-UPZS4K4S.png) + +**To receive a $100 credit, make sure to use the promo code `relocate100` on this page.** + +### [2\. Choose which organizations to relocate](https://docs.sentry.io/concepts/migration/\#2-choose-which-organizations-to-relocate) + +Your self-hosted installation may have multiple organizations, each identified by a unique slug. You'll need to decide which org slugs to keep. You can always change them post-relocation by going to the **Organization Settings** page. + +[![Changing the org slug on the settings page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-slug-B74S4C2M.png%231484x485&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-slug-B74S4C2M.png) + +### [3\. Follow the in-app relocation instructions](https://docs.sentry.io/concepts/migration/\#3-follow-the-in-app-relocation-instructions) + +The rest of the in-app relocation instructions will walk you through the specific details of how to export your self-hosted instance's relocatable data. This will require terminal access to the machine running your self-hosted instance. Here's a quick overview: + +- You'll be asked to save a public key that we generate on the SaaS backend to your self-hosted machine +- You'll then use this key to execute a command which will generate an encrypted tarball with all your data +- Lastly, you'll be prompted to upload this tarball + +Most relocations complete in under an hour, though certain large or complex cases can take a bit longer. If you don't get an update from us within 24 hours, please [contact support](https://sentry.io/contact/enterprise/) for further assistance. + +### [4\. Choose a plan](https://docs.sentry.io/concepts/migration/\#4-choose-a-plan) + +Once your relocation is complete, you can choose the [pricing plan](https://sentry.io/pricing/) that best suits your needs. Note that plan pricing varies based on your [Event Volume](https://docs.sentry.io/product/accounts/quotas/). + +If you're expecting higher volumes or you're interested in our Enterprise capabilities (priority support and SLAs, and single-tenant options, for example), please [contact us](https://sentry.io/contact/enterprise/) regarding our **Enterprise Plan**. + +### [5\. Update your DSNs](https://docs.sentry.io/concepts/migration/\#5-update-your-dsns) + +Though your project data has been fully relocated, the DSNs for all of your projects will have changed, as they are now located at [https://sentry.io](https://sentry.io/) rather than your prior self-hosted domain name. This means that you'll need to update the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) you use in each of your SDKs for each relevant project. Once you complete this step, you'll should start to see issues and events (though hopefully not too many!) appearing as before. + +[Previous\\ +\\ +Data Management](https://docs.sentry.io/concepts/data-management) + +[Next\\ +\\ +Contributing to Docs](https://docs.sentry.io/contributing) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/migration/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) +- [AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) +- [Lambda Layer Modifications](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/) + +# Lambda Layer Modifications + +## Understand how the Sentry AWS Lambda integration works under the hood. + +## [Node](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/\#node) + +When Sentry is added to a Lambda function, the following modifications are made to your Lambda functions: + +- The layer for Sentry is added to your Lambdas. Any existing layers are honored and the Sentry layer is appended to the end. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Flayer-EQWHRKHV.png%23978x192&w=2048&q=75)](https://docs.sentry.io/mdx-images/layer-EQWHRKHV.png) + +- Sentry adds the following environment variables + + + - `NODE_OPTIONS`: This is to preload the `awslambda-auto` module which will automatically initialize Sentry + - `SENTRY_DSN`: This is set to the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) of your project + - `SENTRY_TRACES_SAMPLE_RATE`: This sets the [sampling rate](https://docs.sentry.io/platforms/javascript/guides/node/configuration/sampling/#sampling-transaction-events) for transactions. You can manually edit your environment variables if you want a different sampling rate. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenv_variables-55VGYFH7.png%23846x269&w=1920&q=75)](https://docs.sentry.io/mdx-images/env_variables-55VGYFH7.png) + +## [Python](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/\#python) + +When Sentry is added to a Lambda function, the following modifications are made to your Lambda functions: + +- The layer for Sentry is added to your Lambdas. Any existing layers are honored and the Sentry layer is appended to the end. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Flayer_python-TKZ367LO.png%233102x680&w=3840&q=75)](https://docs.sentry.io/mdx-images/layer_python-TKZ367LO.png) + +And your Runtime handler will point to Sentry's handler that will initialize the SDK for you, and then call your Runtime handler to invoke your function + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fhandler_python-PYDDZUIW.png%233108x626&w=3840&q=75)](https://docs.sentry.io/mdx-images/handler_python-PYDDZUIW.png) + +- Sentry adds the following environment variables + + + - `SENTRY_INITIAL_HANDLER`: This stores the value of your Runtime handler. If you choose to disable the Sentry layer, this value will be used to set the Runtime handler. + - `SENTRY_DSN`: This is set to the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) of your project + - `SENTRY_TRACES_SAMPLE_RATE`: This sets the [sampling rate](https://docs.sentry.io/platforms/python/configuration/sampling/#sampling-transaction-events) for transactions. You can manually edit your environment variables if you want a different sampling rate. + +[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenv_variables_python-J3OPUPVZ.png%233190x1270&w=3840&q=75)](https://docs.sentry.io/mdx-images/env_variables_python-J3OPUPVZ.png) + +[Previous\\ +\\ +AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) + +[Next\\ +\\ +Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/aws-lambda/how-it-works.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features/) + +# Early Adopter Features + +## Learn which features are currently in the early adopter phase. + +If you’re interested in being an Early Adopter, you can turn your organization’s Early Adopter status on/off in **Settings > General Settings**. This will affect all users in your organization and can be turned back off just as easily. + +[![The Early Adopter toggle enabled in settings.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fearly-adopter-toggle-EWVOK5PQ.png%231484x364&w=3840&q=75)](https://docs.sentry.io/mdx-images/early-adopter-toggle-EWVOK5PQ.png) + +This page lists the features that you'll have access to when you opt-in as "Early Adopter". Note that features are sometimes released to early adopters in waves, so you may not see a feature immediately upon enabling the "Early Adopter" setting. + +Limitations: + +- This list does not include new features that aren't controlled by the "Early Adopter" setting, such as alphas, closed betas, or limited availability features that require manual opt-in. +- This list is not guaranteed to be 100% up-to-date, but it is monitored and updated frequently. + +## [Current Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features/\#current-early-adopter-features) + +- [Issue Views](https://docs.sentry.io/product/issues/issue-views/) +- [Issue Status](https://docs.sentry.io/product/issues/states-triage/) tags +- [Span Summary](https://docs.sentry.io/product/insights/overview/transaction-summary/#span-summary) +- [Dynamic Alerts](https://docs.sentry.io/product/alerts/create-alerts/metric-alert-config/#dynamic-alerts) +- [New Trace Explorer With Span Metrics](https://docs.sentry.io/product/explore/new-trace-explorer/) + +[Previous\\ +\\ +Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling) + +[Next\\ +\\ +Integrations](https://docs.sentry.io/organization/integrations) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/early-adopter-features/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) + +# Span Properties + +## Learn more about searchable span properties. + +Spans are the underlying data element captured in Sentry SDKs that together make up a trace. + +You can search by span properties in the following [Sentry](https://sentry.io/) pages: + +- [Traces](https://docs.sentry.io/product/explore/traces/) \- when searching for a trace containing spans with matching properties + +When you search for span properties within the **Traces** page, the search will return any trace that contains _one or more spans_ that match your span properties filter. + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the span search: + +### [`action`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#action) + +The type of span action, for example, `SELECT` for a SQL span or `POST` for an HTTP span. + +- **Type:** string + +### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#browsername) + +The name of the browser that generated the span. + +- **Type:** string + +### [`cache.hit`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#cachehit) + +Whether a cache read has hit or missed the queried cache key. Values are `'true'` or `'false'`. + +- **Type:** string + +### [`description`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#description) + +Parameterized and scrubbed description of the span. + +- **Type:** string + +### [`device.class`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#deviceclass) + +Device class is a synthesized field that's calculated by using device info found in context such as model (for iOS devices), and device specs like `processor_frequency` (for Android devices). + +- **Type:** string + +### [`domain`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#domain) + +General scope of the span’s action, for example, the tables involved in a `db` span or the host name in an `http` span. + +- **Type:** string + +### [`duration`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#duration) + +The total time taken by the span. + +- **Type:** duration + +### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#environment) + +Refers to your code deployment naming convention. For example, `development`, `testing`, `staging` and so on. [Learn more](https://docs.sentry.io/product/sentry-basics/environments/). In some pages of [Sentry](https://sentry.io/), you filter on environment using a dropdown. + +- **Type:** string + +### [`file_extension`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#file_extension) + +The file extension of a resource span. + +- **Type:** string + +### [`group`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#group) + +Unique hash of the span’s description. + +- **Type:** string + +### [`http.decoded_response_content_length`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpdecoded_response_content_length) + +The [decoded body size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/decodedBodySize) of the resource. + +- **Type:** string + +### [`http.response_content_length`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpresponse_content_length) + +The [encoded body size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/encodedBodySize) of the resource. + +- **Type:** string + +### [`http.response_transfer_size`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpresponse_transfer_size) + +The [total transfer size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/transferSize) of the resource. + +- **Type:** string + +### [`messaging.destination.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#messagingdestinationname) + +The queue name or topic that the message is written or published to. The consumer also reads from this queue. + +- **Type:** string + +### [`messaging.message.id`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#messagingmessageid) + +The unique ID of a message from the queue or messaging system. + +- **Type:** string + +### [`module`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#module) + +The Insights module that the span is associated with, for example, `cache`, `db`, `http`, and so on. + +- **Type:** string + +### [`op`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#op) + +The operation of the span, for example, `http.client`, `middleware`. + +- **Type:** string + +### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#osname) + +Name of the operating system. + +- **Type:** string + +### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#platform) + +Name of the platform. This defaults to `other` and is only a property for platforms from this list: `as3`, `c`, `cfml`, `cocoa`, `csharp`, `elixir`, `go`, `groovy`, `haskell`, `java`, `javascript`, `native`, `node`, `objc`, `other`, `perl`, `php`, `python`, `ruby` + +- **Type:** string + +### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#release) + +A release is a version of your code deployed to an environment. You can create a token that matches a release exactly, or pick the most recent release by using `release:latest`. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### [`resource.render_blocking_status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#resourcerender_blocking_status) + +The [render blocking status](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/renderBlockingStatus) of the resource. + +- **Type:** string + +### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#sdkname) + +Name of the Sentry SDK that sent the event. + +- **Type:** string + +### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#sdkversion) + +Version of the Sentry SDK that sent the event. + +- **Type:** string + +### [`self_time`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#self_time) + +The duration of the span excluding the duration of its child spans. + +- **Type:** string + +### [`status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#status) + +Status of the operation the span represents. + +### [`status_code`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#status_code) + +The HTTP response status code. + +- **Type:** string + +### [`system`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#system) + +Database system (e.g., `postgresql` or `mysql`). + +- **Type:** string + +### [`trace.status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#tracestatus) + +The span trace's success or failure status. + +- **Type:** string + +### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transaction) + +Name of the containing transaction. + +- **Type:** string + +### [`transaction.method`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transactionmethod) + +HTTP method of the containing transaction. + +- **Type:** string + +### [`transaction.op`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transactionop) + +Operation of the containing transaction. + +- **Type:** string + +### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#useremail) + +An alternative or addition to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. + +- **Type:** string + +### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#userid) + +Application-specific internal identifier for the user. + +- **Type:** string + +### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#userusername) + +Username, which is typically a better label than `user.id`. + +- **Type:** string + +[Previous\\ +\\ +Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events) + +[Next\\ +\\ +Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/spans.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) + +# Our Approach + +Sentry uses a minimalist approach to documentation. Our docs have one goal: help customers gain mastery _quickly_. Minimalism in documentation puts the reader at the center of the content. Our audience is reading the documentation to solve a problem or finalize a setup or to understand. Thus, think **very critically** about the content that is provided, especially on a primary page. + +## [Use This Test](https://docs.sentry.io/contributing/approach/\#use-this-test) + +Ask these questions as you're developing content: + +- Is this information critical to helping a developer get up and running? If not, consider moving it to a subpage with a link to it from the primary page (or, as suggested by one of our engineering managers, "cool, I can bookmark this for later"). + +- Is this obvious from the UI? Our UI is largely self-documenting, so we don't need to explain what's already evident. + + +## [What Goes Where?](https://docs.sentry.io/contributing/approach/\#what-goes-where) + +Our content has some pretty clear divisions: + +- Platform/SDK content - instrument and configure your SDK +- Product content - look at all the data ingested into Sentry + +And within those primary categories: + +- Reference: What customers need to know +- Action: What customers can do (modify, filter, and so forth) + +If you're uncertain, [ask](https://github.com/getsentry/sentry-docs/issues). + +## [Writing for Sentry](https://docs.sentry.io/contributing/approach/\#writing-for-sentry) + +Keep these concepts in mind when contributing to docs: + +1. Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code. +2. Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/getting-started/inclusive-language/). +3. Feedback is a gift - share your PR so we can improve our content. + +[Previous\\ +\\ +Development Environment](https://docs.sentry.io/contributing/environment) + +[Next\\ +\\ +SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial/) + +# Tutorial: Create and List Teams with the Sentry API + +This guide walks you through the basics of using Sentry's API to list the teams in an organization and create a new team. + +APIs used in this tutorial: + +- [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) +- [Create a New Team](https://docs.sentry.io/api/teams/create-a-new-team/) + +## [Prerequisites](https://docs.sentry.io/api/guides/teams-tutorial/\#prerequisites) + +- A Sentry authentication token with team:write scopes or higher and project:read scopes or higher. + + +> If you don't have an authentication token, follow the [Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) tutorial to create an organization auth token with the following permissions, or higher: +> +> - Organization: Read +> - Team: Write + + +We recommend using a free [Sentry developer account](https://sentry.io/pricing/) for this tutorial. + +## [List an Organization's Teams](https://docs.sentry.io/api/guides/teams-tutorial/\#list-an-organizations-teams) + +First, you will use the [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) API to list all the teams in your organization. + +### [Find your organization ID](https://docs.sentry.io/api/guides/teams-tutorial/\#find-your-organization-id) + +The list teams API requires you to pass in the an organization id to list teams for. + +You can find your organization ID in the browser URL of your Sentry instance. For example, [https://test-org.sentry.io/](https://test-org.sentry.io/). + +### [Make the cURL call](https://docs.sentry.io/api/guides/teams-tutorial/\#make-the-curl-call) + +1. Open your terminal. + +2. Save your auth token and organization ID as environment variables for ease of use. Paste the following commands into your terminal, replacing `<organization_id>` with your organization ID and `<auth_token>` with the auth token you copied previously:Bash + +`` + +```bash code-highlight +export SENTRY_ORG_ID=<organization_id> +export SENTRY_AUTH_TOKEN=<auth_token> + +``` + +3. Paste the following cURL command into your terminal:Bash + +`` + +```bash code-highlight +curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \ + -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' + +``` + +4. Here's an example of what the output of the command should be, for an organization that has a team called "test-team":JSON + +`` + +```code-highlight json +[\ + {\ + "id": "4505449964175360",\ + "slug": "test-team",\ + "name": "test-team",\ + "dateCreated": "2023-06-30T18:44:59.196618Z",\ + "isMember": false,\ + "teamRole": null,\ + "flags": {\ + "idp:provisioned": false\ + },\ + "access": [\ + "alerts:read",\ + "team:read",\ + "member:read",\ + "org:read",\ + "project:releases",\ + "project:read",\ + "event:write",\ + "event:read"\ + ],\ + "hasAccess": true,\ + "isPending": false,\ + "memberCount": 1,\ + "avatar": {\ + "avatarType": "letter_avatar",\ + "avatarUuid": null\ + },\ + "orgRole": null\ + }\ +] + +```The output gives you details about the teams within the specified organization. + +If your organization has enough teams, the API will return paginated results. See Sentry's docs on [Pagination](https://docs.sentry.io/api/pagination/) to learn how to handle paginated results. + +5. \[Optional\] To list information about the projects associated with each team you can set the `detailed` query parameter to `1`:Bash + +`` + +```bash code-highlight +curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=1" \ + -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' + +```Here's an example of what that output might look like if "test-team" has one associated project named "test-project":JSON + +`` + +```code-highlight json +[\ + {\ + ...\ + "orgRole": null,\ + "externalTeams": [],\ + "projects": [\ + {\ + "id": "4505506997403648",\ + "slug": "test-project",\ + "name": "test-project",\ + "platform": "javascript-react",\ + "dateCreated": "2023-07-10T20:29:17.426792Z",\ + "isBookmarked": false,\ + "isMember": false,\ + "features": [\ + "alert-filters",\ + "minidump",\ + "race-free-group-creation",\ + "similarity-indexing",\ + "similarity-view",\ + "releases"\ + ],\ + "firstEvent": "2023-07-10T20:39:35.811000Z",\ + "firstTransactionEvent": true,\ + "access": [],\ + "hasAccess": true,\ + "hasMinifiedStackTrace": true,\ + "hasMonitors": false,\ + "hasProfiles": false,\ + "hasReplays": true,\ + "hasSessions": true,\ + "isInternal": false,\ + "isPublic": false,\ + "avatar": {\ + "avatarType": "letter_avatar",\ + "avatarUuid": null\ + },\ + "color": "#bf853f",\ + "status": "active"\ + }\ + ]\ + }\ +] + +``` + + +## [Create a Team](https://docs.sentry.io/api/guides/teams-tutorial/\#create-a-team) + +Now that you know what teams already exist in your org, use the [Create a New Team](https://docs.sentry.io/api/teams/create-a-new-team/) API to create another. + +1. Make sure your auth token and organization ID are both still stored as environment variables in your shell. + +2. Paste the following cURL command into your terminal:Bash + +`` + +```bash code-highlight +curl -d "name=tutorial-team" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \ + -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' + +```The `name` query parameter means the name of the created team should be "tutorial-team". + +3. Here's an example of what the output of the command should be:JSON + +`` + +```code-highlight json +{ + "id": "4505524553711616", + "slug": "tutorial-team", + "name": "tutorial-team", + "dateCreated": "2023-07-13T22:54:05.074990Z", + "isMember": false, + "teamRole": null, + "flags": { + "idp:provisioned": false + }, + "access": [\ + "event:write",\ + "member:read",\ + "alerts:read",\ + "project:releases",\ + "project:read",\ + "event:read",\ + "team:read",\ + "org:read"\ + ], + "hasAccess": true, + "isPending": false, + "memberCount": 0, + "avatar": { + "avatarType": "letter_avatar", + "avatarUuid": null + }, + "orgRole": null +} + +``` + +4. \[Optional\] To create a team where the `slug` value is different than the `name` value, you can specify both in your POST call, like so:Bash + +`` + +```bash code-highlight +curl -d "name=tutorial-team&slug=tutorial-team-slug" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \ + -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' + +``` + + +## [List an Organization's Teams](https://docs.sentry.io/api/guides/teams-tutorial/\#list-an-organizations-teams-1) + +Finally, call the [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) API one more time to make sure your new team is returned. + +1. Make sure your auth token and organization ID are both still stored as environment variables in your shell. + +2. Paste the following cURL command into your terminal:Bash + +`` + +```bash code-highlight +curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \ + -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' + +``` + +3. Your response should contain an entry for your new "tutorial-team" and look something like this:JSON + +`` + +```code-highlight json +[\ + {\ + "id": "4505524236910592",\ + "slug": "test-team",\ + "name": "test-team",\ + "dateCreated": "2023-07-13T21:33:31.686812Z",\ + "isMember": false,\ + "teamRole": null,\ + "flags": {\ + "idp:provisioned": false\ + },\ + "access": [\ + "member:read",\ + "alerts:read",\ + "org:read",\ + "project:read",\ + "team:read",\ + "project:releases",\ + "event:read",\ + "event:write"\ + ],\ + "hasAccess": true,\ + "isPending": false,\ + "memberCount": 1,\ + "avatar": {\ + "avatarType": "letter_avatar",\ + "avatarUuid": null\ + },\ + "orgRole": null\ + },\ + {\ + "id": "4505524616167424",\ + "slug": "tutorial-team",\ + "name": "tutorial-team",\ + "dateCreated": "2023-07-13T23:09:58.243168Z",\ + "isMember": false,\ + "teamRole": null,\ + "flags": {\ + "idp:provisioned": false\ + },\ + "access": [\ + "member:read",\ + "alerts:read",\ + "org:read",\ + "project:read",\ + "team:read",\ + "project:releases",\ + "event:read",\ + "event:write"\ + ],\ + "hasAccess": true,\ + "isPending": false,\ + "memberCount": 0,\ + "avatar": {\ + "avatarType": "letter_avatar",\ + "avatarUuid": null\ + },\ + "orgRole": null\ + }\ +] + +``` + + +[Previous](https://docs.sentry.io/api/guides) + +[Next\\ +\\ +Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token) + +- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Concepts](https://docs.sentry.io/concepts/key-terms/) +- [Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms/) + +# Key Terms & Features + +## A few key terms and features to help you get a better understanding of Sentry. + +Some of the below terms have corresponding features with the same name (in upper case) in the [Key Features](https://docs.sentry.io/concepts/key-terms/key-terms/#key-features) section. + +## [Key Terms](https://docs.sentry.io/concepts/key-terms/key-terms/\#key-terms) + +- **alerts** \- Alerts let you know about problems with your code in real-time by sending you notifications when certain alert rule conditions are met. There are several types of alerts available with customizable thresholds and integrations. + +- **attachments** \- Stored additional files, such as config or log files that are related to an error event. + +- **data** \- Anything you send to Sentry. This includes, events (errors or transactions), attachments, and event metadata. + +- **distributed trace** \- When a trace includes work in multiple services, it's called a [distributed trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/), because the trace is distributed across those services. + +- **DSN** \- Data Source Name. A DSN tells the Sentry SDK where to send events so the events are associated with the correct project. Sentry automatically assigns you a DSN when you create a project. Learn more in our full [DSN documentation](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). + +- **environment** \- `environment` is a Sentry-supported tag that you can add to your SDK that's intended to refer to your code deployments' naming convention, such as _development_, _testing_, _staging_, or _production_. Environments help you better filter issues and transactions among other uses. Learn more in our full [Environments documentation](https://docs.sentry.io/product/sentry-basics/environments/). + +- **error** \- What counts as an error varies by platform, but in general, if there's something that looks like an exception, it can be captured as an error in Sentry. Sentry automatically captures errors, uncaught exceptions, and unhandled rejections, as well as other types of errors, depending on platform. + +- **event** \- An error or a transaction. + +- **issues** \- An issue is a grouping of similar errors or performance problems. Every event has a set of characteristics called its fingerprint, which is what Sentry uses to group them. For example, Sentry groups error events together when they are triggered by the same part of your code. This grouping of events into issues allows you to see how frequently a problem is happening and how many users it's affecting. + +- **performance monitoring** \- Performance monitoring is the act of tracking application performance and measuring metrics such as how many transactions are being sent and the average response time for all occurrences of a given transaction. To do this, Sentry captures [distributed traces](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/) consisting of transactions and [spans](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/#traces-transactions-and-spans) to measure individual services, as well as operations within those services. + +- **project** \- A project represents your service or application in Sentry. You can create a project for a particular language or framework used in your application. For example, you might have separate projects for your API server and frontend client. For more information, check out our [best practices for creating projects](https://docs.sentry.io/organization/getting-started/#4-create-projects). Projects allow you to associate events with a distinct application in your organization and assign responsibility and ownership to specific users and teams within your organization. + +- **release** \- A release is a version of your code deployed to an environment. When you notify Sentry about a release, you can identify new issues and regressions associated with it, confirm whether an issue is resolved in the next release, and apply source maps. Learn more in the full [Releases documentation](https://docs.sentry.io/product/releases/). + +- **release health** \- Release health data provides insight into the impact of crashes and bugs as it relates to your user's experience and reveals trends with each new issue. Learn more in the full [release health documentation](https://docs.sentry.io/product/releases/health/). + +- **sentry.io** \- Sentry's user interface for SaaS customers, where event data captured by our SDK is visualized. (For self-hosted users, the user interface is on an internal domain for your company.) + +- **Sentry SDKs** \- Sentry's programming language/framework-specific libraries for application monitoring. When you add one of our SDKs to your application, event data from your application is captured and sent to Sentry, so we can provide you with error and performance reports. + +- **span** \- A [span](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans) is the basic unit that traces are composed of. Multiple groups of parent-child spans make up a trace in Sentry and share a trace\_id, which can help you get to the root cause of a problem faster. + +- **team** \- Teams are associated with your Sentry projects, and their members receive issue notifications as a group. Learn more about [setting up teams](https://docs.sentry.io/organization/getting-started/#2-set-up-teams). + +- **trace** \- A [trace](https://docs.sentry.io/concepts/key-terms/tracing/) is the record of the entire operation you want to measure or track - like page load, an instance of a user completing some action in your application, or a cron job in your backend. + +- **transaction** \- A transaction represents a single instance of a service being called to support an operation you want to measure or track, like a page load, page navigation, or asynchronous task. Transaction events are grouped by the transaction name. + + +## [Key Features](https://docs.sentry.io/concepts/key-terms/key-terms/\#key-features) + +Each of these key features have their own page (or set of pages) in the [sentry.io](https://sentry.io/) application. + +- **Issues** \- Displays information about grouped problems in your application. From here, you can go to the **Issue Details** page for a more granular view of any issue. Learn more in the full [Issues documentation](https://docs.sentry.io/product/issues/). + +- **Projects** \- Lists the projects of which you're a member, by team, and provides you with a high-level overview of your projects. From here, you can go to the **Project Details** page of each project for a more granular view. Learn more in the full [Projects documentation](https://docs.sentry.io/product/projects/). + +- **Explore** \- Sentry offers multiple ways to search and investigate your application's data — including your app's traces, metrics, profiles, replays, and events — to get the information you need to debug issues more quickly and easily. Use the Discover page to query events across environments, visualize the results, and unlock insights into the health of your entire system. Learn more in the full [Explore documentation](https://docs.sentry.io/product/explore/). + +- **Insights** \- Sentry surfaces insights that can help you identify opportunities at the service-level to improve various parts of your app's performance, including requests, assets, caches, queues, and more. Modules living under the Insights heading provide an overview of how your project is performing in that category, as well as the ability to review sample events and their traces to help you diagnose potential problems. + +- **Insights Overview** \- The main view in [sentry.io](http://sentry.io/) where you can search or browse for transaction data. The page displays graphs that visualize transactions or trends, as well as a table where you can view relevant transactions and drill down to more information about them. Learn more in the full [performance monitoring documentation](https://docs.sentry.io/product/insights/overview/). + +- **Alerts** \- Where you can create new alert rules and manage existing ones. Learn more in the full [Alerts documentation](https://docs.sentry.io/product/alerts/). + +- **Dashboards** \- Provide you with a broad overview of your application’s health by allowing you to navigate through error and performance data across multiple projects. Dashboards are made up of one or more widgets, and each widget visualizes one or more **Discover** or **Issues** queries. Learn more in the full [Dashboards documentation](https://docs.sentry.io/product/dashboards/). + +- **Releases** \- Provides a high-level view of each release version, the associated project, the adoption stage of each release, the authors of each commit, as well as release health data including the percentage of crash-free users, and the percentage of crash-free sessions. You can navigate directly to the **Releases** page or from the **Issue Details** page, by selecting release ID listed under "Last Seen". Learn more in the full [Releases documentation](https://docs.sentry.io/product/releases/). + + +[Previous\\ +\\ +Concepts](https://docs.sentry.io/concepts/key-terms) + +[Next\\ +\\ +Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/key-terms.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Pages](https://docs.sentry.io/contributing/pages/) +- [Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams/) + +# Charts & Diagrams + +You can render charts and diagrams in you MDX files using [Mermaid](https://mermaid.js.org/): + +Example + +`` + +````code-highlight txt +```mermaid +flowchart TD +Start --> Stop +``` + +```` + +Will turn into this: + +Mermaid + +`` + +```code-highlight mermaid +flowchart TD + Start --> Stop + +``` + +See the [Mermaid documentation](https://mermaid.js.org/intro/) to learn what types of charts and diagrams can be rendered. + +[Previous\\ +\\ +Images](https://docs.sentry.io/contributing/pages/images) + +[Next\\ +\\ +MDX Components](https://docs.sentry.io/contributing/pages/components) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/charts-diagrams.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) +- [Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso/) +- [Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) + +# Okta SCIM Provisioning + +## Set up Okta's SCIM Integration for Member and Team Provisioning + +This feature is only available if your organization is on a Business or Enterprise plan. + +If you change your organization slug, you'll also need to update it in the "Auth" section of your "Organization Settings" in Sentry. + +### [Supported Features](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#supported-features) + +- Create users +- Deactivate users +- Push groups +- Import groups +- Configure organization-level roles +- Update user attributes (organization-level roles only) + +### [Requirements](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#requirements) + +Okta SCIM provisioning requires: + +- A subscription to Sentry Business Plan or higher. +- Configuration of SAML SSO for Okta [as documented here](https://docs.sentry.io/organization/authentication/sso/okta-sso/), or use the Okta sign-on tab in your Sentry Okta application to configure SAML. +- **Selection of Email for the Application username format** in the Sign On application tab in Okta. [![Okta username configuration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-username-config-FIAOC3YE.png%231332x710&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-username-config-FIAOC3YE.png) + +### [Sentry Configuration](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#sentry-configuration) + +1. Sign in to [sentry.io](https://sentry.io/). Select **Settings > Auth** [![Sentry Okta SCIM Auth Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-settings-auth-I7AT2EWD.png%232688x1428&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-settings-auth-I7AT2EWD.png) +2. Under General Settings select "Enable SCIM", then "Save Settings" [![Sentry Enable SCIM Instruction](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-enable-sentry-7WE3LMJ5.png%231542x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-enable-sentry-7WE3LMJ5.png) Sentry will display "SCIM Information" that contains your Auth Token and SCIM Base URL. [![SCIM Credentials Fields](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-sentry-fields-Q4U5PUUE.png%231504x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-sentry-fields-Q4U5PUUE.png) + +### [Okta Configuration](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#okta-configuration) + +1. Sign in to your Okta organization with your administrator account. From the admin console's sidebar, select Applications > Applications, then select the existing Sentry application. + +2. Select the "Provisioning" tab, then "Configure API integration". [![Okta configure SCIM API](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-okta-configure-B4HRRJ2R.png%231852x1022&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-okta-configure-B4HRRJ2R.png) + +3. Select "Enable API Integration", then enter the SCIM URL from the auth settings page as the Base URL field. + +4. For the API Token, copy the Auth Token value from the auth settings page. + +5. Select "Test API Credentials". You should see a "the app was verified successfully" message appear. + +6. Select "Save" to be directed to SCIM App settings. + +7. On the Provisioning page, select "To App", then "edit": [![Okta Save SCIM Settings](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-okta-edit-KBKRWCR4.png%231864x686&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-okta-edit-KBKRWCR4.png) + +8. Enable both "Create Users" and "Deactivate Users", then click the "Save" button. [![Okta Create and Deactivate Users](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-user-sync-3RMBVCM6.png%232100x1366&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-user-sync-3RMBVCM6.png) + + +Once these changes have been made, newly assigned users will be sent an invitation email. If a user gets un-assigned, they'll be removed from their organization in Sentry. + +You can use "Push Groups" to sync and assign groups in Okta; they'll be mirrored in Sentry teams. + +If you use Okta to assign organization membership, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. To remove these users, deprovision them in Okta. + +[![Okta Provisioned User Unable to Leave](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-provisioned-unable-to-leave-IOB6CFSL.png%232444x250&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-provisioned-unable-to-leave-IOB6CFSL.png) + +### [Configuring Organization-level Roles](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#configuring-organization-level-roles) + +Here's how to assign an organization-level role to an Okta group: + +1. Add a new custom attribute to your Okta application profile + +1. Navigate to your application settings in Okta + +2. Under the "Provisioning" tab, select "Go to Profile Editor" [![Okta Provisioning Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-go-to-profile-ANIFPKTO.png%233398x2540&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-go-to-profile-ANIFPKTO.png) + +3. Select "+ Add Attribute" [![Okta Add Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-add-attribute-ORRVTSLT.png%232100x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-add-attribute-ORRVTSLT.png) + +4. Fill out the form with the following settings (You can set whatever value you want for any setting not listed below.): + + + - Data Type: `string` + - Display Name: `Org Role` + - Variable Name: `sentryOrgRole` + - External name: `sentryOrgRole` + - External namespace: `urn:ietf:params:scim:schemas:core:2.0:User` + - Attribute type: `Group` + +[![Okta Custom Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-custom-attribute-values-4FONBHNY.png%233400x2546&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-custom-attribute-values-4FONBHNY.png) +2. Assign a group to your okta application [![Okta Assign Group](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-assign-group-77ZIXYR4.png%232220x884&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-assign-group-77ZIXYR4.png) + +3. In the form, enter the string for the org-level role [![Okta Set Role](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-set-group-attribute-XTTLAXCA.png%233400x1668&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-set-group-attribute-XTTLAXCA.png) + + +- If the `sentryOrgField` field is left blank, group members will be provisioned with the default organization-level role. This default role can be configured in Sentry, under Settings -> Organization -> Auth. Otherwise, the role must be one of the following: + - Admin + - Manager + - Billing + - Member +- Invalid role names will prevent group members from being provisioned. To try again, you'll need to remove the group first. +- For security reasons, the "Owner" role cannot be provisioned through SCIM. However, you _can_ deprovision users who have the "Owner" role in Sentry, but aren't provisioned through SCIM. + - For self-hosted users with custom roles, this extends to any role with the `org:admin` permission + +If a user is a member of multiple Okta groups, only the attributes set by the first group will be used. + +If you use Okta to assign organization-level roles, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. To change a user's organization-level role, you will need to deprovision and then reprovision them with the new role. + +Users who've had their roles assigned via Okta will only be able to make membership changes via Okta. + +[![Okta Role Restricted Role Select](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-role-restricted-sentry-role-select-QCW7B66W.png%232350x1020&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-role-restricted-sentry-role-select-QCW7B66W.png) + +### [Updating User Attributes](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#updating-user-attributes) + +Currently, Sentry only supports the ability to update user attributes for organization-level roles. You'll be able to edit the attribute for users assigned to your application once you've added the `sentryOrgRole` attribute to your Okta application profile. + +[![Okta Edit Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-edit-sentryOrgRole-attribute-BSHZOCG4.png%231362x692&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-edit-sentryOrgRole-attribute-BSHZOCG4.png) + +The user's role in Sentry will reflect their organization role in your Auth settings. This means that if you change a user's attribute to blank, their organization-level role will be removed from Sentry. + +## [Troubleshooting](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#troubleshooting) + +### [I get a "Matching user not found" error in Okta when provisioning a user.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-get-a-matching-user-not-found-error-in-okta-when-provisioning-a-user) + +Make sure that `Create User` and `Deactivate User` are enabled in the "Provisioning" tab of your Sentry application in Okta [(see Okta Configuration step 7)](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/#okta-configuration). + +### [I assigned Sentry to a group but no team was created.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-assigned-sentry-to-a-group-but-no-team-was-created) + +Assigning Sentry to a group in Okta is the same as assigning Sentry to every member of that group. Functionally, this provisions every group member within Sentry, but doesn't create a team. To create a team, push the group to Sentry from the `Push Groups` tab of your Sentry application in Okta. + +### [I pushed a group to Sentry but the team is empty.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-pushed-a-group-to-sentry-but-the-team-is-empty) + +Pushing a group via Okta tells Sentry to create a new team with the same name as the Okta group. Only those users who've already been provisioned as members of that group will be added to the Sentry team. Make sure that your group in Okta contains the appropriate users and that they've already been provisioned. + +### [I pushed a group to Sentry but am receiving a "User not found" error.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-pushed-a-group-to-sentry-but-am-receiving-a-user-not-found-error) + +If possible, isolate the user(s) that are causing the error. Then remove the user(s) from Sentry and provision them again with Okta. + +### [I’m unable to use the Sentry application to remove a member whose membership is managed by an identity provider.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#im-unable-to-use-the-sentry-application-to-remove-a-member-whose-membership-is-managed-by-an-identity-provider) + +When team membership is managed by an identity provider (such as Okta), it can only be updated or revoked via that identity provider. + +### [I’m unable to use the Sentry application to add or remove members from my team.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#im-unable-to-use-the-sentry-application-to-add-or-remove-members-from-my-team) + +If you use Okta to assign members to a team, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. + +### [I used Okta to remove a user from Sentry, but they’re still showing up in my Sentry organization.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-used-okta-to-remove-a-user-from-sentry-but-theyre-still-showing-up-in-my-sentry-organization) + +Make sure that `Deactivate User` is enabled in the "Provisioning" tab of your Sentry application in Okta. Re-provision the user, then remove them again. + +### [How do I remove the organization-level role for a user that I set via Okta?](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#how-do-i-remove-the-organization-level-role-for-a-user-that-i-set-via-okta) + +Change the user's role attribute to blank. + +## [Known Issues](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#known-issues) + +- The Import Users feature isn't currently supported because Sentry's SCIM API doesn't support the user `name` attribute fields: `firstName` and `lastName` at this time. For compatibility purposes, they're returned as `N/A` values. +- If the `active` field is set to `false` for any given user, their organization member record gets deleted. +- The only filter operation supported for resources is `eq`. +- When provisioning a new team, Sentry will both normalize and convert the team `displayName` uppercase to lowercase, and convert spaces to dashes. +- The GET /Groups endpoint cannot return more than 10000 members in a group, see [SCIM API documentation](https://docs.sentry.io/api/scim/) for more information. + +[Previous\\ +\\ +Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) + +[Next\\ +\\ +Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/okta-sso/okta-scim.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) +- [Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/) + +# Common Content + +Our docs strive for a contributor-friendly balance of duplication vs. complexity. That means we generally don't try to share content between SDKs in our docs, even when they have similar information architecture, sections, and even wording. Instead of enforcing consistency through shared content, we encourage contributors to reference other SDK docs to keep things consistent wherever possible. + +For SDKs that have framework-specific docs (which we call guides or children), common content for that SDK's frameworks lives in `/docs/platforms/<platform_name>/common/`. + +## [Hierarchy](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/\#hierarchy) + +What displays for the user relies upon the hierarchy of content as detailed in our content discussing [Platforms & Guides](https://docs.sentry.io/contributing/platforms/). In short, a guide's content displays if provided. If not provided, then the platform content displays. + +## [Tuning Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/\#tuning-common-content) + +To ensure that common content can scale as we support more platforms and frameworks, we use `include` files. These files can range from, most typically, a code sample specific to a platform or framework to information that augments the core content for a specific platform or framework. These platform-specific `include` files live in [`plaftorm-includes/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes). We also have [platform-agnostic `include` files](https://docs.sentry.io/contributing/approach/product-docs/write-index/#includes) which are discussed in our product docs. + +[Previous\\ +\\ +SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) + +[Next\\ +\\ +How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/common_content.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Installation](https://docs.sentry.io/cli/installation/) + +# Installation + +## Learn about the different methods available to install \`sentry-cli\`. + +Depending on your platform, there are different methods available to install `sentry-cli`. + +## [Manual Download](https://docs.sentry.io/cli/installation/\#manual-download) + +You can find the list of releases on [the GitHub release page](https://github.com/getsentry/sentry-cli/releases/). We provide executables for Linux, OS X and Windows. It’s a single file download and upon receiving the file you can rename it to just `sentry-cli` or `sentry-cli.exe` to use it. + +## [Automatic Installation](https://docs.sentry.io/cli/installation/\#automatic-installation) + +If you are on OS X or Linux, you can use the automated downloader which will fetch the latest release version for you and install it: + +Bash + +`` + +```bash code-highlight +curl -sL https://sentry.io/get-cli/ | sh + +``` + +We do however, encourage you to pin the specific version of the CLI, so your builds are always reproducible. To do that, you can use the exact same method, with an additional version specifier: + +Bash + +`` + +```bash code-highlight +curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION="2.42.2" sh + +``` + +This will automatically download the correct version of `sentry-cli` for your operating system and install it. If necessary, it will prompt for your admin password for `sudo`. For a different installation location or for systems without `sudo` (like Windows), you can `export INSTALL_DIR=/custom/installation/path` before running this command. + +To verify it's installed correctly you can bring up the help: + +Bash + +`` + +```bash code-highlight +sentry-cli --help + +``` + +## [Installation via NPM](https://docs.sentry.io/cli/installation/\#installation-via-npm) + +There is also the option to install `sentry-cli` via npm for specialized use cases. This, for instance, is useful for build servers. The package is called `@sentry/cli` and in the post installation it will download the appropriate release binary: + +npmyarnpnpm + +`` + +```bash code-highlight +npm install @sentry/cli + +``` + +You can then find it in the `.bin` folder: + +Bash + +`` + +```bash code-highlight +./node_modules/.bin/sentry-cli --help + +``` + +In case you want to install this with npm system wide with sudo you will need to pass `--unsafe-perm` to it: + +Bash + +`` + +```bash code-highlight +sudo npm install -g @sentry/cli --unsafe-perm + +``` + +This installation is not recommended however. + +### [Downloading From a Custom Source](https://docs.sentry.io/cli/installation/\#downloading-from-a-custom-source) + +By default, this package will download sentry-cli from the CDN managed by [Fastly](https://www.fastly.com/). To use a custom CDN, set the npm config property `sentrycli_cdnurl`. The downloader will append `"/<version>/sentry-cli-<dist>"`. + +Bash + +`` + +```bash code-highlight +npm install @sentry/cli --sentrycli_cdnurl=https://mymirror.local/path + +``` + +Or add property into your `.npmrc` file ( [https://docs.npmjs.com/files/npmrc](https://docs.npmjs.com/files/npmrc)) + +Bash + +`` + +```bash code-highlight +sentrycli_cdnurl=https://mymirror.local/path + +``` + +Another option is to use the environment variable `SENTRYCLI_CDNURL`. + +Bash + +`` + +```bash code-highlight +SENTRYCLI_CDNURL=https://mymirror.local/path npm install @sentry/cli + +``` + +### [Available Installation Options](https://docs.sentry.io/cli/installation/\#available-installation-options) + +Options listed below control how `sentry-cli` install script behaves, when installed through `npm`. + +`SENTRYCLI_CDNURL`: + +If set, the script will use given URL for fetching the binary. Defaults to `https://downloads.sentry-cdn.com/sentry-cli`. + +`SENTRYCLI_USE_LOCAL`: + +If set to `1`, `sentry-cli` binary will be discovered from your `$PATH` and copied locally instead of being downloaded from external servers. It will still verify the version number, which has to match. + +`SENTRYCLI_SKIP_DOWNLOAD`: + +If set to `1`, the script will skip downloading the binary completely. + +`SENTRYCLI_SKIP_CHECKSUM_VALIDATION`: + +If set to `1`, the script will skip the checksum validation phase. You can manually verify the checksums by visiting [Build Checksums](https://docs.sentry.io/cli/installation/#build-checksums) page. + +`SENTRYCLI_NO_PROGRESS_BAR`: + +If set to `1`, the script will not display download progress bars. This is a default behavior for CI environments. + +`SENTRYCLI_LOG_STREAM`: + +If set, the script will change where it writes its output. Possible values are `stdout` and `stderr`. Defaults to `stdout`. + +## [Installation via Homebrew](https://docs.sentry.io/cli/installation/\#installation-via-homebrew) + +If you are on OS X, you can install `sentry-cli` via homebrew: + +Bash + +`` + +```bash code-highlight +brew install getsentry/tools/sentry-cli + +``` + +## [Installation via Scoop](https://docs.sentry.io/cli/installation/\#installation-via-scoop) + +If you are on Windows, you can install `sentry-cli` via [Scoop](https://scoop.sh/): + +PowerShell + +`` + +```code-highlight powershell +> scoop install sentry-cli + +``` + +## [Docker Image](https://docs.sentry.io/cli/installation/\#docker-image) + +For unsupported distributions and CI systems, we offer a Docker image that comes with `sentry-cli` preinstalled. It is recommended to use the `latest` tag, but you can also pin to a specific version. By default, the command runs inside the `/work` directory. Mount relevant project folders and build outputs there to allow `sentry-cli` to scan for resources: + +Bash + +`` + +```bash code-highlight +docker pull getsentry/sentry-cli +docker run --rm -v $(pwd):/work getsentry/sentry-cli --help + +``` + +## [Updating and Uninstalling](https://docs.sentry.io/cli/installation/\#updating-and-uninstalling) + +You can use `sentry-cli update` and `sentry-cli uninstall` to update or uninstall the `sentry-cli` binary. These commands may be unavailable in certain situations, generally when `sentry-cli` has been installed by a tool like homebrew or yarn, either directly or as a dependency of another package. In those cases, the same tool will need to be used for updating and removal. If you find that `sentry-cli update` and `sentry-cli uninstall` aren't working and you don't know how the package was installed, running `which sentry-cli` will often provide a clue as to which tool to use. + +## [Build Checksums](https://docs.sentry.io/cli/installation/\#build-checksums) + +When downloading an executable from a remote server, it's often a good practice to verify, that what has been downloaded, is in fact what we expect it to be. To make sure that this is the case, we can use checksum validation. A checksum is the value calculated from the contents of a file, in a form of hash, in our case SHA256, and it acts as the data integrity check, as it's always producing the same output, for a given input. + +Below is the table of SHA256 checksums for all available build targets that our CLI supports. To calculate the hash of a downloaded file, you can use `sha256sum` utility, which is preinstalled in OSX and most Linux distributions. + +| Filename (v2.42.2) | Integrity Checksum | +| --- | --- | +| sentry-cli-Darwin-arm64 | `sha384-0443a228db1b8fddd4cade3c9b7d8ac4ea46c9872fcbaa46014f95f6c25f7d97` | +| sentry-cli-Darwin-universal | `sha384-957bb8224e5d1304e97793ad674e5c42426fe0023dcdd937cfc2a5f8ce2e0b6a` | +| sentry-cli-Darwin-x86\_64 | `sha384-f95c7a2b7555bf41d54904cedd1be6c1b7b2765eff4e2a8a5911fda2af7fa761` | +| sentry-cli-Linux-aarch64 | `sha384-5b0eae7991817bb58ec9a039fdec38cace47c40f5133e11f553985968dc74af6` | +| sentry-cli-Linux-armv7 | `sha384-1d06e01e7e8bc42def337469626bdcc9693eba4950f225a24b6d4204c7e0a060` | +| sentry-cli-Linux-i686 | `sha384-345926403c9e3c58d39b4938eee43299966e6984fc1ba3030ad21932d498b8bf` | +| sentry-cli-Linux-x86\_64 | `sha384-7d5e69080cac84468547796a1123a2db05133dc4da5b4b042f5f1b5f32050cc5` | +| sentry-cli-Windows-i686.exe | `sha384-8a9d33e406563f497df418b3c98094b7c0534d393349fd0e94feba7f8e85c006` | +| sentry-cli-Windows-x86\_64.exe | `sha384-ef9c552f17fdd7d0043981aecf72906ddedee5d07d4699f8ee5a23103d6a2a05` | +| sentry\_cli-2.42.2-py3-none-macosx\_10\_15\_x86\_64.whl | `sha384-d8b13bd4ce2bb9a1134a9704ef29ebcee2e958977507c4e88d16873b4396a263` | +| sentry\_cli-2.42.2-py3-none-macosx\_11\_0\_arm64.whl | `sha384-144000522c7c5c45fc9d407eff0f0db9c6c03cc2bfe75e138c973834be2c9be8` | +| sentry\_cli-2.42.2-py3-none-macosx\_11\_0\_universal2.whl | `sha384-d8748fb3c594a7f0a5f1eda715170ec83043fd40296165ae88af57d10d6de9c4` | +| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_aarch64.manylinux2014\_aarch64.musllinux\_1\_2\_aarch64.whl | `sha384-aec4bd20178932721131ed6c498074bd95381fe800b8b3b6c7248a369eed1c6f` | +| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_armv7l.manylinux2014\_armv7l.musllinux\_1\_2\_armv7l.whl | `sha384-3cec8ef42a12b62e266821a25530937066647bddc0c7a18d06a12cc8a2d65b31` | +| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_i686.manylinux2014\_i686.musllinux\_1\_2\_i686.whl | `sha384-b529127ddb96105a458aa552d95b59312eb206fca69223528a98a408af4dbf2e` | +| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_x86\_64.manylinux2014\_x86\_64.musllinux\_1\_2\_x86\_64.whl | `sha384-e4f2e81f73813035f95fd93af3d83878c9ed00461fdbf6759548996fbcf6ed23` | +| sentry\_cli-2.42.2-py3-none-win32.whl | `sha384-7b038e5463a35803cfb41dd96d29b9f441a12530df133a5a496297783b7d2c38` | +| sentry\_cli-2.42.2-py3-none-win\_amd64.whl | `sha384-f6135bb3adb50208bc083b577cdefc55b0c42cc03a1a3c234f190baba6ad22d9` | +| sentry\_cli-2.42.2.tar.gz | `sha384-c08b78fee424fec550d43795b2295140dc528ba120a3fec4301753f7b7c7aa41` | + +If you would like to verify checksums for historic versions of the `sentry-cli`, please refer to our release registry directly, which can be found at [https://release-registry.services.sentry.io/apps/sentry-cli/{version}](https://release-registry.services.sentry.io/apps/sentry-cli/latest). For example, [https://release-registry.services.sentry.io/apps/sentry-cli/1.74.4](https://release-registry.services.sentry.io/apps/sentry-cli/1.74.4). + +[Previous\\ +\\ +Sentry CLI](https://docs.sentry.io/cli) + +[Next\\ +\\ +Configuration and Authentication](https://docs.sentry.io/cli/configuration) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/installation.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Debug Information Files](https://docs.sentry.io/cli/dif/) + +# Debug Information Files + +## Debug information files allow Sentry to extract stack traces and provide more information about crash reports for most compiled platforms. Sentry's CLI can be used to validate and upload debug information files. + +Debug information files allow Sentry to extract stack traces and provide more information about crash reports for most compiled platforms. `sentry-cli` can be used to validate and upload debug information files. For more general information, refer to [_Debug Information Files_](https://docs.sentry.io/platforms/native/data-management/debug-files/). + +## [Permissions](https://docs.sentry.io/cli/dif/\#permissions) + +The `sentry-cli` requires an [Organization Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) so that Debug Information Files can be uploaded. + +Source maps, while also being debug information files, are handled differently in Sentry. For more information see [Source Maps in sentry-cli](https://docs.sentry.io/cli/releases/#sentry-cli-sourcemaps). + +## [Checking Files](https://docs.sentry.io/cli/dif/\#checking-files) + +Not all debug information files can be used by Sentry. To see if they are usable or not, you can use the `sentry-cli debug-files check` command: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files check mylibrary.so.debug + +Debug Info File Check + Type: elf debug companion + Contained debug identifiers: + > 924e148f-3bb7-06a0-74c1-36f42f08b40e (x86_64) + Contained debug information: + > symtab, debug + Usable: yes + +``` + +This will report the debug identifiers of the debug information file as well as if it passes basic requirements for Sentry. + +## [Finding Files](https://docs.sentry.io/cli/dif/\#finding-files) + +If you see in Sentry's UI that debug information files are missing, but you are not sure how to locate them, you can use the `sentry-cli debug-files find` command to look for them: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files find <identifier> + +``` + +Additionally, `sentry-cli debug-files upload` can automatically search for files in a folder or ZIP archive. + +## [Creating Source Bundles](https://docs.sentry.io/cli/dif/\#creating-source-bundles) + +To get inline source context in stack traces in the Sentry UI, `sentry-cli` can scan debug files for references to source code files, resolve them in the local file system and bundle them up. The resulting source bundle is an archive containing all source files referenced by a specific debug information file. + +This is particularly useful when building and uploading debug information files are detached. In this case, a source bundle can be created when building and can be uploaded at any later point in time with `sentry-cli debug-files upload`. + +To create a source bundle, use the `debug-files bundle-sources` command on a list of debug information files: + +Bash + +`` + +```bash code-highlight +# on the build machine: +sentry-cli debug-files bundle-sources /path/to/files... + +# at any later time: +sentry-cli debug-files upload --type sourcebundle /path/to/bundles... + +``` + +To create multiple source bundles for all debug information files, use the command on each file individually. + +Alternatively, add the `--include-sources` option to the `debug-files upload` command, which generates source bundles on the fly during the upload. This requires that the upload is performed on the same machine as the application build: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload --include-sources /path/to/files... + +``` + +This feature is supported by build tools that produce debug information files supported by Sentry such as DWARF and PDB. This applies to languages such as C/C++/C#/Swift/Rust/Zig/etc. For Java/Kotlin and other JVM languages, use one of the plugins: [Maven](https://docs.sentry.io/platforms/java/maven/) or [Gradle](https://docs.sentry.io/platforms/java/gradle/). + +## [Uploading Files](https://docs.sentry.io/cli/dif/\#uploading-files) + +Use the `sentry-cli debug-files upload` command to upload debug information files to Sentry. The command will recursively scan the provided folders or ZIP archives. Files that have already been uploaded are skipped automatically. + +We recommend uploading debug information files when publishing or releasing your application. Alternatively, files can be uploaded during the build process. See [_Debug Information Files_](https://docs.sentry.io/platforms/native/data-management/debug-files/) for more information. + +You need to specify the organization and project you are working with because debug information files work on projects. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). + +A basic debug file upload can be started with: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload -o <org> -p <project> /path/to/files... + +> Found 2 debug information files +> Prepared debug information files for upload +> Uploaded 2 missing debug information files +> File processing complete: + + PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable) + PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion) + +``` + +After the upload, Sentry analyzes the files to symbolicate future events. If you want to send a native crash to Sentry to verify correct operation, ensure that the debug files are listed in _Project Settings > Debug Files_. Alternatively, specify `--wait` in the CLI, which will block until server-side analysis is complete: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload -o <org> -p <project> --wait /path/to/files... + +> Found 2 debug information files +> Prepared debug information files for upload +> Uploaded 2 missing debug information files +> File processing complete: + + OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable) + OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion) + +``` + +### [Upload Options](https://docs.sentry.io/cli/dif/\#upload-options) + +The command's `--help` output lists and explains all options: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload --help + +``` + +### [Symbol Maps](https://docs.sentry.io/cli/dif/\#symbol-maps) + +If you are hiding debug symbols from Apple, the debug files will not contain many useful symbols. In that case, the sentry-cli upload will warn you that it needs BCSymbolMaps: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload ... +> Found 34 debug information files +> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps) + +``` + +In this case, you need the BCSymbolMaps that match your files. Typically, these are generated by the Xcode build process. Supply the `--symbol-maps` parameter and point it to the folder containing the symbol maps: + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload --symbol-maps path/to/symbolmaps path/to/debug/symbols + +``` + +### [Breakpad Files](https://docs.sentry.io/cli/dif/\#breakpad-files) + +In contrast to native debug files, Breakpad symbols discard a lot of information that is not required to process minidumps. Most notably, inline functions are not declared, such that Sentry is not able to display inline frames in stack traces. + +If possible, upload native debug files such as dSYMs, PDBs or ELF files instead of Breakpad symbols. + +## [ProGuard Mapping Upload](https://docs.sentry.io/cli/dif/\#proguard-mapping-upload) + +`sentry-cli` can be used to upload ProGuard files to Sentry; however, in most situations, you would use the [Gradle plugin](https://github.com/getsentry/sentry-android-gradle-plugin) to do that. Nevertheless, there may be situations where you would upload ProGuard files manually. For instance, when you only release some of the builds you're creating. + +You need to specify the organization and project you are working with because ProGuard files work on projects. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). + +The `upload-proguard` command is the one to use for uploading ProGuard files. It takes the path to one or more ProGuard mapping files and will upload them to Sentry. + +Bash + +`` + +```bash code-highlight +sentry-cli upload-proguard \ + app/build/outputs/mapping/{BuildVariant}/mapping.txt + +``` + +Since the Android Sentry SDK needs to know the UUID of the mapping file, you need to associate it with the upload. However, you first have to place that UUID into the `AndroidManifest.xml` file: + +Xml + +`` + +```code-highlight xml +<application> + <meta-data + android:name="io.sentry.proguard-uuid" + android:value="A_VALID_UUID" + /> +</application> + +``` + +The same UUID needs to be used to upload the mapping file: + +Bash + +`` + +```bash code-highlight +sentry-cli upload-proguard \ + --uuid A_VALID_UUID \ + app/build/outputs/mapping/{BuildVariant}/mapping.txt + +``` + +Additionally, you can associate the proguard mapping file to a specific release: + +Bash + +`` + +```bash code-highlight +# Additionally create an association to the release my.app.id@1.0.0+1 +sentry-cli upload-proguard \ + --uuid A_VALID_UUID \ + app/build/outputs/mapping/{BuildVariant}/mapping.txt \ + --app-id my.app.id \ + --version 1.0.0 \ + --version-code 1 + +``` + +After the upload, Sentry deobfuscates future events. To make sure that it worked, you can check _Project Settings > ProGuard_ and see if the upload mapping files are listed. + +### [Upload Options](https://docs.sentry.io/cli/dif/\#upload-options-1) + +The command's `--help` output lists and explains all options: + +Bash + +`` + +```bash code-highlight +sentry-cli upload-proguard --help + +``` + +## [JVM Source Bundles](https://docs.sentry.io/cli/dif/\#jvm-source-bundles) + +If you're using a build tool we don't support, or you prefer not to use Sentry's build tool plugins, you'll need to upload source bundle files manually. + +See the build tool plugins we currently support here: + +- [Android](https://docs.sentry.io/platforms/android/enhance-errors/source-context/) +- [Java](https://docs.sentry.io/platforms/java/source-context/) + +You can also upload ProGuard files manually with `sentry-cli` for any JVM-based language like Java or Kotlin. + +Before you can upload source files, you must configure the Sentry CLI with the organization and project you are uploading bundle files for. See the CLI docs on [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects) to learn how to do this. + +### [Creating a Source Bundle](https://docs.sentry.io/cli/dif/\#creating-a-source-bundle) + +Run the `debug-files bundle-jvm` command to create a source bundle for a source directory. + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files bundle-jvm \ + --output some/dir \ + --debug-id A_VALID_UUID \ + path/to/source/dir + +``` + +You must provide the UUID of the source bundle for the Java/Android SDK to send. More details can be found in the [Source Context](https://docs.sentry.io/platforms/java/source-context/#manually-uploading-source-context) docs for Java and the [Source Context](https://docs.sentry.io/platforms/android/enhance-errors/source-context/#manually-uploading-source-context) docs for Android. + +### [Uploading a Source Bundle](https://docs.sentry.io/cli/dif/\#uploading-a-source-bundle) + +The `debug-files upload` command allows you to upload the source bundle you created to Sentry. + +Bash + +`` + +```bash code-highlight +sentry-cli debug-files upload \ + --type jvm \ + output/path/of/bundle-jvm/command + +``` + +After the upload, Sentry will attach Source Context to future events. + +To make sure these steps worked, check **Project Settings > Debug Files** in Sentry.io to see if the uploaded source bundle files are listed. + +[Previous\\ +\\ +Release Management](https://docs.sentry.io/cli/releases) + +[Next\\ +\\ +Sending Events](https://docs.sentry.io/cli/send-event) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/dif.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Search](https://docs.sentry.io/concepts/search/) +- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) +- [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events/) + +# Event Properties + +## Learn more about searchable event properties. + +Events are the underlying event data captured using Sentry SDKs — that is, errors and transactions. + +You can search by event properties in the following [sentry.io](https://sentry.io/) pages: + +- Discover - in the query builder (depending on the dataset selection) +- Dashboards - within the widget builder (depending on dataset selection) +- Performance - only in transaction summaries +- Issues - as indicated in the list below +- Alerts - when creating a metric alert + +Please note that in Alerts only a limited number of properties are available for [filtering transaction events](https://docs.sentry.io/product/alerts/create-alerts/metric-alert-config/#tags--properties). + +When searching on event properties within the **Issues** page, the search will return any issue that has _one or more events_ matching the supplied event properties filter. + +## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/events/\#searchable-properties) + +Below is a list of keys and tokens that can be used in the event search. + +### [`apdex(threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#apdexthreshold) + +Returns results with the [Apdex score](https://docs.sentry.io/product/insights/overview/metrics/#apdex) that you entered. Values must be between `0` and `1`. Higher apdex values indicate higher user satisfaction. + +- **Type:** number + +### [`app.in_foreground`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#appin_foreground) + +Indicates if the app is in the foreground or background. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`avg(field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#avgfield) + +Returns results with matching averages for the field selected. The field can be either a number or a duration. Typically used with a comparison operator. + +- **Type:** matches field + +### [`count_if(column,operator,value)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_ifcolumnoperatorvalue) + +Returns results with a matching count that satisfy the condition passed to the parameters of the function. + +- **Type:** number + +### [`count_miserable(field,threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_miserablefieldthreshold) + +Returns results with a matching count of unique instances of the field that fall above the miserable threshold. + +- **Type:** number + +### [`count_unique(field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_uniquefield) + +Returns results with a matching count of the unique instances of the field entered. + +- **Type:** number + +### [`count_web_vitals(vital,threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_web_vitalsvitalthreshold) + +Returns results with a matching count that meet a Web Vitals quality threshold ( `poor`, `meh`, `good`, or `any`). + +- **Type:** number + +### [`count()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count) + +Returns results with a matching count. (Same as `timesSeen` in issue search.) Doesn't take a parameter. + +- **Type:** number + +### [`culprit`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#culprit) + +Deprecated + +- **Type:** string + +### [`device.arch`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicearch) + +CPU architecture + +- **Type:** string + +### [`device.battery_level`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicebattery_level) + +If the device has a battery, this can be a floating point value defining the battery level (in the range 0-100). + +- **Type:** string + +### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicebrand) + +Brand of the device + +- **Type:** string + +### [`device.charging`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicecharging) + +Whether the device was charging or not. Not a boolean. + +- **Type:** string + +### [`device.class`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceclass) + +The estimated performance class of the client device, estimated `high`, `medium`, or `low`. For more details, see the [Device Classification](https://docs.sentry.io/concepts/search/searchable-properties/events/#device-classification) section below. + +- **Type:** string + +### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicefamily) + +Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. + +- **Type:** string + +### [`device.locale`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicelocale) + +Deprecated + +- **Type:** string + +### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicename) + +Details of the device + +- **Type:** string + +### [`device.online`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceonline) + +Whether the device was online or not. A string that is either `True` or `False`. + +- **Type:** string + +### [`device.orientation`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceorientation) + +Describes the orientation of the device and can be either `portrait` or `landscape`. + +- **Type:** string + +### [`device.screen_density`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_density) + +Device screen density in pixels. + +- **Type:** string + +### [`device.screen_dpi`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_dpi) + +Number of dots per inch of the device screen. + +- **Type:** string + +### [`device.screen_height_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_height_pixels) + +Device screen height in pixels. + +- **Type:** string + +### [`device.screen_width_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_width_pixels) + +Device screen width in pixels. + +- **Type:** string + +### [`device.simulator`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicesimulator) + +Indicates whether this device is a simulator or a real device. A string that is either `True` or `False`. + +- **Type:** string + +### [`device.uuid`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceuuid) + +Deprecated + +- **Type:** UUID + +### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#dist) + +Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. + +- **Type:** string + +### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#environment) + +Refers to your code deployment naming convention. For example, _development_, _testing_, _staging_ and so on. [Learn more](https://docs.sentry.io/product/sentry-basics/environments/).In some pages of [sentry.io](https://sentry.io/), you filter on environment using a dropdown. + +- **Type:** string + +### [`epm()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#epm) + +Returns results with a matching events-per-minute count. Doesn't take a parameter. + +- **Type:** number + +### [`eps()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#eps) + +Returns results with a matching events-per-second count. Doesn't take a parameter. + +- **Type:** number + +### [`error.handled`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorhandled) + +Indicates whether the user has handled the exception — for example, using try...catch. An error is considered handled if all stack traces handle the error. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`error.main_thread`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errormain_thread) + +Indicates if the error occurred on the main thread. Values are `1/0` or `true/false` + +- **Type:** boolean + +### [`error.mechanism`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errormechanism) + +An object describing the mechanism that created this exception. + +- **Type:** array + +### [`error.type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errortype) + +The type of exception. For example, `ValueError`. + +- **Type:** array + +### [`error.unhandled`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorunhandled) + +The inversion of `error.handled`. + +- **Type:** boolean + +### [`error.value`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorvalue) + +Original value of a field that causes or exhibits the error. + +- **Type:** array + +### [`event.type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#eventtype) + +Type of the event (transaction, error, default, csp, and so on). The transaction type is unavailable in **Issues**. + +- **Type:** string + +### [`failure_count()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#failure_count) + +Returns results with a matching count of events with a `transaction.status` value that's in the list of failing ones. Values can be: `ok`, `cancelled`, `unknown`. Doesn't take a parameter. + +- **Type:** number + +### [`failure_rate()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#failure_rate) + +Returns results with a matching rate of failing transactions — that is, `failure_count()` divided by the `count()` (total count). Doesn't take a parameter. + +- **Type:** number + +### [`geo.city`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#geocity) + +Full name of the city + +- **Type:** string + +### [`geo.country_code`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#geocountry_code) + +ISO 3166-1 country code + +- **Type:** string + +### [`geo.region`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#georegion) + +Full name of the country + +- **Type:** string + +### [`has`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#has) + +Returns results with the defined tag or field, but not the value of that tag or field. For example, entering `has:user` would find events with the `user` tag. + +- **Type:** error + +### [`http.method`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpmethod) + +HTTP method of the [request](https://develop.sentry.dev/sdk/data-model/event-payloads/request/) that created the event. + +- **Type:** string + +### [`http.referer`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpreferer) + +Identifies the web page from which the resource was requested. + +- **Type:** string + +### [`http.status_code`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpstatus_code) + +HTTP status code, which indicates whether a response was successful. For example, `200` or `404`. + +- **Type:** string + +### [`http.url`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpurl) + +Full URL of the request that caused the error, but without any parameters + +- **Type:** string + +### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#id) + +The event id. In **Issues**, use only the ID value without the `id` key. + +- **Type:** UUID + +### [`issue`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#issue) + +The short issue code, for example `SENTRY-ABC`. + +- **Type:** string + +### [`last_seen()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#last_seen) + +Datetime when the event was last seen. Equivalent to `max(timestamp)`. Doesn't take a parameter. + +- **Type:** datetime + +### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#level) + +Severity of the event (such as: fatal, error, warning). Always set to info for transactions. + +- **Type:** string + +### [`location`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#location) + +Location where the error happened. + +- **Type:** string + +### [`max(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#maxnumeric-field) + +Returns results with a matching maximum value for the field entered. + +- **Type:** matches field + +### [`measurements.app_start_cold`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsapp_start_cold) + +A [cold start](https://docs.sentry.io/product/insights/mobile/mobile-vitals/app-starts/) refers to when the app launches for the first time after a reboot or update. The app is not in memory and no process exists. + +- **Type:** duration + +### [`measurements.app_start_warm`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsapp_start_warm) + +A [warm start](https://docs.sentry.io/product/insights/mobile/mobile-vitals/app-starts/) refers to when the app has already launched at least once and is partially in memory. For instance, the user backs out of your app, but then re-launches it. The process may have continued to run, but the app must recreate the activity from scratch. + +- **Type:** duration + +### [`measurements.cls`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementscls) + +[Cumulative Layout Shift (CLS)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#cumulative-layout-shift-cls) is the sum of individual layout shift scores for every unexpected element shift during the rendering process. + +- **Type:** number + +### [`measurements.fcp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfcp) + +[First Contentful Paint (FCP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-contentful-paint-fcp) measures the time for the first content to render in the viewport. + +- **Type:** duration + +### [`measurements.fid`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfid) + +[First Input Delay (FID)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-input-delay-fid) measures the response time when the user tries to interact with the viewport. + +- **Type:** duration + +### [`measurements.fp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfp) + +[First Paint (FP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-paint-fp) measures the amount of time the first pixel takes to appear in the viewport, rendering any visual change from what was previously displayed. + +- **Type:** duration + +### [`measurements.frames_frozen`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_frozen) + +[Slow and frozen frames](https://docs.sentry.io/product/insights/mobile/mobile-vitals/#slow-and-frozen-frames) measure the responsiveness of your app. + +- **Type:** number + +### [`measurements.frames_frozen_rate`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_frozen_rate) + +Returns results with a matching rate of frozen frames. That is, `measurements.frames_frozen` divided by the `measurements.frames_total`. + +- **Type:** number + +### [`measurements.frames_slow`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_slow) + +[Slow and frozen frames](https://docs.sentry.io/product/insights/mobile/mobile-vitals/#slow-and-frozen-frames) measure the responsiveness of your app. + +- **Type:** number + +### [`measurements.frames_slow_rate`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_slow_rate) + +Returns results with a matching rate of slow frames. That is, `measurements.frames_slow` divided by the `measurements.frames_total`. + +- **Type:** number + +### [`measurements.frames_total`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_total) + +Returns results with a matching total number of frames. + +- **Type:** number + +### [`measurements.lcp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementslcp) + +[Largest Contentful Paint (LCP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#largest-contentful-paint-lcp) measures the render time for the largest content to appear in the viewport. + +- **Type:** duration + +### [`measurements.stall_count`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_count) + +A [stall](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is when the JavaScript event loop takes longer than expected to complete. Only applies to React Native. + +- **Type:** number + +### [`measurements.stall_longest_time`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_longest_time) + +The [longest stall time](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is the time, in milliseconds, of the longest event loop stall. Only applies to React Native. + +- **Type:** duration + +### [`measurements.stall_percentage`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_percentage) + +Stall percentage is equal to the `stall_total_time` divided by the `transaction.duration`. Only applies to React Native. + +- **Type:** number + +### [`measurements.stall_total_time`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_total_time) + +The [total stall time](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is the total combined time, in milliseconds, of all stalls. Only applies to React Native. + +- **Type:** duration + +### [`measurements.ttfb`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsttfb) + +[Time To First Byte (TTFB)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#time-to-first-byte-ttfb) measures the time that it takes for a user's browser to receive the first byte of page content. + +- **Type:** duration + +### [`measurements.ttfb.requesttime`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsttfbrequesttime) + +The time between start of the request and start of the response (see [diagram](https://web.dev/ttfb/#what-is-ttfb)). + +- **Type:** duration + +### [`message`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#message) + +Returns errors with the matching message or transactions with matching transaction name. Also matches on any message containing the supplied value.Searching `message:undefined` will match an event with a message of `undefined is not an object`. Raw text searches (searches without the `message` key) are also checked against this field. For errors, the message can be a concatenatenation of elements, so searches might include unexpected results. + +- **Type:** string + +### [`min(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#minnumeric-field) + +Returns results with a matching minimum value for the field entered. + +- **Type:** matches field + +### [`os.build`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osbuild) + +The internal build revision of the operating system. + +- **Type:** string + +### [`os.kernel_version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#oskernel_version) + +The independent kernel version string. This is typically the entire output of the `uname` syscall. + +- **Type:** string + +### [`os.distribution_name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osdistribution_name) + +The Linux distribution name. This maps to `ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). + +- **Type:** string + +### [`os.distribution_version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osdistribution_version) + +The Linux distribution version. This maps to `VERSION_ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). + +- **Type:** string + +### [`percentile(field,level)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#percentilefieldlevel) + +Returns results with an approximate percentile of the field to the level. The level can be between `0` and `1`. For example, if you wanted to find the 50th percentile of transaction durations, you would enter `percentile(transaction.duration, 0.5)`. + +- **Type:** number + +### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#platform) + +Name of the platform. This defaults to `other` and is only a property for platforms from this list: `as3`, `c`, `cfml`, `cocoa`, `csharp`, `elixir`, `go`, `groovy`, `haskell`, `java`, `javascript`, `native`, `node`, `objc`, `other`, `perl`, `php`, `python`, `ruby` + +- **Type:** string + +### [`project`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#project) + +The name of the project. In some pages of [sentry.io](https://sentry.io/), you can also filter on project using a dropdown. + +- **Type:** string + +### [`project.id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#projectid) + +The id of the project. + +- **Type:** number + +### [`pXY(duration field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#pxyduration-field) + +Returns results with an approximate percentile of the field. Replace "XY" with 50, 75, 95, 99, or 100. For example, if you wanted to find the 50th percentile of transaction durations, you would enter `p50(transaction.duration)`. + +- **Type:** number + +### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#release) + +A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). + +- **Type:** string + +### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasebuild) + +The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** number + +### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasepackage) + +The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasestage) + +The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). + +- **Type:** string + +### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releaseversion) + +A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). + +- **Type:** string + +### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sdkname) + +Name of the Sentry SDK that sent the event. + +- **Type:** string + +### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sdkversion) + +Version of the Sentry SDK that sent the event. + +- **Type:** string + +### [`spans.browser`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansbrowser) + +Cumulative browser time for a transaction, based on the span operations. + +- **Type:** duration + +### [`spans.db`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansdb) + +Cumulative db time for a transaction, based on span operations. + +- **Type:** duration + +### [`spans.http`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spanshttp) + +Cumulative http time for a transaction, based on span operations. + +- **Type:** duration + +### [`spans.resource`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansresource) + +Cumulative resource time for a transaction, based on span operations. + +- **Type:** duration + +### [`spans.ui`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansui) + +Cumulative UI time for a transaction, based on span operations. + +- **Type:** duration + +### [`stack.abs_path`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackabs_path) + +The absolute path to the source file. In events, this is an array; in issues, this is a single value. + +- **Type:** array, single value + +### [`stack.colno`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackcolno) + +Column number of the call, starting at 1. + +- **Type:** array + +### [`stack.filename`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackfilename) + +The path to the source file relative to the project root directory. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.function`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackfunction) + +Name of the function being called. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.in_app`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackin_app) + +Indicates whether a frame is related to the execution of the relevant code in the stack trace. For example, the frames that might power the framework’s web server of your app are probably not relevant. However, calls to the framework’s library once you start handling code likely are relevant. Values can be `1` (true) or `0` (false). + +- **Type:** array + +### [`stack.lineno`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stacklineno) + +Line number of the call, starting at 1. + +- **Type:** array + +### [`stack.module`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackmodule) + +Platform-specific module path. For example, `sentry.interfaces.Stacktrace`. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`stack.package`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackpackage) + +The "package" the frame was contained in. Depending on the platform, this can be different things. For C#, it can be the name of the assembly. For native code, it can be the path of the dynamic library or something else. In events, this is an array. In issues, this is a single value. + +- **Type:** array, single value + +### [`sum(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sumnumeric-field) + +Returns results with a matching total value for the the field entered. + +- **Type:** matches field + +### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestamp) + +The finish timestamp of the transaction. Returns events with matching datetime. + +- **Type:** datetime + +### [`timestamp.to_day`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestampto_day) + +Timestamp rounded down to the nearest day. + +- **Type:** datetime + +### [`timestamp.to_hour`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestampto_hour) + +Timestamp rounded down to the nearest hour. + +- **Type:** datetime + +### [`title`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#title) + +Title of the error or the transaction name. + +- **Type:** string + +### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#trace) + +A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. + +- **Type:** UUID + +### [`trace.parent_span`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#traceparent_span) + +Span ID of the parent to the current transaction. This is null if the transaction is root. + +- **Type:** UUID + +### [`trace.span`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#tracespan) + +Span ID of the root span of the root transaction in the event. + +- **Type:** UUID + +### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transaction) + +For [transactions](https://docs.sentry.io/product/insights/overview/transaction-summary/#what-is-a-transaction), the name of the transaction. For errors, the name of the associated transaction. + +- **Type:** string + +### [`transaction.duration`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionduration) + +Duration, in milliseconds, of the transaction. + +- **Type:** duration + +### [`transaction.op`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionop) + +Short code identifying the [type of operation](https://develop.sentry.dev/sdk/performance/span-operations/) the span is measuring. + +- **Type:** string + +### [`transaction.status`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionstatus) + +Describes the status of the span/transaction. Check out our [Transaction Payloads documentation](https://develop.sentry.dev/sdk/data-model/event-payloads/transaction/) for all possible statuses. + +- **Type:** string + +### [`unreal.crash_type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#unrealcrash_type) + +The [Unreal Crash Context Type](https://docs.unrealengine.com/4.27/en-US/API/Runtime/Core/GenericPlatform/ECrashContextType/) + +- **Type:** string + +### [`user_misery(number)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#user_miserynumber) + +Returns transactions with the defined user misery value. [User Misery](https://docs.sentry.io/product/insights/overview/metrics/#user-misery) is a user-weighted performance metric that counts the number of unique users who were frustrated; "frustration" is measured as a response time four times the satisfactory response time threshold (in milliseconds). It highlights transactions that have the highest impact on users. + +- **Type:** number + +### [`user.display`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userdisplay) + +In order, the first available user field available: email, then username, ID, and then IP address. + +- **Type:** string + +### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#useremail) + +An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. + +- **Type:** string + +### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userid) + +Application-specific internal identifier for the user. + +- **Type:** string + +### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userip) + +User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. + +- **Type:** string + +### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userusername) + +Username, which is typically a better label than the `user.id`. + +- **Type:** string + +[Previous\\ +\\ +Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues) + +[Next\\ +\\ +Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/events.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Authentication](https://docs.sentry.io/organization/authentication/) +- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) +- [Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso/) + +# Azure Active Directory SSO + +## Set up Azure Active Directory single sign-on (SSO) on Sentry. + +## [Installation](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#installation) + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. + +01. Log in to the [Azure portal](https://portal.azure.com/). + +02. Under "Manage Azure Active Directory" (the picture of the shield), click "View". This takes you to the **Organization Overview** page. + +03. If you don't require a permission group for Sentry, skip to Step 5. + +04. In the search bar, search for "Groups" then navigate to it. From there, create a new group, add an owner and members to the group. Set "Group type" to Office 365. For more details about group creation, see the [Azure docs](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-groups-create-azure-portal). + +05. Return to the **Overview** page. In the search bar, enter `Enterprise Applications`, then navigate to it. Click "+ New application". Search for `Sentry` to create the application. + + [![Sentry in Azure Gallery](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-search-sentry-3NIHTCLW.png%232356x1102&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-search-sentry-3NIHTCLW.png) + +06. Once the application is created, you'll be directed to **Sentry - Overview**. + + [![Sentry Overview](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-sentry-overview-GRUHFUC4.png%231500x741&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-sentry-overview-GRUHFUC4.png) + +07. Click on "1. Assign users and groups", then "+ Add user". Add yourself and the group you've created to the Sentry app. Click "Assign". + +08. Navigate back to **Overview**, click on "2. Set up single sign-on" and then select SAML as your single sign-on method. + +09. For Section (1), labeled "Basic SAML Configuration", enter the following data in each line and save your changes. + + + - Identifier (Entity ID): `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` Ensure that the URL includes a trailing slash to prevent Azure from throwing a misconfiguration error (AADSTS650056). + + - Reply URL (Assertion Consumer Service URL): `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` + + - Sign on URL: `https://sentry.io/auth/login/YOUR_ORG_SLUG/` + + - Relay State: `https://sentry.io/organizations/YOUR_ORG_SLUG/` + + - Logout URL: `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` + + +[![SAML Configuration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-basic-saml-configuration-MXFOQTUE.png%231500x369&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-basic-saml-configuration-MXFOQTUE.png) + +10. In Section (3), labeled "SAML Signing Certificate", copy the "App Federation Metadata URL". + + [![SAML Signing Certificate](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-saml-signing-certificate-SLHMLERE.png%232788x889&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-saml-signing-certificate-SLHMLERE.png) + +11. Navigate to your **Org Settings > Auth** (or go to `https://sentry.io/settings/YOUR_ORG_SLUG/auth/`) and click on "Configure" for Active Directory. + +12. Paste the App Federation Metadata URL from above and click "Get Metadata". + +13. In the next page, enter the following keys in their respective fields to map the attributes from AzureAD to Sentry, and then save them. + + + - IdP User ID: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` + + - User Email: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` + + - First Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` + + - Last Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` + + +For more details about mappings for custom configs, see [The Role of Claims](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/the-role-of-claims). + +[![Map Identity with provider attributes](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-map-identity-provider-attributes-UPSWPTFR.png%231500x1414&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-map-identity-provider-attributes-UPSWPTFR.png) + +14. Sentry will attempt to authenticate and link your account with Azure. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can take the following actions: + + - You can share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. + + - Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Azure Active Directory. + + - Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. + + - If you made changes, click "Save Settings" to complete your setup. + +## [SCIM Integration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#scim-integration) + +This feature is only available if your organization is on a Business or Enterprise plan; it is not available on Trial plans. + +If you change your organization slug, you'll need to make the same update in the steps where you enter the SCIM configuration values. + +Sentry users can manage provisioning using Azure with SCIM. You'll need to have Azure SSO set up and configured for your organization already. Sentry supports User and Group provisioning with Azure. + +### [Sentry Configuration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#sentry-configuration) + +1. Sign in to [sentry.io](https://sentry.io/). Select **Settings > Auth** + +[![Sentry Okta SCIM Auth Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-settings-auth-I7AT2EWD.png%232688x1428&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-settings-auth-I7AT2EWD.png) + +2. Under General Settings select "Enable SCIM", then "Save Settings" + +[![Sentry Enable SCIM Instruction](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-enable-sentry-7WE3LMJ5.png%231542x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-enable-sentry-7WE3LMJ5.png) + + - Sentry will display "SCIM Information" that contains your Auth Token and SCIM Base URL. + + [![SCIM Credentials Fields](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-sentry-fields-Q4U5PUUE.png%231504x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-sentry-fields-Q4U5PUUE.png) + +### [Azure Configuration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#azure-configuration) + +1. Log in to the [Azure portal](https://portal.azure.com/). + +2. In your Azure portal, navigate to **Enterprise applications** in the sidebar. + +3. Select the existing Sentry application. + +4. Select "Provisioning" from the "Manage" menu. [![Azure Provisioning Selection](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-scim-provisioning-5EP5PCMZ.png%23400x422&w=828&q=75)](https://docs.sentry.io/mdx-images/azure-scim-provisioning-5EP5PCMZ.png) + +5. Set "Provisioning Mode" to "Automatic". + +6. Use the values from your Sentry SCIM configuration to enter your SCIM URL in the "Tenant URL" field and your SCIM Auth token in the "Secret Token" field. + +7. Select "Test Connection" and wait for the message that confirms that the credentials are authorized to enable provisioning. + +[![Azure Test SCIM Connection](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-scim-test-connection-MGBJPVJF.png%231484x1078&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-scim-test-connection-MGBJPVJF.png) + + +We recommend that you select the option to "Send an email notification when a failure occurs". + +As a result of these changes, users who are assigned will be sent an invitation email. When a user is un-assigned, their membership object in Sentry will be deleted. + +You can use Use Group Provisioning to sync and assign groups in Azure; they will be reflected in Sentry teams. + +Please see the [Microsoft AD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/sentry-provisioning-tutorial) for further documentation on Azure provisioning setup. If you are using a custom enterprise application, you **must** follow the instructions for only enabling attribute mappings that Sentry supports (Step 5). + +[Previous\\ +\\ +Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) + +[Next\\ +\\ +Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/azure-sso.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) +- [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/) + +# Stack Trace Rules + +## Learn how to use stack trace rules to group incoming events based on matchers. + +This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. + +Stack trace rules improve issue tracking by ensuring accurate grouping and better classification of stack frames as in-app or system. This helps focus on relevant code, reduces noise, and minimizes false positives. By tailoring rules to your project, you can streamline debugging and maintain consistency across teams or multiple applications. + +When you set stack trace rules (previously known as _grouping enhancements_) for grouping in Sentry, they influence the data that's fed into the grouping algorithm. These rules can be configured on a per-project basis by going to your project settings and then clicking on "Issue Grouping". + +Here are a few things to note about stack trace rules: + +- Each rule is written on a single line. +- Rules consist of one or more match expressions followed by one or more actions triggered when all expressions match. +- Rules are applied sequentially, from top to bottom, across all frames in the stack trace. + +In addition, the stack trace rules using the below matchers and actions can also be applied to incoming profiles to improve frame classification (in-app vs system, for example). + +Allowed Matchers: + +- `stack.abs_path` +- `stack.module` +- `stack.function` +- `stack.package` + +Allowed Actions: + +- `+app` +- `-app` + +The syntax for stack trace rules is similar to: + +Enhancement Rules + +`` + +```bash code-highlight +matcher-name:expression other-matcher:expression ... action1 action2 ... + +``` + +If you want to negate the match, prefix the expression with an exclamation mark ( `!`). If a line is prefixed with a hash ( `#`), it's ignored and treated as a comment. + +The following is a practical example of how this looks: + +Enhancement Rules + +`` + +```bash code-highlight +# mark all functions in the std namespace to be outside the app +family:native stack.function:std::* -app + +# mark all code in node modules not to be in app +stack.abs_path:**/node_modules/** -app + +# remove all generated javascript code from all grouping +stack.abs_path:**/generated/**.js -group + +``` + +## [Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#matchers) + +Multiple matchers can be defined in a line. The following matchers are available: + +### [`family`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#family) + +Matches on the general platform family, which currently includes `javascript`, `native` and `other`. Comma separate rules to apply them to multiple platforms. + +Match multipleMatch only JavaScriptMatch only native + +`` + +```bash code-highlight +family:javascript,native stack.abs_path:**/generated/** -group + +``` + +### [`stack.abs_path`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackabs_path) + +alias: `path` + +This matcher is case insensitive with Unix glob behavior on a path in a stack trace. The path separators are normalized to `/`. As a special rule, if the filename is relative, it still matches on `**/`. + +Enhancement Rules + +`` + +```bash code-highlight +# match on all files under `project` with a `.c` extension +stack.abs_path:**/project/**.c +app + +# matches on vendor/foo without sub folders +stack.abs_path:**/vendor/foo/*.c -app + +# matches on `foo.gen.c` as well as `foo/bar.gen.c`. +stack.abs_path:**/*.gen.c -group + +``` + +### [`stack.module`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackmodule) + +alias: `module` + +Module is similar to `path` but matches on the `module`. This is not used for Native but it is used for JavaScript, Python, and similar platforms. Matches are case-sensitive, and normal globbing is available. Note that modules are not packages, which can be confusing for Native environments. + +### [`stack.function`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackfunction) + +alias: `function` + +Matches on a function in a stack trace, and is case-sensitive with normal globbing. + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:myproject_* +app +stack.function:malloc -group + +``` + +### [`stack.package`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackpackage) + +alias: `package` + +Matches on a package in a stack trace. The package is the container that contains a function or module. This is a `.jar`, a `.dylib` or similar. The same matching rules as for `path` apply. For example, this is typically an absolute path. + +Enhancement Rules + +`` + +```bash code-highlight +stack.package:**/libcurl.dylib -group + +``` + +### [`app`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#app) + +Matches on the current state of the in-app flag of a stack trace frame. `yes` means the frame is in-app, `no` means it's not. + +### [`category`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#category) + +Matches on a [built-in](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/#built-in-categories) or a user-defined frame category. See [variable actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/#variable-actions) on how to set a category. + +Category Match + +`` + +```bash code-highlight +category:telemetry -group + +``` + +#### [Built-in Categories](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#built-in-categories) + +Frame categorization is heavily used by our newest grouping algorithm. You can match on a variety of categories, including: + +- `system` \- detected system libraries +- `std` \- detected standard libraries +- `ui` \- UI frameworks +- `driver` \- graphics drivers, and so on +- `telemetry` \- crash reporting and analytics frameworks + +See [our source code](https://github.com/getsentry/sentry/blob/master/src/sentry/grouping/enhancer/enhancement-configs/mobile%402021-04-02.txt) for a full list of built-in categories. + +### [Matching Sibling Frames](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#matching-sibling-frames) + +If information about the surrounding frames is necessary to apply a rule to a frame, use caller/callee matching syntax. For example: + +Sibling matches + +`` + +```bash code-highlight +# Ignore in-app frames if they are called by telemetry +[ category:telemetry ] | app:yes -group + +# Ignore system frames if they call app frames +category:system | [ app:yes ] -group + +``` + +## [Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#actions) + +There are two types of **actions**: flag and variables setting. + +### [Flag Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#flag-actions) + +A _flag_ identifies the action to be taken if all matchers match, and it uses these prefixes: + +- `+` sets the flag +- `-` unsets the flag +- `^` applies to frames above the matching frame (toward the crash) +- `v` applies to frames below the matching frame (away from the crash) + +As an example, `-group ^-group` removes the matching frame and all frames above it from the grouping. + +- `app`: marks or unmarks a frame in-app +- `group`: adds or removes a frame from grouping + +### [Variable Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#variable-actions) + +A limited set of _variables_ can be defined ( `variable=value`): + +- `max-frames`: Sets the total number of frames to be considered for grouping. The default is `0`, which means "all frames". If set to `3`, only the top three frames are considered. + +### [Example](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#example) + +Enhancement Rules + +`` + +```bash code-highlight +stack.abs_path:**/node_modules/** -group +stack.abs_path:**/app/utils/requestError.jsx -group +stack.abs_path:**src/getsentry/src/getsentry/** +app + +family:native max-frames=3 + +stack.function:fetchSavedSearches v-group +stack.abs_path:**/app/views/**.jsx stack.function:fetchData ^-group + +family:native stack.function:SpawnThread v-app -app +family:native stack.function:_NSRaiseError ^-group -app +family:native stack.function:std::* -app +family:native stack.function:core::* -app + +``` + +## [Recommendations](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#recommendations) + +These recommendations will greatly improve your out-of-the-box grouping experience. + +### [Mark in-app Frames](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#mark-in-app-frames) + +To proactively improve your experience, help Sentry determine which frames in your stack trace are "in-app" (part of your own application) and which are not. The SDK defines the default rules, but in many cases, this can be improved on the server as well. In particular, for languages where server-side processing is necessary (for example, Native C, C++, or JavaScript), it's better to override this on the server. + +For instance, the following marks all frames that are below a specific C++ namespace are in-app: + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:myapplication::* +app + +``` + +See [in-app frames for Apple](https://docs.sentry.io/platforms/apple/usage/in-app-frames/) to find out how the `sentry-cocoa` SDK marks frames as in-app. + +#### [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stack-trace-rules) + +The following marks frames from libdispatch starting with `_dispatch_` as `inApp`. + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:_dispatch_* +app + +``` + +You can also achieve the same result by marking other frames "not in-app." However, if that's the case, you should ensure that first all frames are set to "in-app" to override the defaults: + +Enhancement Rules + +`` + +```bash code-highlight +app:no +app +stack.function:std::* -app +stack.function:boost::* -app + +``` + +You need to force all frames to be in-app first because there might already have been some defaults set by the client SDK or earlier processing. + +If you're using the `sentry-cocoa` SDK, you can also achieve the same result by marking other frames `not inApp`. The following sample marks functions from the classes `DataRequest` and `DownloadRequest` as `not inApp`. + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:DataRequest* -app +stack.function:DownloadRequest* -app + +``` + +### [Cut Stack Traces](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#cut-stack-traces) + +In many cases, you want to remove the top or bottom of the stack trace. For instance, many code bases use a common function to generate an error. In this case, the error machinery will appear as part of the stack trace. + +For example, if you use Rust, you likely want to remove some frames that are related to panic handling: + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:std::panicking::begin_panic ^-app -app ^-group -group +stack.function:core::panicking::begin_panic ^-app -app ^-group -group + +``` + +Here we tell the system that all frames from `begin-panic` to the crash location are not part of the application (including the panic frame itself). All frames above are, in all cases, irrelevant for grouping. + +Likewise, you can also remove the base of a stack trace. This is particularly useful if you have different main loops that drive an application: + +Enhancement Rules + +`` + +```bash code-highlight +stack.function:myapp::LinuxMainLoop v-group -group +stack.function:myapp::MacMainLoop v-group -group +stack.function:myapp::WinMainLoop v-group -group + +``` + +### [Stack Trace Frame Limits](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stack-trace-frame-limits) + +This isn't useful for _all_ projects, but it can work well for large applications with many crashes. The default strategy is to consider most of the stack trace relevant for grouping. This means that every different stack trace that leads to a crashing function will cause a different group to be created. If you do not want that, you can force the groups to be much larger by limiting how many frames should be considered. + +For instance, if any of the frames in the stack trace refer to a common external library, you could tell the system only to consider the top N frames: + +Enhancement Rules + +`` + +```bash code-highlight +# always only consider the top 1 frame for all native events +family:native max-frames=1 + +# if the bug is in proprietarymodule.so, only consider top 2 frames +family:native stack.package:**/proprietarymodule.so max-frames=2 + +# these are functions we want to consider much more of the stack trace for +family:native stack.function:KnownBadFunction1 max-frames=5 +family:native stack.function:KnownBadFunction2 max-frames=5 + +``` + +[Previous\\ +\\ +Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules) + +[Next\\ +\\ +Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/stack-trace-rules.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Sentry CLI](https://docs.sentry.io/cli/) +- [Crons (CLI)](https://docs.sentry.io/cli/crons/) + +# Crons (CLI) + +## Follow this guide to set up and manage monitors using the Sentry CLI. + +##### Deprecation Notice + +Starting with v2.16.1 of the Sentry CLI, the ability to monitor check-ins using an auth token for authorization has been deprecated. Read on to learn how to update your CLI and use your project's DSN instead. + +Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. + +## [Requirements](https://docs.sentry.io/cli/crons/\#requirements) + +To begin monitoring your recurring, scheduled job: + +- [Install](https://docs.sentry.io/cli/installation/) the Sentry CLI (min v2.16.1). +- Create and configure your first Monitor in [Sentry](https://sentry.io/crons/create/) or [via the CLI](https://docs.sentry.io/cli/crons/#creating-or-updating-a-monitor-through-a-check-in-optional). + +## [Configuration](https://docs.sentry.io/cli/crons/\#configuration) + +The Sentry CLI uses your Monitor's project DSN to authorize check-ins. To set it up, export the `SENTRY_DSN` environment variable: + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/crons/). + +Bash + +`` + +```bash code-highlight +export SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 + +``` + +Alternatively, you can add it to your `~/.sentryclirc` config: + +The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/crons/). + +Ini + +`~/.sentryclirc` + +```code-highlight ini +[auth] +dsn = https://examplePublicKey@o0.ingest.sentry.io/0 + +``` + +Learn more about the CLI's [configuration file](https://docs.sentry.io/cli/configuration/#configuration-file). + +## [Job Monitoring](https://docs.sentry.io/cli/crons/\#job-monitoring) + +Use the Sentry CLI to run your job and notify you if it doesn't start when expected (missed) or if it exceeded its maximum runtime (failed). + +CLI + +`` + +```bash code-highlight +sentry-cli monitors run <monitor_slug> -- <command> <args> + +``` + +Usage examples: + +PythonNode.JS + +`` + +```bash code-highlight +sentry-cli monitors run my-monitor-slug -- python path/to/file.py + +``` + +### [Creating or Updating a Monitor Through a Check-In (Optional)](https://docs.sentry.io/cli/crons/\#creating-or-updating-a-monitor-through-a-check-in-optional) + +You can also use the Sentry CLI to create or update your cron monitor when you run your job. This way, you can avoid having to first set up the monitor through the Sentry web interface. + +Configure the cron monitor by providing the cron schdule in crontab format using the `--schedule` or the equivalent `-s` argument when executing the `sentry cli monitors run` command. Please make sure to enclose the schedule in quotes, so that your shell parses the argument correctly, like so: + +Bash + +`` + +```bash code-highlight +sentry-cli monitors run --schedule "<expected schedule>" <monitor-slug> -- <command> <args> + +``` + +When providing the `--schedule` argument, we also support the following optional arguments to provide additional configuration: + +- `--check-in-margin`: The allowed margin of minutes after the expected check-in time that the monitor will not be considered missed for. +- `--max-runtime`: The allowed duration in minutes that the monitor may be in progress for before being considered failed due to timeout. +- `--timezone`: A valid [tz database identifier string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (e.g. "Europe/Vienna") representing the monitor's execution schedule's timezone. + +Below are some usage examples: + +Every MinuteEvery Hour (+ Optional Arguments) + +`` + +```bash code-highlight +sentry-cli monitors run -s "* * * * *" -- my-command + +``` + +### [Specifying Monitor Environments (Optional)](https://docs.sentry.io/cli/crons/\#specifying-monitor-environments-optional) + +If your cron monitor runs in multiple environments you can use the `-e` flag to specify which [Monitor Environment](https://docs.sentry.io/product/crons/job-monitoring/#multiple-environments) to send check-ins to. + +Node.JS + +`` + +```bash code-highlight +sentry-cli monitors run -e dev my-monitor-slug -- node path/to/file.js + +``` + +[Previous\\ +\\ +Sending Events](https://docs.sentry.io/cli/send-event) + +[Next\\ +\\ +API Reference](https://docs.sentry.io/api) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/crons.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [API Reference](https://docs.sentry.io/api/) +- [Paginating Results](https://docs.sentry.io/api/pagination/) + +# Paginating Results + +Pagination in the API is handled via the Link header standard: + +BashHttp + +`` + +```bash code-highlight +curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/ + +``` + +When supported, cursors will **always** be returned for both a previous and a next page, even if there are no results on these pages. This allows you to make a query against the API for yet-undiscovered results. An example where this would be used is when you're implementing polling behavior and you want to see if there is any new data. We return a `results="[true|false]"` indicator to determine if you actually need to paginate. + +## [Pagination Example](https://docs.sentry.io/api/pagination/\#pagination-example) + +Here is a pagination example using this API endpoint: + +[https://docs.sentry.io/api/events/list-an-issues-events/](https://docs.sentry.io/api/events/list-an-issues-events/) + +The HTTP request in this example returns 100 events for the issue and has the following link header in the response: + +Http + +`` + +```bash code-highlight +<https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="false"; cursor="0:0:1", <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:100:0>; rel="next"; results="true"; cursor="0:100:0" + +``` + +One of the URLs in the link response has `rel=next`, which indicates the next results page. It also has `results=true`, which means that there are more results. + +Based on this, the next request is `GET <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:100:0>`. + +This request will return the next 100 events for that issue, again, with the following link header: + +Http + +`` + +```bash code-highlight +<https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="true"; cursor="0:0:1", <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:200:0>; rel="next"; results="true"; cursor="0:200:0" + +``` + +The process is repeated until the URL with `rel=next` has the flag `results=false` to indicate the last page. + +The three values from cursor are: cursor identifier (integer, usually 0), row offset, and is\_prev (1 or 0). + +[Previous\\ +\\ +Authentication](https://docs.sentry.io/api/auth) + +[Next\\ +\\ +Permissions & Scopes](https://docs.sentry.io/api/permissions) + +- [Home](https://docs.sentry.io/) +- [Concepts & Reference](https://docs.sentry.io/concepts/) +- [Data Management](https://docs.sentry.io/concepts/data-management/) +- [Size Limits](https://docs.sentry.io/concepts/data-management/size-limits/) + +# Size Limits + +## Learn about the size limits for events and attachments, and how to avoid exceeding them. + +Sentry imposes size limits on events, attachments, requests, and various event fields. + +## [Behavior](https://docs.sentry.io/concepts/data-management/size-limits/\#behavior) + +The following describes how Sentry treats size limits: + +- Events, attachments, and requests exceeding payload size limits are immediately dropped with a `413 Payload Too Large` error. +- Sentry allows compressed content encoding, and applies separate limits before and after decompression. +- Events that exceed 200KB compressed or 1MB decompressed will be rejected. +- Minidump uploads that exceeed 20MB compressed or 100MB decompressed (for all files combined) will also be rejected. +- Event fields exceeding the individual size limits are trimmed and truncated afterwards. +- The number of events rejected due to size limits is counted towards the _Dropped_ category in [usage stats](https://docs.sentry.io/product/stats/#usage-stats). + +## [Recommendations](https://docs.sentry.io/concepts/data-management/size-limits/\#recommendations) + +To avoid using up your attachments quota — which is based on size and not number of instances of attachments data sent — or having the event dropped entirely, consider limiting the size of values passed into Sentry's APIs. For example, if your application attaches application state or request bodies to Sentry events, truncate them first. + +## [Size Limit References](https://docs.sentry.io/concepts/data-management/size-limits/\#size-limit-references) + +Sentry's exact size limits may change over time. For more information, please refer to the following resources: + +- [Envelope Size Limits](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) +- [Store Endpoint Size Limits](https://develop.sentry.dev/sdk/miscellaneous/store/#size-limits) +- [Minidump Size Limits](https://docs.sentry.io/platforms/native/guides/minidumps/#size-limits) +- [Variable Size Limits](https://develop.sentry.dev/sdk/expected-features/data-handling/#variable-size) + +[Previous\\ +\\ +Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering) + +[Next\\ +\\ +Moving to SaaS](https://docs.sentry.io/concepts/migration) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/size-limits.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) + +# Cloud Monitoring + +## Learn more about Sentry's cloud monitoring integrations. + +- [Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/) +- [Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/) +- [Google Cloud Functions - Python](https://docs.sentry.io/platforms/python/integrations/gcp-functions/) +- [Google Cloud Functions - Node](https://docs.sentry.io/platforms/javascript/guides/gcp-functions/) +- [AWS Lambda - Python (Automatic)](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) +- [AWS Lambda - Python (Manual)](https://docs.sentry.io/platforms/python/integrations/aws-lambda/) +- [AWS Lambda - Node (Automatic)](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) +- [AWS Lambda - Node (Manual)](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/) + +[Previous\\ +\\ +Compliance](https://docs.sentry.io/organization/integrations/compliance) + +[Next\\ +\\ +AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Organization Settings](https://docs.sentry.io/organization/) +- [Integrations](https://docs.sentry.io/organization/integrations/) +- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) +- [Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment/) + +# Segment + +## Learn about Sentry's Segment integration, which allows you to collect all your client-side data for Sentry automatically. + +If you make changes to your organization slug, you'll need to update your configuration for this integration. Learn more in our [troubleshooting guide](https://docs.sentry.io/organization/integrations/troubleshooting/). + +Segment is useful for collecting, responsibly managing, and integrating your customer data with many other applications, including Sentry. + +This integration needs to be set up in each project for which you wish to use it. It is maintained and supported by the [Sentry community](https://open.sentry.io/). + +## [Install and Configure](https://docs.sentry.io/organization/integrations/data-visualization/segment/\#install-and-configure) + +Sentry owner, manager, or admin permissions are required to install this integration. + +Navigate to **Settings > Integrations > Segment** + +[![Install Segment integration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsegment-WF5U76QW.png%231944x718&w=3840&q=75)](https://docs.sentry.io/mdx-images/segment-WF5U76QW.png) + +### [Data Forwarding](https://docs.sentry.io/organization/integrations/data-visualization/segment/\#data-forwarding) + +Configure [data forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) in **\[Project\] > Settings > Data Forwarding**, and provide the required information for the given integration. + +[Previous\\ +\\ +Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana) + +[Next\\ +\\ +Splunk](https://docs.sentry.io/organization/integrations/data-visualization/splunk) + + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/segment/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) +- [Contributing to Docs](https://docs.sentry.io/contributing/) +- [Our Approach](https://docs.sentry.io/contributing/approach/) +- [Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs/) +- [How to Write - Index Pages](https://docs.sentry.io/contributing/approach/product-docs/write-index/) + +# How to Write - Index Pages + +This guide to writing index pages is just that—a guide. It won’t answer every question you have about how to write a good index page, but it will help you make a good start. + +While we use the term “index page” to refer to the top-level page about a feature in Docs, we don’t use this terminology in the actual Docs. Learn more in [Other Guidelines](https://docs.sentry.io/contributing/approach/product-docs/write-index/#other-guidelines). + +The index page: + +- Explains WHAT the feature is +- Describes WHY the feature benefits the customer, without veering too far into marketing language +- Describes HOW the mechanisms of the feature help the customer achieve these benefits +- Provides easy-to-find LINKS to child pages describing the subpages of the primary feature and/or how to do things with the feature + +The index page does not: + +- Describe HOW TO do anything that can’t be described in one or two sentences; that information should be on child pages in Docs. + +## [What and Why](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#what-and-why) + +- The elevator pitch of this feature + - What the feature is and what problem it’s solving for the customer +- Two-to-five sentences + - This can be longer if you need to explain the feature as a concept before you can explain what the feature provides (for example, [Releases as a feature/concept vs the Releases page of application](https://docs.sentry.io/product/releases/)) +- A pixel perfect overview screenshot showing the feature in action + +## [How: Contained Features - Page Breakdown](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#how-contained-features---page-breakdown) + +Use this approach for a feature that doesn’t require much explanation and has distinct sections, like [Usage Stats](https://docs.sentry.io/product/stats/) \- it’s good for very contained features. + +- Describe each page section/element focusing on how it helps the customer achieve the WHY of this feature. +- Add headings describing the page section/element to make each section of text stand out, if needed. +- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries). + +## [How: Wider-Ranging Features - Benefit Breakdown](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#how-wider-ranging-features---benefit-breakdown) + +Use this approach for a page that requires more explanation to break down and/or has a lot of child pages to explain its different benefits, like [Insights](https://docs.sentry.io/product/insights/). + +- Describe how each page section/element or child page, helps the customer achieve the WHY of this feature. +- Include links to relevant child pages in the text. +- Group page sections/elements or child pages as appropriate. +- Add headings that describe the benefit rather than the page section/element like [here](https://docs.sentry.io/product/insights/overview/#analyze-performance-trends). +- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries). + +If you use this approach, you may want to include a very high-level, one- or two-sentence description of what the page looks like as part of the WHAT/WHY section. + +## [Links](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#links) + +- Create a section called “Learn More” + +- Use a `<PageGrid />` element to link to child pages for this feature + + - This displays a bullet list of page links with their front matter page descriptions + - This might require that you edit the front matter descriptions of the pages displayed in the page grid + +## [Includes](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#includes) + +You might need to use an `include` file for small pieces of reusable content, such as Early Adopter notes, plan/feature notes, or short snippets of text. These are found in [`/includes/`](https://github.com/getsentry/sentry-docs/tree/master/includes). + +## [Other Guidelines](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#other-guidelines) + +Following are some quick tips to keep in mind: + +- Refer to the feature’s main page in the application as a _page_, _home page_, or even _main page_. Do not call it an _index page_ or use _homepage_ (all one word). +- Refer to the organization as _Sentry_; refer to the UI of the application as [sentry.io](https://sentry.io/) (with lower case “s” and embedded link), not _the Sentry UI_. +- Avoid beginning sentences with [sentry.io](https://sentry.io/). +- Do not skip heading levels. Don’t use an H3 as your first sub-heading/page-level heading. The page title is considered the H1 and the next heading level that should be used after that is an H2. If you skip heading levels, the right hand sidebar menu won’t render. +- Do not add more H1 headings to the page. The title is the H1. All other headings on the page should be H2 or lower in hierarchy (that is, higher in number). + +Internal writers, refer to the [Tips for Contributors](https://www.notion.so/sentry/Tips-for-Contributors-b1997ea7f5e84eb9a02e0770b6dcc453) page for further guidance. + +[Previous\\ +\\ +Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs) + +[Next\\ +\\ +Platforms & Guides](https://docs.sentry.io/contributing/platforms) + + + +[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/product-docs/write-index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) +Copy From ad52281668c4478680affafc6043bebe6cf5c690 Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Tue, 4 Mar 2025 22:20:54 -0800 Subject: [PATCH 2/7] Moving llms.txt to correct directory for serving --- {docs => public}/llms.txt | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {docs => public}/llms.txt (100%) diff --git a/docs/llms.txt b/public/llms.txt similarity index 100% rename from docs/llms.txt rename to public/llms.txt From 71ede61be58e863ee1ca4bb6f2f21c8403668833 Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Thu, 3 Apr 2025 02:00:20 -0700 Subject: [PATCH 3/7] Adding test llms.txt files for validation --- public/llms.txt | 11758 +--------------- public/platform/javascript/common/llms.txt | 79 + .../javascript/guides/nextjs/llms.txt | 59 + .../platform/javascript/guides/react/llms.txt | 79 + 4 files changed, 222 insertions(+), 11753 deletions(-) create mode 100644 public/platform/javascript/common/llms.txt create mode 100644 public/platform/javascript/guides/nextjs/llms.txt create mode 100644 public/platform/javascript/guides/react/llms.txt diff --git a/public/llms.txt b/public/llms.txt index 49df6191cb1be..86c2e74e785fc 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,11755 +1,7 @@ -# https://docs.sentry.io/ llms.txt +Sentry llms.txt -- [Home](https://docs.sentry.io/) -- [Account Settings](https://docs.sentry.io/account/) -- [Auth Tokens](https://docs.sentry.io/account/auth-tokens/) +This llmx.txt focuses on platform specific configuration options for the major sdks, linked below. AI sdks should parse these paths to access the framework specific llm instructions. -# Auth Tokens - -## Learn about the different kinds of Auth Tokens Sentry provides, and when to use which. - -Auth tokens (short for _authentication tokens_) are a way to authenticate with Sentry. They are similar to passwords but are designed for programmatic interaction with Sentry. Some examples of what you would use auth tokens for include: - -- Uploading Source Maps during your CI build -- Using [Sentry CLI](https://docs.sentry.io/cli/) to interact with Sentry -- Using the [Sentry API](https://docs.sentry.io/api/auth/) - -Each auth token is created with a certain set of permissions and scopes which are mapped to the Sentry API's [Permissions & Scopes](https://docs.sentry.io/api/permissions/). Some types of auth tokens have set permissions that can't be edited, while others can be customized upon token creation and edited later. - -We recommend using a separate auth token for each use case. For example, you would use a different auth token to upload source maps than the one you use with Sentry CLI. This has the benefit that if an auth token is compromised, you can revoke that auth token without impacting the rest of your workflow. - -## [Types of Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#types-of-auth-tokens) - -There are three key types of auth tokens in Sentry: - -- [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens): These tokens are bound to an organization, and have access to all projects within that organization. They have a limited set of permissions and are designed to be used in CI environments and with Sentry CLI. - -- [Internal Integrations](https://docs.sentry.io/account/auth-tokens/#internal-integrations): These tokens are bound to an organization, and have access to all projects within that organization. They can be created with a custom set of permissions, and are designed to be used in cases where organization auth tokens don't have sufficient access rights. - -- [User Auth Tokens](https://docs.sentry.io/account/auth-tokens/#user-auth-tokens): These tokens are bound to a user, and have access to all organizations and projects that user has access to. - - -### [When Should I Use Which?](https://docs.sentry.io/account/auth-tokens/\#when-should-i-use-which) - -For most scenarios, we recommend using [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/#organization-auth-tokens). They are designed to be used in CI environments and have a limited set of permissions. This means that if the place you stored the auth token is compromised, the attacker can only do limited damage. - -Organization auth tokens permissions aren't customizable. They are set to allow most CI-related tasks, without any unnecessary permissions. - -[Internal Integrations](https://docs.sentry.io/account/auth-tokens/#internal-integrations) should be used when you need full API access (which the organization auth tokens cannot grant), and you want to interact with the Sentry API on behalf of an organization. For example, to programmatically create a new project, you would use an internal integration. - -Permissions for auth tokens created as part of an internal integration are customizable and editable. - -[User Auth Tokens](https://docs.sentry.io/account/auth-tokens/#user-auth-tokens) should be used to interact with the Sentry API on behalf of a user. For example, to fetch all issues for a user, you would use a user auth token. We don't recommend using user auth tokens for CI tasks because if the user who created the token is removed from the Organization, the token will stop working. - -User auth token permissions are customizable but cannot be edited later. - -### [Organization Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#organization-auth-tokens) - -[Organization auth tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) can be created in [sentry.io](https://sentry.io/) on the **Auth Tokens** page under **Settings > Developer Settings > Auth Tokens**. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-auth-tokens-overview-EVXIT75D.png%231200x562&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-auth-tokens-overview-EVXIT75D.png) - -They can also be generated on certain pages of Sentry's docs if you're signed in, and by using the Sentry Wizard to configure uploading source maps. - -Organization auth token names are generated for you unless you create the token through the Sentry UI. This name is only used for display purposes - it helps to identify an auth token in case you want to revoke it later. You can change the name for an organization auth token at [sentry.io](https://sentry.io/) on the **Edit Auth Token** page under **Settings > Developer Settings > Auth Tokens**. - -For security reasons, organization auth tokens are only visible _once_, right after you create them. If you lose the auth token, you will have to create a new one. This means you can't see the full token on the overview page or on the token detail page, you can only see the last characters of the token to help identify it. - -Any user can create organization auth tokens for any of their organizations. This allows any user (not only organization owners) to configure a Sentry SDK and set up CI processes by creating and using organization auth tokens. Since organization auth tokens have limited access, there is limited potential for abuse. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-auth-token-create-C7PVFF4S.png%231200x338&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-auth-token-create-C7PVFF4S.png) - -All owners of the organization will receive a security email when a new organization auth token is created and can revoke these tokens at any point. _Only_ organization owners & managers can revoke organization auth tokens . - -### [Internal Integrations](https://docs.sentry.io/account/auth-tokens/\#internal-integrations) - -We recommend only using an internal integration when you want to interact with the Sentry API on behalf of an organization. See Sentry's API [Authentication](https://docs.sentry.io/api/auth/) docs for more information on how to do this. - -To get started, see our docs on [Internal Integrations](https://docs.sentry.io/organization/integrations/integration-platform/). - -### [User Auth Tokens](https://docs.sentry.io/account/auth-tokens/\#user-auth-tokens) - -[User auth tokens](https://sentry.io/settings/account/api/auth-tokens/) can be created in [sentry.io](https://sentry.io/) on the **User Auth Tokens** page under the Account dropdown in the top left. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-tokens-menu-7RYBD4GV.png%23500x572&w=1080&q=75)](https://docs.sentry.io/mdx-images/user-auth-tokens-menu-7RYBD4GV.png) - -User auth tokens can be created by any user, and are bound to that user. The tokens can be given permissions to all organizations and projects that user has access to. This means a user auth token's _maximum_ scope is all the scopes that the user has access to for a given organization. A user auth token cannot exceed the permissions of the user who created it. See [Organization and User Management](https://docs.sentry.io/organization/membership/) for more details on how permissions work in Sentry. - -When you create a new user auth token, you can select which [scopes](https://docs.sentry.io/api/permissions/) the token should have in the UI: - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-token-create-ZKQIPVXA.png%232396x1404&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-token-create-ZKQIPVXA.png) - -Currently, you can view user auth tokens in the UI after creating them. This is a legacy behavior that may change in the future. We recommend only using each user auth token once, and creating a new token for each use case. Any user can always revoke any of their user auth tokens. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-tokens-overview-R7WDNH5A.png%231200x484&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-tokens-overview-R7WDNH5A.png) - -We recommend only using a user auth token to interact with the Sentry API on behalf of a user. See Sentry's API [Authentication](https://docs.sentry.io/api/auth/) docs for more information on how to do this. - -[Previous\\ -\\ -Account Preferences](https://docs.sentry.io/account/user-settings) - -[Next\\ -\\ -Organization Settings](https://docs.sentry.io/organization) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/auth-tokens/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=qzenzbb76tqy)Ship it, break it, fix it—live! Hands-on workshop debugging with Lazar. [RSVP for March 12.](https://sentry.io/resources/instrument-monitor-fix-workshop/) - -× - -# Welcome to Sentry Docs - -Sentry provides end-to-end distributed tracing, enabling developers to identify and debug performance issues and errors across their systems and services. - -![Sentry's hero image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fhome_illustration.65d91c38.png&w=3840&q=75) - -## Most Viewed Sentry SDKs - -[![javascript-nextjs icon](https://docs.sentry.io/_next/static/media/nextjs.32864a1b.svg)Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs/) - -[![javascript-react icon](https://docs.sentry.io/_next/static/media/react.bdd05676.svg)React](https://docs.sentry.io/platforms/javascript/guides/react/) - -[![php-laravel icon](https://docs.sentry.io/_next/static/media/laravel.bb692921.svg)Laravel](https://docs.sentry.io/platforms/php/guides/laravel/) - -[![javascript-node icon](https://docs.sentry.io/_next/static/media/nodejs.852a24fa.svg)Node.js](https://docs.sentry.io/platforms/javascript/guides/node/) - -[![python icon](https://docs.sentry.io/_next/static/media/python.94740f0e.svg)Python](https://docs.sentry.io/platforms/python/) - -[![react-native icon](https://docs.sentry.io/_next/static/media/react-native.29a585c0.svg)React Native](https://docs.sentry.io/platforms/react-native/) - -## All SDKs Supported by Sentry - -If you use it, we probably support it. - -![android icon](https://docs.sentry.io/_next/static/media/android.b3576036.svg)Android - -![apple icon](https://docs.sentry.io/_next/static/media/apple.e4583c4c.svg)Apple - -[![dart icon](https://docs.sentry.io/_next/static/media/dart.5c7f1c51.svg)Dart](https://docs.sentry.io/platforms/dart/) - -![elixir icon](https://docs.sentry.io/_next/static/media/elixir.7b73ceba.svg)Elixir - -[![flutter icon](https://docs.sentry.io/_next/static/media/flutter.a90468ce.svg)Flutter](https://docs.sentry.io/platforms/flutter/) - -![go icon](https://docs.sentry.io/_next/static/media/go.61b8c940.svg)Go - -[![godot icon](https://docs.sentry.io/_next/static/media/godot.27321999.svg)Godot Engine](https://docs.sentry.io/platforms/godot/) - -![java icon](https://docs.sentry.io/_next/static/media/java.acc28a20.svg)Java - -![javascript icon](https://docs.sentry.io/_next/static/media/javascript.bcdb1761.svg)JavaScript - -![kotlin icon](https://docs.sentry.io/_next/static/media/kotlin.3786f5aa.svg)Kotlin - -![native icon](https://docs.sentry.io/_next/static/media/nativec.2290b21b.svg)Native - -![dotnet icon](https://docs.sentry.io/_next/static/media/dotnet.5140e140.svg).NET - -![php icon](https://docs.sentry.io/_next/static/media/php.8ad32900.svg)PHP - -[![powershell icon](https://docs.sentry.io/_next/static/media/powershell.8794be24.svg)PowerShell](https://docs.sentry.io/platforms/powershell/) - -![python icon](https://docs.sentry.io/_next/static/media/python.94740f0e.svg)Python - -[![react-native icon](https://docs.sentry.io/_next/static/media/react-native.29a585c0.svg)React Native](https://docs.sentry.io/platforms/react-native/) - -![ruby icon](https://docs.sentry.io/_next/static/media/ruby.bdbd1ec3.svg)Ruby - -![rust icon](https://docs.sentry.io/_next/static/media/rust.2e576be7.svg)Rust - -[![unity icon](https://docs.sentry.io/_next/static/media/unity.2a861bdd.svg)Unity](https://docs.sentry.io/platforms/unity/) [![unreal icon](https://docs.sentry.io/_next/static/media/unreal.8100ceaa.svg)Unreal Engine](https://docs.sentry.io/platforms/unreal/) - -## Get to know us - -[![Rocket image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Frocket.b246cb46.png&w=128&q=75)\\ -\\ -**What is Sentry?** \\ -\\ -Application monitoring and debugging software considered “not bad” by 4 million developers.](https://docs.sentry.io/product/) [![Organization image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Forganization.8218fb60.png&w=128&q=75)\\ -\\ -**Organization settings** \\ -\\ -Information for setting up your organization's Sentry account.](https://docs.sentry.io/organization/) [![Calculator image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fpricing.ffb025fd.png&w=128&q=75)\\ -\\ -**Pricing & Billing** \\ -\\ -All about our pricing and billing structure.](https://docs.sentry.io/pricing/) [![Plug image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fapi.a101b39c.png&w=128&q=75)\\ -\\ -**API** \\ -\\ -APIs for accessing Sentry programmatically.](https://docs.sentry.io/api/) [![Terminal image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fcli.2909a9c8.png&w=128&q=75)\\ -\\ -**CLI** \\ -\\ -How to use ‘sentry-cli’ on the command line.](https://docs.sentry.io/cli/) [![Stamped paper image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fsecurity.7c52136a.png&w=128&q=75)\\ -\\ -**Security, Legal & PII** \\ -\\ -Security, compliance, and data-scrubbing processes.](https://docs.sentry.io/security-legal-pii/) [![Concept and references image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fconcepts-reference.3b9f1750.png&w=128&q=75)\\ -\\ -**Concepts & Reference** \\ -\\ -Core concepts that make Sentry, Sentry.](https://docs.sentry.io/concepts/) - -## Talk to us - -[![Chat bubble image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fchat-bubble.0c0f4dff.png&w=128&q=75)\\ -\\ -**Sentry Discord** \\ -\\ -Real talk in real time. Get in it.](https://discord.com/invite/sentry) [![Support image](https://docs.sentry.io/_next/image/?url=%2F_next%2Fstatic%2Fmedia%2Fsupport.8b7cb019.png&w=128&q=75)\\ -\\ -**Support** \\ -\\ -See how we can help.](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=mqc11j9cbcoh)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/) - -# How to Write - Data Management - -The Data Management section of the content covers how customers can manage the data sent to Sentry using the SDK. We provide a parallel section in product, which focuses on the settings in [sentry.io](http://sentry.io/) a user can user to control data. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/data-management` \- feel free to peruse the files in that directory to answer any questions. - -Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. - -Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions if any questions arise by opening an issue on GitHub. - -## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#start-here) - -Determine if the page applies: - -- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. -- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting customers open an issue for the missing sample. - -### [Sensitive Data](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#sensitive-data) - -This file is `/sensitive-data/index.mdx`. It explains how to scrub or filter data within the SDK, so it's not sent with an event. - -For data scrubbing that the guide DOES NOT support, add the name of the guide to the `PlatformSection notSupported` statement, which ensures the content won't display. For example: - -`<PlatformSection notSupported={["javascript.react"]}>` - -Add the code sample to these directories: - -- `/src/platform-includes/configuration/before-send` -- `/src/platform-includes/sensitive-data/set-tag` -- `/src/platform-includes/sensitive-data/set-user` - -### [Debug Files](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management/\#debug-files) - -This file is `/sensitive-data/debug-files.mdx`. It explains how to debug information files work for Sentry. - -For specific controls that the guide supports, add the name of the guide to the `PlatformSection supported` statement, which ensures the content displays. - -[Previous\\ -\\ -How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events) - -[Next\\ -\\ -How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-data-management.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=4uol10g7q80v)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) - -# Sentry CLI - -## Learn how to use the \`sentry-cli\` command line executable. - -For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms. - -[Previous\\ -\\ -Pricing & Billing](https://docs.sentry.io/pricing) - -[Next\\ -\\ -Installation](https://docs.sentry.io/cli/installation) - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=nvhm92pvf9r6)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data/) - -# Event Data - -## Learn about event data and how to configure Sentry workflows and tools to fine-tune the data sent to Sentry. - -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](https://docs.sentry.io/concepts/key-terms/enrich-data/\#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: - -1. **Unstructured Data** \- Includes additional data like `Breadcrumbs`, `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. - -2. **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. - - `Release` and `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](https://docs.sentry.io/concepts/key-terms/enrich-data/\#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: - -### [Alert Rules](https://docs.sentry.io/concepts/key-terms/enrich-data/\#alert-rules) - -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: - -1. **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_: [![Issue alert configuration for the example rule.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F002-TZFM5RVW.png%231484x1887&w=3840&q=75)](https://docs.sentry.io/mdx-images/002-TZFM5RVW.png) - -2. **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: - -[![Metric alert configuration for the example rule](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F006-74IB2NWA.png%231484x2090&w=3840&q=75)](https://docs.sentry.io/mdx-images/006-74IB2NWA.png) - - -Learn more in [Alerts](https://docs.sentry.io/product/alerts/). - -### [Filter, Search, and Order Issues](https://docs.sentry.io/concepts/key-terms/enrich-data/\#filter-search-and-order-issues) - -On the **Issues** page, custom data allows you to: - -- Filter issues according to your application's `environments` using the environment filter dropdown. -- Sort issues by the number of (unique) impacted `users`. -- Search through issues by your `custom tags`, `user context` attributes, and `release` ids in the issue search bar. - -[![Issues View](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F003-PA7LJBLZ.png%233403x1522&w=3840&q=75)](https://docs.sentry.io/mdx-images/003-PA7LJBLZ.png) - -Learn more in [Search](https://docs.sentry.io/concepts/search/). - -### [Discover](https://docs.sentry.io/concepts/key-terms/enrich-data/\#discover) - -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_. - -[![Discover Query](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F004-IYDNJC4S.png%232094x1416&w=3840&q=75)](https://docs.sentry.io/mdx-images/004-IYDNJC4S.png) - -Learn more in [Discover](https://docs.sentry.io/product/explore/discover-queries/). - -### [Ownership Rules](https://docs.sentry.io/concepts/key-terms/enrich-data/\#ownership-rules) - -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 `URL`, the `path` of the files in the error's stack-trace, or an error's `tag` value. - -[![Issue Owner Tag Rule](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F005-WBZFLCWC.png%231237x363&w=3840&q=75)](https://docs.sentry.io/mdx-images/005-WBZFLCWC.png) - -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](https://docs.sentry.io/product/issues/ownership-rules/). - -### [Release Workflows](https://docs.sentry.io/concepts/key-terms/enrich-data/\#release-workflows) - -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: - -1. **Commit Tracking** \- With a release in place, Sentry can track which commits were involved with a release and the authors who made them. -2. **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. -3. **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. -4. **Release Health** \- Sentry can monitor the [health](https://docs.sentry.io/product/releases/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.) - -[![Release](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2F001-J2GKUTTJ.png%231934x1302&w=3840&q=75)](https://docs.sentry.io/mdx-images/001-J2GKUTTJ.png) - -Learn more in [Releases](https://docs.sentry.io/product/releases/). - -[Previous\\ -\\ -Environments](https://docs.sentry.io/concepts/key-terms/environments) - -[Next\\ -\\ -Tracing](https://docs.sentry.io/concepts/key-terms/tracing) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/enrich-data/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=mai45p2vrhl0)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) - -# Contributing to Docs - -The Sentry documentation is a static site, generated with [Next.js](https://nextjs.org/). - -[Previous\\ -\\ -Concepts & Reference](https://docs.sentry.io/concepts) - -[Next\\ -\\ -Development Environment](https://docs.sentry.io/contributing/environment) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) - -[iframe](https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6Lck4YwlAAAAAEIE1hR--varWp0qu9F-8-emQn2v&co=aHR0cHM6Ly9kb2NzLnNlbnRyeS5pbzo0NDM.&hl=en&v=EGO3I7Q26cZ-jBw3BEtzIx7-&size=invisible&cb=7pqih7842muw)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) -- [Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) - -# Fingerprint Rules - -## Learn about fingerprint rules, matchers for fingerprinting, how to combine matchers, and using variables for fingerprinting. - -This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. - -Fingerprint rules (previously known as _server-side fingerprinting_) are also configured with a config similar to [stack trace rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/), but the syntax is slightly different. The matchers are the same, but instead of flipping flags, a fingerprint is assigned and it overrides the default grouping entirely. Assigning a fingerprint can also refine the default grouping rather than overriding it, if the fingerprint includes the value `{{ default }}`. - -These rules can be configured on a per-project basis in **\[Project\] > Settings > Issue Grouping > Fingerprint Rules**. This setting has input fields where you can write custom fingerprinting rules. To update a rule: - -1. Identify the match logic for grouping issues together. -2. Set the match logic and the fingerprint for it. - -The syntax for fingerprint rules is similar to syntax in [**Discover** queries](https://docs.sentry.io/concepts/search/#syntax). To negate a match, add an exclamation mark ( `!`) at the beginning of the expression. See the full grammar [here](https://github.com/getsentry/sentry/blob/c5b84a393365a833348dd7fd9378d34c353ca6ca/src/sentry/grouping/fingerprinting.py#L17-L55). - -Sentry attempts to match against all values that are configured in the fingerprint. In the case of stack traces, all frames are considered. If the event data matches all the values in a line for a matcher and expression, then the fingerprint is applied. When there are multiple rules that match the event, the first matching rule in the list is applied. - -Fingerprinting Config - -`` - -```bash code-highlight -# You can use comments to explain the rules. Rules themselves follow the -# following syntax: -matcher:expression -> list of values -# The list of values can be hardcoded or substituted values. - -``` - -Below is a practical example, which groups exceptions of a specific type together: - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:DatabaseUnavailable -> system-down -error.type:ConnectionError -> system-down - -error.value:"connection error: *" -> connection-error, {{ transaction }} - -``` - -Now, all the events with the error type `DatabaseUnavailable` or `ConnectionError` will be grouped into an issue with the type `system-down`. In addition, all events with the error value `connection error` will be grouped by their transaction name. So, for example, if your transactions `/api/users/foo/` and `/api/events/foo/`—both with the value `connection error`—crash the same way, Sentry will create two issues, regardless of stack trace or any other default grouping method. - -## [Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#matchers) - -Matchers allow you to use [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)). - -If you want to create a rule that includes brackets `[ ]`, braces `{ }` or a literal `*`, escape them with a backslash; that is, `\[`, `\]`, `\{`, `\}` or `\*`. - -The following matchers are available: - -### [`error.type`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#errortype) - -alias: `type` - -Matches on an exception type (exception name). The match is performed as a case-sensitive glob. - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:ZeroDivisionError -> zero-division -error.type:ConnectionError -> connection-error - -``` - -### [`error.value`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#errorvalue) - -alias: `value` - -Matches on the exception value. Errors or exceptions often have human-readable descriptions (values) associated with them. This matcher allows a case insensitive match. - -Fingerprinting Config - -`` - -```bash code-highlight -error.value:"connection error (code: *)" -> connection-error -error.value:"could not connect (*)" -> connection-error - -``` - -### [`message`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#message) - -Matches on a log message. It will also automatically check for the additional exception value as they can be hard to keep apart. The matching is case insensitive. - -Fingerprinting Config - -`` - -```bash code-highlight -message:"system encountered a fatal problem: *" -> fatal-log - -``` - -### [`logger`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#logger) - -Matches on the name of the logger, which is useful to combine all messages of a logger together. This match is case-sensitive. - -Fingerprinting Config - -`` - -```bash code-highlight -logger:"com.myapp.mypackage.*" -> mypackage-logger - -``` - -### [`level`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#level) - -Matches on the log level. The match is case insensitive. - -Fingerprinting Config - -`` - -```bash code-highlight -logger:"com.myapp.FooLogger" level:"error" -> mylogger-error - -``` - -### [`tags.tag_name`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#tagstag_name) - -Matches on the value of the tag `tag_name`. This can be useful to filter down certain types of events. For instance, you can separate events caused by a specific server: - -Fingerprinting Config - -`` - -```bash code-highlight -tags.server_name:"canary-*.mycompany.internal" -> canary-events - -``` - -### [`stack.abs_path`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackabs_path) - -alias: `path` - -Matches on the path of an event and is case insensitive. It uses path globbing semantics, which means that `*` does not match a slash, but `**` does. Note that this matcher matches on both `abs_path` and `filename` as SDKs can be quite inconsistent about how these values are supported. If the glob matches on either of these values, it's considered a match. - -Fingerprinting Config - -`` - -```bash code-highlight -stack.abs_path:"**/my-utils/*.js" -> my-utils, {{ error.type }} - -``` - -### [`stack.module`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackmodule) - -alias: `module` - -Similar to `stack.abs_path` but matches on the module name instead. The match is case-sensitive and regular globbing rules apply ( `*` also matches slashes). - -Fingerprinting Config - -`` - -```bash code-highlight -stack.module:"*/my-utils/*" -> my-utils, {{ error.type }} - -``` - -### [`stack.function`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackfunction) - -alias: `function` - -Checks if any of the functions in the stack trace match the glob. The match is case-sensitive: - -Fingerprinting Config - -`` - -```bash code-highlight -stack.function:"my_assertion_failed" -> my-assertion-failed - -``` - -### [`stack.package`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#stackpackage) - -alias: `package` - -Matches on the "package" of a frame. This is typically the name of the debug symbol/object file that contains a frame. If any of the frames match this object file, then it matches. - -Fingerprinting Config - -`` - -```bash code-highlight -stack.package:"**/libcurl.dylib" -> libcurl -stack.package:"**/libcurl.so" -> libcurl - -``` - -### [`family`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#family) - -Used to "scope" down the matcher. The following families exist: `javascript` for any type of JavaScript event, `native` for any type of Native event. Any other platform is called `other`. - -Fingerprinting Config - -`` - -```bash code-highlight -family:native !stack.module:"myproject::*" -> not-from-my-project - -``` - -### [`app`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#app) - -Checks if the frame is in-app or not. It is particularly useful when combined with another matcher. Possible values are `yes` and `no`: - -Fingerprinting Config - -`` - -```bash code-highlight -app:yes stack.function:"assert" -> assert - -``` - -## [Combining Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#combining-matchers) - -When multiple matchers are combined, they all need to match. Matchers that operate on frames must all apply to the same frame; otherwise, they are not considered a match. - -For instance, if you match on both the function name and module name, then a match only exists if a frame matches _both_ the function name and the module name. It's not enough for a frame to match only with the function name, even if another frame would match the module name by itself. - -Fingerprinting Config - -`` - -```bash code-highlight -# this matches if a frame exists with a specific function and module name -# and also a specific error type is thrown -error.type:ConnectionError stack.function:"connect" stack.module:"bot" -> bot-error - -``` - -## [Variables](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#variables) - -On the right-hand side of the fingerprint, you can use constant values and variables. Variables are substituted automatically and have the same name as matchers, but they might be filled in differently. These variables can also be used when assigning fingerprints using Sentry SDKs. - -Variables are enclosed in double braces ( `{{ variable_name }}`). - -### [`{{ default }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-default-) - -This fills in the default fingerprint that would be produced by the normal grouping operation. It is useful if you want to subdivide an already existing group by something else: - -Fingerprinting Config - -`` - -```bash code-highlight -stack.function:"query_database" -> {{ default }}, {{ transaction }} - -``` - -### [`{{ transaction }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-transaction-) - -This fills in the name of the transaction into the fingerprint. It will force the creation of a group per transaction: - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ApiError" -> api-error, {{ transaction }} - -``` - -### [`{{ error.type }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-errortype-) - -alias: `{{ type }}` - -This fills in the name of the error that occurred. When chained exceptions are used, it will be the most recently thrown error. This will force the creation of a group per error type: - -Fingerprinting Config - -`` - -```bash code-highlight -stack.function:"evaluate_script" -> script-evaluation, {{ error.type }} - -``` - -### [`{{ error.value }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-errorvalue-) - -alias: `{{ value }}` - -This fills in the stringified value of the error that occurred. When chained exceptions are used, it will be the most recently thrown error. Note that this can produce really bad groups when error values are frequently changing. - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ScriptError" -> script-evaluation, {{ error.value }} - -``` - -### [`{{ stack.function }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackfunction-) - -alias: `{{ function }}` - -This fills in the function name of the "crashing frame," also known as the application code's topmost frame. - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ScriptError" -> script-evaluation, {{ stack.function }} - -``` - -### [`{{ stack.abs_path }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackabs_path-) - -alias: `{{ path }}` - -This fills in the path of the "crashing frame," also known as the application code's topmost frame. - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ScriptError" -> script-evaluation, {{ stack.abs_path }} - -``` - -### [`{{ stack.filename }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackfilename-) - -This is like `stack.abs_path` but will only fill in the relative file name: - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ScriptError" -> script-evaluation, {{ stack.filename }} - -``` - -### [`{{ stack.module }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackmodule-) - -alias: `{{ module }}` - -This fills in the module name of the "crashing frame," also known as the application code's topmost frame. - -Fingerprinting Config - -`` - -```bash code-highlight -error.type:"ScriptError" -> script-evaluation, {{ stack.module }} - -``` - -### [`{{ stack.package }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-stackpackage-) - -alias: `{{ package }}` - -This fills in the package name (object file) of the "crashing frame," also known as the application code's topmost frame. - -Fingerprinting Config - -`` - -```bash code-highlight -stack.function:"assert" -> assertion, {{ stack.package }} - -``` - -### [`{{ logger }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-logger-) - -This fills in the name of the logger that caused an event. - -Fingerprinting Config - -`` - -```bash code-highlight -message:"critical connection error*" -> connection-error, {{ logger }} - -``` - -### [`{{ level }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-level-) - -This fills in the name of the log level that was used to create an event. - -Fingerprinting Config - -`` - -```bash code-highlight -message:"connection error*" -> connection-error, {{ logger }}, {{ level }} - -``` - -### [`{{ tags.tag_name }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-tagstag_name-) - -This fills in the value of a tag into the fingerprint, which can, for instance, be used to split events by server name or something similar. - -Fingerprinting Config - -`` - -```bash code-highlight -message:"connection error*" -> connection-error, {{ tags.server_name }} - -``` - -### [`{{ message }}`](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#-message-) - -This fills in the message of the event (similar to `error.value` but for captured messages). Note that this can produce groups with poor data quality if messages are changing frequently: - -Fingerprinting Config - -`` - -```bash code-highlight -logger:"com.foo.auditlogger.*" -> audit-log, {{ message }} - -``` - -## [Custom Titles](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/\#custom-titles) - -When you use fingerprinting to group events together it can sometimes be useful to also change the default title of the event. Normally the title of the event is the exception type and value (or the top most function names for certain platforms). When you group by custom rules this title can often be misleading. For instance if you group a logger together you might want to name the group after that logger. This can be accomplished by setting the `title` attribute like this: - -Fingerprinting Config - -`` - -```bash code-highlight -logger:my.package.* level:error -> error-logger, {{ logger }} title="Error from Logger {{ logger }}" - -``` - -[Previous\\ -\\ -Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues) - -[Next\\ -\\ -Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/fingerprint-rules.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Release Management](https://docs.sentry.io/cli/releases/) - -# Release Management - -## Sentry's command line interface can be used for release management. The CLI allows you to create, edit and delete releases as well as upload release artifacts. - -The `sentry-cli` tool can be used for release management on Sentry. It allows you to create, edit and delete releases as well as upload release artifacts for them. Note that releases are global per organization. If you want the releases in different projects to be treated as separate entities, make the version name unique across the organization. For example, if you have projectA and projectB that share version numbers, you can name the releases `projectA-1.0` and `projectB-1.0` respectively. - -Because releases work on projects you will need to specify the organization and project you are working with. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). - -## [Creating Releases](https://docs.sentry.io/cli/releases/\#creating-releases) - -Releases are created with the `sentry-cli releases new` command. It takes at the very least a version identifier that uniquely identifies the releases. There are a few restrictions -- the release name cannot: - -- contain newlines, tabulator characters, forward slashes(/), or back slashes(\\) -- be (in their entirety) period (.), double period (..), or space ( ) -- exceed 200 characters - -The value can be arbitrary, but for certain platforms, recommendations exist: - -- for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error. -- if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`. -- if you tag releases we recommend using the release tag prefixed with a product or package name (for example, `my-project-name@2.3.12`). - -Bash - -`` - -```bash code-highlight -#!/bin/sh -sentry-cli releases new "$VERSION" - -``` - -Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in. - -## [Finalizing Releases](https://docs.sentry.io/cli/releases/\#finalizing-releases) - -By default a release is created “unreleased”. Finalizing a release means that we populate a second timestamp on the release record, which is prioritized over `date_created` when sorting releases in [sentry.io](https://sentry.io/). Release finalization (and the timestamp) also affects: - -- What counts as "the next release" for resolving issues -- What release is used as the base for associating commits if you use `--auto` - -In addition, it creates an entry in the **Activity** stream. - -You can change this by passing either `--finalize` to the `new` command, which will immediately finalize the release, or by separately calling `sentry-cli releases finalize VERSION` later on, which is useful if you are managing releases as part of a build process. For example: - -Bash - -`` - -```bash code-highlight -#!/bin/sh -sentry-cli releases new "$VERSION" -# do your build steps here -# once you are done, finalize -sentry-cli releases finalize "$VERSION" - -``` - -You can also choose to finalize the release when you've made the release live (when you've deployed to your machines, enabled in the App store, etc.). - -If you are using git you can ask Sentry to determine `$VERSION`: - -Bash - -`` - -```bash code-highlight -#!/bin/sh -VERSION=`sentry-cli releases propose-version` - -``` - -## [Commit Integration](https://docs.sentry.io/cli/releases/\#commit-integration) - -If you have [repositories configured](https://docs.sentry.io/product/releases/setup/release-automation/) within your Sentry organization, you can associate commits with your release automatically or manually. If you don't have a source code integration installed, you can still send Sentry commit information. See [Alternatively: Without a Repository Integration](https://docs.sentry.io/cli/releases/#alternatively-without-a-repository-integration) to associate commits using the git tree of your local repo. - -To integrate commits automatically, you need to deploy from a git repository that sentry-cli can discover from your current working directory and set commits with the `--auto` flag: - -Bash - -`` - -```bash code-highlight -sentry-cli releases set-commits "$VERSION" --auto - -``` - -In case you are deploying without access to the git repository, you can manually specify the commits instead. To do this, pass the `--commit` parameter to the `set-commits` command in the format `REPO_NAME@REVISION`. You can repeat this for as many repositories as you have: - -bash (one repo)bash (many repos) - -`` - -```bash code-highlight -sentry-cli releases set-commits "$VERSION" --commit "repo-owner/repo-name@deadbeef" - -``` - -To see which repos are available for the organization, you can run `sentry-cli repos list` which will return a list of configured repositories. - -Note that you need to refer to releases you need to use the actual full commit SHA. If you want to refer to tags or references (like _HEAD_), the repository needs to be checked out and reachable from the path where you invoke _sentry-cli_. - -If you also want to set a previous commit instead of letting the server use the previous release as the base point you can do that by setting a commit range: - -Bash - -`` - -```bash code-highlight -sentry-cli releases set-commits "$VERSION" --commit "repo-owner/repo-name@from..to" - -``` - -### [Alternatively: Without a Repository Integration](https://docs.sentry.io/cli/releases/\#alternatively-without-a-repository-integration) - -You can still use the `--auto` flag, and the CLI will automatically use the git tree of your local repo, and associate commits between the previous release's commit and the current head commit with the release. If this is the first release, Sentry will use the latest 20 commits. This behavior is configurable with the `--initial-depth` flag. - -You can use the `--local` flag to enable this behavior by default. - -Bash - -`` - -```bash code-highlight -sentry-cli releases set-commits "$VERSION" --local - -``` - -If you receive an "Unable to Fetch Commits" email, take a look at our [help center article](https://sentry.zendesk.com/hc/en-us/articles/23968845267739-Why-am-I-receiving-the-email-Unable-to-Fetch-Commits). - -### [Dealing With Missing Commits](https://docs.sentry.io/cli/releases/\#dealing-with-missing-commits) - -There are scenarios in which your repositories may be missing commits previously used in the release. This can happen whenever you modify the commit in question by, for example, amending it, rebasing, or squashing multiple commits together. In this case, Sentry CLI will be unable to find it, and will throw an error that the commit cannot be found. - -When this happens, you can pass an additional `--ignore-missing` flag. This will allow the command to fall back to the default behavior, which is creating a release with a specified number of commits (see the section above). - -Bash - -`` - -```bash code-highlight -sentry-cli releases set-commits "$VERSION" --auto --ignore-missing - -``` - -## [Managing Release Artifacts](https://docs.sentry.io/cli/releases/\#managing-release-artifacts) - -When you are working with JavaScript and other platforms, you can upload release artifacts to Sentry which are then considered during processing. The most common release artifact are [source maps](https://docs.sentry.io/platforms/javascript/sourcemaps/) for which `sentry-cli` has specific support. - -To manage release artifacts the `sentry-cli files` command can be used which itself provides various sub commands. - -### [Upload Files](https://docs.sentry.io/cli/releases/\#upload-files) - -The most common use case is to upload files. For the generic upload the `sentry-cli files upload` command can be used. However since most release artifacts are JavaScript source map related we have a [Upload Source Maps](https://docs.sentry.io/cli/releases/#sentry-cli-sourcemaps) convenience method for that. - -Files uploaded are typically named with a full (eg: `http://example.com/foo.js`) or truncated URL (eg: `~/foo.js`). - -Release artifacts are only considered at time of event processing. So while it’s possible to modify release artifacts after the fact they will only be considered for future events of that release. - -The first argument to `upload` is the path to the file, the second is an optional URL we should associate it with. Note that if you want to use an abbreviated URL (eg: `~/foo.js`) make sure to use single quotes to avoid the expansion by the shell to your home folder. - -Bash - -`` - -```bash code-highlight -sentry-cli files upload --release "$VERSION" /path/to/file '~/file.js' - -``` - -### [Upload Source Maps](https://docs.sentry.io/cli/releases/\#upload-source-maps) - -For source map upload, a separate command is provided which assists you in uploading and verifying source maps: - -Bash - -`` - -```bash code-highlight -sentry-cli sourcemaps upload /path/to/sourcemaps - -``` - -This command provides several options and attempts as much auto detection as possible. By default, it will scan the provided path for files and upload them named by their path with a `~/` prefix. It will also attempt to figure out references between minified files and source maps based on the filename. So if you have a file named `foo.min.js` which is a minified JavaScript file and a source map named `foo.min.map` for example, it will send a long a `Sourcemap` header to associate them. This works for files the system can detect a relationship of. - -By default, `sentry-cli` rewrites source maps before upload: - -1. It flattens out indexed source maps. This has the advantage that it can compress source maps sometimes which might improve your processing times and can work with tools that embed local paths for source map references which would not work on the server. This is useful when working with source maps for development purposes in particular. -2. Local file references in source maps for source contents are inlined. This works particularly well with React Native projects which might reference thousands of files you probably do not want to upload separately. -3. It automatically validates source maps before upload very accurately which can spot errors you would not find otherwise until an event comes in. This is an improved version of what `--validate` does otherwise. - -The following options exist to change the behavior of the upload command: - -`--dist` - -Sets the distribution identifier for uploaded files. This identifier is used to make a distinction between multiple files of the same name within a single release. `dist` can be used to disambiguate build or deployment variants. For example, `dist` can be the build number of an Xcode build or the version code of an Android build. - -`--no-sourcemap-reference` - -This prevents the automatic detection of source map references. It’s not recommended to use this option since the system falls back to not emitting a reference anyways. It is however useful if you are manually adding `sourceMapURL` comments to the minified files and you know that they are more correct than the autodetection. - -`--no-rewrite` - -Disables rewriting of matching source maps. By default, the tool will rewrite sources, so that indexed maps are flattened and missing sources are inlined if possible. This fundamentally changes the upload process to be based on source maps and minified files exclusively and comes in handy for setups like react-native that generate source maps that would otherwise not work for Sentry. - -`--strip-prefix` / `--strip-common-prefix` - -Unless `--no-rewrite` is specified, this will chop-off a prefix from all sources references inside uploaded source maps. For instance, you can use this to remove a path that is build machine specific. The common prefix version will attempt to automatically guess what the common prefix is and chop that one off automatically. This will not modify the uploaded sources paths. To do that, point the `sourcemaps upload` command to a more precise directory instead. - -`--validate` - -This attempts source map validation before upload when rewriting is not enabled. It will spot a variety of issues with source maps and cancel the upload if any are found. This is not the default as this can cause false positives. - -`--url-prefix` - -This sets an URL prefix in front of all files. This defaults to `~/` but you might want to set this to the full URL. This is also useful if your files are stored in a sub folder. eg: `--url-prefix '~/static/js'` - -`--ext` - -Overrides the list of file extensions to upload. By default, the following file extensions are processed: `js`, `map`, `jsbundle` and `bundle`. The tool will automatically detect the type of the file by the file contents (eg: sources, minified sources, and source maps) and act appropriately. For multiple extensions you need to repeat the option, e.g.: `--ext js --ext map`. - -`--ignore` - -Specifies one or more patterns of ignored files and folders. Overrides patterns specified in the ignore file. See `--ignore-file` for more information. Note that unlike `--ignore-file`, this argument is interpreted relative to the specified path argument. - -`--ignore-file` - -Specifies a file containing patterns of files and folders to ignore during the scan. Ignore patterns follow the [gitignore](https://git-scm.com/docs/gitignore#_pattern_format) rules and are evaluated relative to the location of the ignore file. The file is assumed in the current working directory or any of its parent directories. - -`--strict` - -Fail with a non-zero exit code if there are no sourcemaps to upload in the provided directory. Without this argument, the command succeeds if there are no sourcemaps to upload. - -Some example usages: - -Bash - -`` - -```bash code-highlight -# Rewrite and upload all sourcemaps in /path/to/sourcemaps -sentry-cli sourcemaps upload /path/to/sourcemaps - -# Prefix all paths with ~/static/js to match where the sources are hosted online -sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js' - -# Remove a common prefix if all source maps are located in a subdirectory -sentry-cli sourcemaps upload /path/to/sourcemaps --url-prefix '~/static/js' \ - --strip-common-prefix - -# Omit all files specified in .sentryignore -sentry-cli sourcemaps upload /path/to/sourcemaps --ignore-file .sentryignore - -``` - -### [List Files](https://docs.sentry.io/cli/releases/\#list-files) - -To list uploaded files, the following command can be used: - -Bash - -`` - -```bash code-highlight -sentry-cli files list --release "$VERSION" - -``` - -This will return a list of all uploaded files for that release. - -### [Delete Files](https://docs.sentry.io/cli/releases/\#delete-files) - -You can also delete already uploaded files. Either by name or all files at once: - -Bash - -`` - -```bash code-highlight -sentry-cli files delete --release "$VERSION" NAME_OF_FILE -sentry-cli files delete --release "$VERSION" --all - -``` - -## [Creating Deploys](https://docs.sentry.io/cli/releases/\#creating-deploys) - -You can also associate deploys with releases. To create a deploy you first create a release and then a deploy for it. At the very least, you should supply the “environment” the deploy goes to (production, staging etc.). You can freely define this: - -Bash - -`` - -```bash code-highlight -sentry-cli deploys new --release "$VERSION" -e ENVIRONMENT - -``` - -Optionally, you can also define how long the deploy took: - -Bash - -`` - -```bash code-highlight -start=$(date +%s) -... -now=$(date +%s) -sentry-cli deploys new --release "$VERSION" -e ENVIRONMENT -t $((now-start)) - -``` - -Deploys can be listed too (however they cannot be deleted): - -Bash - -`` - -```bash code-highlight -sentry-cli deploys list --release "$VERSION" - -``` - -[Previous\\ -\\ -Configuration and Authentication](https://docs.sentry.io/cli/configuration) - -[Next\\ -\\ -Debug Information Files](https://docs.sentry.io/cli/dif) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/releases.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Set Up Your Organization](https://docs.sentry.io/organization/getting-started/) - -# Set Up Your Organization - -## Learn how to set up a Sentry organization account, so you can start fixing errors right away. - -In this guide, we'll provide the recommended checklist for setting up your [Sentry organization account](https://sentry.io/) so you can get started with Sentry error monitoring. - -If you'd prefer a TL;DR, download our ["Admin Quick Reference Guide"](https://docs.sentry.io/pdfs/Admin-quick-reference-guide.pdf) - -We understand that some of you are running enterprise organizations, while others of you are hobbyists just coding for fun. Below, we've linked where you should get started, depending on your situation. - -- You're configuring Sentry for a large organization? [Start at step 1](https://docs.sentry.io/organization/getting-started/#1-enable-single-sign-on-access) -- You're working on an application with a small team? [Start step 2](https://docs.sentry.io/organization/getting-started/#2-set-up-teams) -- You're a hobbyist or working on an app alone? [Start at step 3](https://docs.sentry.io/organization/getting-started/#3-configure-integrations) - -Of course, you're welcome to go through all the steps, even if you're a team of one. - -## [1\. Enable Single Sign-On Access](https://docs.sentry.io/organization/getting-started/\#1-enable-single-sign-on-access) - -[Single sign-on (SSO)](https://docs.sentry.io/organization/authentication/sso/) allows your team to log in quickly, streamlines the on/off-boarding process for member accounts, and strengthens your login with secure credentials. Sentry provides out-of-the-box configuration for integrating SSO providers like [Okta](https://docs.sentry.io/organization/authentication/sso/#okta) and [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/#azure-active-directory) (SAML) or [Google](https://docs.sentry.io/organization/authentication/sso/#google-business-app) and [GitHub](https://docs.sentry.io/organization/authentication/sso/#github-organizations) (Oauth). In addition, we provide a generic configuration option for any other [SAML2 Identity Provider](https://docs.sentry.io/organization/authentication/sso/saml2/). - -Sentry also supports a subset of the specification for System for Cross-Domain Identity Management (SCIM) for [Okta](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) and [Azure AD](https://docs.sentry.io/organization/authentication/sso/azure-sso/#scim-integration). - -## [2\. Set Up Teams](https://docs.sentry.io/organization/getting-started/\#2-set-up-teams) - -Now that SSO is configured and members have created their accounts, add them to their Sentry Teams. Teams are associated with your [Sentry projects](https://docs.sentry.io/organization/getting-started/#4-create-projects), and their members receive issue notifications in addition to becoming issue assignees. We recommend creating Sentry teams that align with your internal team structure (for example, _#Frontend_, _#Ops_, _#SDK_, and so on). To add a new team, go to **Settings > Teams** and click "Create Team". - -[![Create New Team](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fteam-settings-HSDWF3LG.png%232024x896&w=3840&q=75)](https://docs.sentry.io/mdx-images/team-settings-HSDWF3LG.png) - -Click on a team name to open the team settings and manage its associated members and projects. Under the "Members" tab, add existing members to your team by clicking on "Add Member > \[Member Name\]". - -You can also invite multiple new (external) members to join your organization and team by clicking on "Add Member > Invite Member". - -[![Invite Members](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvite-members-NIJLLGEH.png%231866x717&w=3840&q=75)](https://docs.sentry.io/mdx-images/invite-members-NIJLLGEH.png) - -Learn more about different user roles in [Organization Management](https://docs.sentry.io/organization/membership/). - -## [3\. Configure Integrations](https://docs.sentry.io/organization/getting-started/\#3-configure-integrations) - -Sentry integrates into your existing workflows by providing out-of-the-box integrations with widely-used apps and services. To enable and configure integrations, go to **Settings > Integrations**. There are several types of integrations available, but we recommend that you immediately set up integrations for: - -- [Alerting](https://docs.sentry.io/organization/getting-started/#31-alert-notifications) -- [Source code management](https://docs.sentry.io/organization/getting-started/#32-source-code-management) -- [Issue tracking](https://docs.sentry.io/organization/getting-started/#33-issue-tracking) - -### [Alert Notifications](https://docs.sentry.io/organization/getting-started/\#alert-notifications) - -By default, Sentry will notify you about errors in your apps by email and [Slack](https://docs.sentry.io/organization/integrations/notification-incidents/slack/) (once you enable the integration). You can also enable team notifications in Slack so the right people in your organization always receive the alerts they need. In addition to Slack, Sentry offers several other [notification and incident integrations](https://docs.sentry.io/organization/integrations/notification-incidents/) to help you triage issues, including [Discord](https://docs.sentry.io/organization/integrations/notification-incidents/discord/), [Microsoft Teams](https://docs.sentry.io/organization/integrations/notification-incidents/msteams/), and [PagerDuty](https://docs.sentry.io/organization/integrations/notification-incidents/pagerduty/). - -Learn more about setting up alerts with integrations in [Alert Routing With Integrations](https://docs.sentry.io/product/alerts/create-alerts/routing-alerts/). - -### [Source Code Management](https://docs.sentry.io/organization/getting-started/\#source-code-management) - -When you enable an integration with your source code management (SCM) provider, Sentry will analyze your commit data to: - -1. Identify **suspect commits** that likely introduced an error. - -2. **Suggest assignees** who can best resolve the error, based on the suspect commits and your [codeowners file](https://docs.sentry.io/product/issues/issue-owners/#code-owners). - -3. Mark an issue as **Resolved via Commit or PR** to stop notifications about similar errors in past releases and notify you of a regression. - -4. Link a Sentry issue to a new or existing issue in your integrated [issue tracking](https://docs.sentry.io/organization/getting-started/#33-issue-tracking) solution. - -[![Identify suspect commits and see suggested assignees for issues.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissue-integrations-01-UC7KSKAC.png%231400x537&w=3840&q=75)](https://docs.sentry.io/mdx-images/issue-integrations-01-UC7KSKAC.png) - -[![Link a Sentry issue to a new or existing issue in your issue tracking solution.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissue-integrations-02-WDF5PC4V.png%231400x210&w=3840&q=75)](https://docs.sentry.io/mdx-images/issue-integrations-02-WDF5PC4V.png) - - -Sentry has built-in SCM integrations with: - -- [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/) -- [GitHub](https://docs.sentry.io/organization/integrations/source-code-mgmt/github/) -- [GitLab](https://docs.sentry.io/organization/integrations/source-code-mgmt/gitlab/) -- [Bitbucket](https://docs.sentry.io/organization/integrations/source-code-mgmt/bitbucket/) - -If you're using a different SCM provider or don't want Sentry to connect to your repository, check out our [Releases documentation](https://docs.sentry.io/product/releases/associate-commits/) to learn how you can still associate commits with your release. - -### [Issue Tracking](https://docs.sentry.io/organization/getting-started/\#issue-tracking) - -Enabling an integration with your issue tracking solution allows you to create a new issue from within the **Issue Details** page in [sentry.io](https://sentry.io/), or link to an existing one. GitHub, GitLab, and Bitbucket issues are associated with their respective SCM integrations. Sentry also integrates with [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/), [Shortcut](https://docs.sentry.io/organization/integrations/issue-tracking/shortcut/), [Jira](https://docs.sentry.io/organization/integrations/issue-tracking/jira/), and others. - -For a list of all supported integrations, check out out our [full Integrations documentation](https://docs.sentry.io/organization/integrations/). - -You can set up automated issue management when you create alerts that route to [Azure DevOps](https://docs.sentry.io/organization/integrations/source-code-mgmt/azure-devops/#automatically) and [Jira](https://docs.sentry.io/organization/integrations/issue-tracking/jira/#automatically). External issues will be created for new Sentry issues on your behalf, and these issues will use the configured fields in your Azure DevOps or Jira workspace. For other issue tracking solutions, you can manually link Sentry issues. - -Automatic issue management is available only if your organization is on a Business or Trial plan. - -## [4\. Create Projects](https://docs.sentry.io/organization/getting-started/\#4-create-projects) - -To start monitoring errors in your app with Sentry, you'll need to initialize the SDK with a DSN key. To obtain a key, add a new Sentry project by going to **Projects** and clicking "Create Project". Give the project a name and assign the responsible [team (or teams)](https://docs.sentry.io/organization/getting-started/#2-set-up-teams). Then, retrieve the key in **\[Project\] > Settings > Client Keys (DSN)**. - -[![Retrieve your project DSN key.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-dsn-CQ76WK6B.png%231400x561&w=3840&q=75)](https://docs.sentry.io/mdx-images/project-dsn-CQ76WK6B.png) - -Once the SDK is initialized, any error that occurs in your code, wherever it may be deployed and running, will be associated with that specific project. - -If you haven't set up any teams to associate with your project because you skipped to step three, don't worry. Even on our free Developer plan, Sentry automatically sets up a team for you based on the name of your organization, and adds you to it. - -### [What's in a Project?](https://docs.sentry.io/organization/getting-started/\#whats-in-a-project) - -A _project_ is a logical entity that connects the errors in your application (or a part of it) to the team members assigned to that project. The project settings determine: - -- Which errors should be ingested into your Sentry account and which should be dropped, through [Inbound Filters](https://docs.sentry.io/pricing/quotas/#inbound-data-filters) -- Who to notify, about what error, and how, using [Alert Rules](https://docs.sentry.io/product/alerts/alert-types/) -- Which errors should be automatically assigned to which member or team using [Ownership Rules](https://docs.sentry.io/product/issues/ownership-rules/) -- Custom rules to fine-tune [Event Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) into issues - -Also, when you go to the **Issues** and **Discover** pages in [sentry.io](https://sentry.io/), the filter at the top of the screen prioritizes the projects you're a member of by default. This way, developers are looking at information that is relevant to their work, and they see the errors that they might need to work on. - -[![Issues page with Project dropdown open.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fissues-project-dropdown-ASVOHFSW.png%232152x847&w=3840&q=75)](https://docs.sentry.io/mdx-images/issues-project-dropdown-ASVOHFSW.png) - -### [How Many Projects Should I Create?](https://docs.sentry.io/organization/getting-started/\#how-many-projects-should-i-create) - -You could theoretically put all your errors into a single project, as this isn't limited in [sentry.io](https://sentry.io/). However, setting up multiple projects to reflect your application with finer granularity helps makes errors more visible and actionable, which can have a big impact on your team's productivity. - -Here are some points to consider: - -- If your application's source code is managed in **multiple repositories**, create a **separate project for each repo**. -- If your app is made up of **several micro-services**, **split them into projects** accordingly. -- If you have a **monolithic codebase**, set up **separate projects for the backend and frontend**. -- Give **each language its own project**. For example, if your backend code contains NodeJS and Java components, separate those into two different projects. - -## [5\. Define Environments](https://docs.sentry.io/organization/getting-started/\#5-define-environments) - -Depending on your development life cycle, your applications are probably deployed and running in multiple environments — _QA_, _Staging_, _Production_, and so on. Configuring the environment in your Sentry SDK will add the tag to every error event and will help you associate events with the environment in which they occurred. You can do that by creating a `SENTRY_ENVIRONMENT` environment variable or by explicitly defining it in the SDK configuration. Learn more in [Environments](https://docs.sentry.io/platform-redirect/?next=/configuration/environments/). - -[![The Issues page with the Environment dropdown opened.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenvironment-dropdown-CVASUUYU.png%232153x827&w=3840&q=75)](https://docs.sentry.io/mdx-images/environment-dropdown-CVASUUYU.png) - -Having the environment defined in your SDK will allow you to: - -- Create environment-specific alert rules. -- Filter the **Issues** page based on the environment. -- Gain comparative insights, based on the environment, through queries in **Discover**. - -[Previous\\ -\\ -Organization Settings](https://docs.sentry.io/organization) - -[Next\\ -\\ -Authentication](https://docs.sentry.io/organization/authentication) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/getting-started/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/) - -# How to Write - Getting Started - -A new platform/SDK should base it's Getting Started page of off a similar existing SDK page. - -Here's an overview of the general components of a Getting Started page. - -## [config.yml](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#configyml) - -This file resides in the `/docs/platform/<SDK_name>/` directory. An example: - -YAML - -`` - -```yaml code-highlight -title: JavaScript -caseStyle: camelCase -supportLevel: production -sdk: "sentry.javascript.browser" -categories: - - browser - -``` - -## [Primer Content](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#primer-content) - -Explain the SDK at a high level in these two parts: - -1. An italicized sentence that explains what the SDK enables (errors, or errors and transactions) - -2. A brief paragraph that provides technical insight and the versions supported - -If the primer content isn't developed, this fallback will display " _Sentry's SDKs enable automatic reporting of errors and exceptions_." - - -Add the primer content to this directory: - -- [`/platform-includes/getting-started-primer/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-primer) - -## [Installation Method](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#installation-method) - -Provide an example of the primary installation method for this SDK. While we document alternate methods, we keep those on a separate page (as in this [example](https://docs.sentry.io/platforms/javascript/install/)) to keep the focus of the Getting Started content on the most-common, fastest way to get up and running. - -Add the installation method to this directory: - -- [`/platform-includes/getting-started-install/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-install) - -## [Configuration Code Sample](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#configuration-code-sample) - -Provide an example of the configuration of this SDK, commenting in the code sample, not the surrounding prose. - -Add the configuration code sample to this directory: - -- [`/platform-includes/getting-started-config/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-config) - -If the SDK supports performance monitoring, add it to the list that links back into the SDK content from Product, stored in [`/docs/product/insights/getting-started.mdx`](https://github.com/getsentry/sentry-docs/blob/master/docs/product/insights/getting-started.mdx). - -## [Verification Code Sample](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#verification-code-sample) - -Provide a verification code sample for this SDK. It can be as simple as one line, though the SDK may require a more complex code sample. - -Add the verification code sample to this directory: - -- [`/src/platform-includes/getting-started-verify/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes/getting-started-verify) - -## [But, that's not all](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#but-thats-not-all) - -The Getting Started content is also used by our in-app onboarding wizard to get customers up and running with Sentry. Keeping all content up to date is critical. - -**If updating the code samples for an SDK, also update the Wizard.** - -### [Update the Wizard](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started/\#update-the-wizard) - -The in-app wizard is where customers first implement our SDKs. It's not a simple copy/paste from the Getting Started for two reasons: - -1. New customers lack the context that our Docs provide (think of it this way, there's no lefthand sidebar to review). -2. Experienced customers likely have alerts and so forth turned off, so don't expect one clear workflow. Also, don't review the workflow. Point customers to the product for a tour. - -As a result, a simple copy/paste of the Getting Started won't suffice. See the JavaScript wizard as an example. - -[Previous\\ -\\ -Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content) - -[Next\\ -\\ -How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-getting-started.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) - -# Tracing - -## Learn more about the tracing features Sentry offers to help you track your software performance across multiple systems. - -[Distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/) provides a connected view of related errors and transactions by capturing interactions among your software systems. With tracing, Sentry tracks your software performance and displays the impact of errors across multiple systems. Tracing issues back through services connects your front-end to your back-end. - -The [Trace View](https://docs.sentry.io/product/sentry-basics/tracing/trace-view/) allows you to drill down into the details of a single trace and traverse every transaction in that trace. This accelerates your ability to debug slow services, identify related errors, and root out other bottlenecks. - -The [Trace Explorer](https://docs.sentry.io/product/explore/traces/) allows you to explore traces by querying [span properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/). This helps you find relevant distributed traces that will give you more information to debug and optimize your code. - -## [Learn More](https://docs.sentry.io/concepts/key-terms/tracing/\#learn-more) - -[Previous\\ -\\ -Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data) - -[Next\\ -\\ -Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter/) - -# Frontmatter - -Frontmatter a YAML-formatted blob defined at the top of every markdown or mdx file: - -Markdown - -`` - -```markdown code-highlight ---- -title: Doc Title ---- - -Markdown or MDX content - -``` - -Standard frontmatter will apply on nearly every page: - -`title` - -Document title - used in `<title>` as well as things like search titles. - -`noindex` (false) - -Set this to true to disable indexing (robots, algolia) of this content. - -`notoc` (false) - -Set this to true to disable page-level table of contents rendering. - -`draft` (false) - -Set this to true to mark this page as a draft, and hide it from various other components (such as the PageGrid). - -`keywords` (\[\]) - -A list of keywords for indexing with search. - -`description` - -A description to use in the `<meta>` header, as well as in auto generated page grids. - -`sidebar_order` (10) - -The order of this page in auto generated sidebars and grids. - -Much of the other functionality for pages is also driven via frontmatter, such as: - -- [Redirects](https://docs.sentry.io/contributing/pages/redirects/) -- [Search](https://docs.sentry.io/contributing/pages/search/) - -`nextPage` ( `{ path: 'path/to/page', title: 'Page Title' }`) - -Overrides the next page shown in the bottom pagination navigation. - -`previousPage` ( `{ path: 'path/to/page', title: 'Page Title' }`) - -Overrides the previous page shown in the bottom pagination navigation. - -[Previous\\ -\\ -Pages](https://docs.sentry.io/contributing/pages) - -[Next\\ -\\ -Images](https://docs.sentry.io/contributing/pages/images) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/frontmatter.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Rate Limits](https://docs.sentry.io/api/ratelimits/) - -# Rate Limits - -Sentry rate limits every API request made to prevent abuse and resource overuse. The limit is applied to each unique combination of caller and endpoint. - -We restrict both how frequently a request is made (requests per second rate limit) and how many concurrent requests a caller can make (concurrent rate limit). - -The requests per second rate limit follows a fixed window approach. Requests are counted into time buckets, determined by the window size. If the number of requests from a caller exceeds the number of allowed requests within a window, then that request will be rejected. Each endpoint has its own maximum number of requests and window size. - -Meanwhile, the concurrent rate limiter will reject requests if the caller has too many requests in progress at the same time. - -You can track your rate limit usage by looking at special headers in the response. - -## [Headers](https://docs.sentry.io/api/ratelimits/\#headers) - -Every API request response includes the following headers: - -- `X-Sentry-Rate-Limit-Limit` - - The maximum number of requests allowed within the window -- `X-Sentry-Rate-Limit-Remaining` - - The number of requests this caller has left on this endpoint within the current window -- `X-Sentry-Rate-Limit-Reset` - - The time when the next rate limit window begins and the count resets, measured in UTC seconds from epoch -- `X-Sentry-Rate-Limit-ConcurrentLimit` - - The maximum number of concurrent requests allowed -- `X-Sentry-Rate-Limit-ConcurrentRemaining` - - The number of concurrent requests this caller has left - -## [Additional Information](https://docs.sentry.io/api/ratelimits/\#additional-information) - -The rate limiter looks at the caller's identity instead of the bearer token or cookie. As such, the rate limit cannot be bypassed by generating multiple tokens. - -Polling the API for updates is likely to quickly trigger rate limiting. We recommend using our [webhooks](https://docs.sentry.io/organization/integrations/integration-platform/webhooks/), if possible. - -[Previous\\ -\\ -Permissions & Scopes](https://docs.sentry.io/api/permissions) - -[Next\\ -\\ -Requests](https://docs.sentry.io/api/requests) - -- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Data Storage Location (US or EU)](https://docs.sentry.io/organization/data-storage-location/) - -# Data Storage Location (US or EU) - -## Choose where to store your data in the US or the EU. - -Sentry supports data storage in both the US and the EU. - -You can choose where to store your data when you’re setting up your Sentry account by selecting from the dropdown menu under "Data Storage Location" in the "Create a New Organization" section. - -**Please note that once selected, your data storage location can’t be changed. The only way to switch it is by creating a new organization.** - -Your selection determines your data storage location only. Sentry will continue to access and process your data in accordance with your agreement with Sentry for the Sentry service and our [Privacy Policy](https://sentry.io/privacy/). - -The table below shows the location where your data will be stored at rest, based on your selection. - -| **Data Storage Location** | **Physical Location** | -| --- | --- | -| United States of America (US) | Iowa, USA | -| European Union (EU) | Frankfurt, Germany | - -## [What Types of Data Are Stored Where](https://docs.sentry.io/organization/data-storage-location/\#what-types-of-data-are-stored-where) - -Here’s a list of the types of data that will be stored in whichever data storage location (US or EU) you select. - -### [Data Stored In Selected Location (US or EU)](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-selected-location-us-or-eu) - -- Error events -- Transactions -- Profiles -- Release health -- Releases, debug symbols, and source maps -- Session replays -- Backups for these resources - -### [Data Stored in US](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-us) - -Here’s a list of the types of data that may be stored in the US. - -- User accounts, notification settings, and 2FA authenticators (User accounts are shared by many organizations.) -- Organization integration metadata (Integrations can be shared across organizations and many of our integrations only support sending their webhooks to a singular destination.) -- Access tokens for users and organizations -- Organization settings, configurations, and teams -- Organization audit logs -- Issue activity, issue links -- Cron check-ins -- Project metadata -- DSN keys -- Detailed usage data -- Debug symbol metadata and source map metadata -- Sentry applications -- SSO, SAML, and SCIM metadata - -Metadata that lets Sentry identify an organization will be replicated out of the organization's data storage location to facilitate login, and backwards-compatible APIs. You can always confirm the location of your organization by viewing your organization's settings page. - -### [Data Stored in All Locations (US and EU)](https://docs.sentry.io/organization/data-storage-location/\#data-stored-in-all-locations-us-and-eu) - -Here’s a list of the types of data that will be stored in both data storage locations (US and EU). - -- Uptime checks - -##### Uptime Monitoring - -For uptime monitoring to work effectively, we perform uptime checks from multiple geolocations. As a result, uptime check data may be stored outside your selected data region, beyond the storage commitments outlined on this page. - -## [Using Data Storage Location APIs](https://docs.sentry.io/organization/data-storage-location/\#using-data-storage-location-apis) - -To ensure that your API requests are only processed within your selected data storage location, use the region-specific domain: - -| **Data Storage Location** | **API domain** | -| --- | --- | -| United States of America (US) | us.sentry.io | -| European Union (EU) | de.sentry.io | - -For [data stored in the US](https://docs.sentry.io/organization/data-storage-location/#data-stored-in-us), your API domain should be `sentry.io`. - -## [Switching Data Storage Locations for Existing Organizations](https://docs.sentry.io/organization/data-storage-location/\#switching-data-storage-locations-for-existing-organizations) - -### [SaaS](https://docs.sentry.io/organization/data-storage-location/\#saas) - -At this time, your data storage location can’t be changed if you have an existing SaaS organization. The only way to switch it is by creating a new organization. - -### [Self-hosted](https://docs.sentry.io/organization/data-storage-location/\#self-hosted) - -If you have a self-hosted Sentry account, you can [follow these instructions](https://docs.sentry.io/concepts/migration/) to migrate your data. - -**Supported for relocation:** - -- User accounts and settings -- Organization settings and configuration -- Projects and project settings -- Teams and members -- Dashboards -- Alert rules, notifications and incidents -- Saved searches - -**Unsupported for relocation:** - -- Error events, activity, and issue links -- Transactions -- Profiles -- Session Replays -- Cron check-ins -- Uptime checks -- DSN keys -- Release health -- Releases, Debug Symbols, and source maps -- Sentry Applications -- Access Tokens for users and organizations -- User notification settings, and 2FA authenticators -- Project codeowners -- Integrations -- Organization Audit Logs - -## [For Users With Multiple Organizations](https://docs.sentry.io/organization/data-storage-location/\#for-users-with-multiple-organizations) - -If you have multiple organizations, they will be treated separately regardless of where data is stored. This means that subscriptions, usage, users, projects, and so on, will be managed separately for each organization. - -[Previous\\ -\\ -Organization and User Management](https://docs.sentry.io/organization/membership) - -[Next\\ -\\ -Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/data-storage-location/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) -- [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) - -# Trace View - -## Learn more about the Trace View page, where you can drill down into the details of a single trace, allowing you to debug slow services, identify related errors, and find other bottlenecks. - -The Trace View page is designed to be your one-stop-shop when debugging performance or errors. It gives you full context on what was happening when an error or performance issue occurred, all in one place. The waterfall Trace View allows you to see everything that may have occurred during a trace, including errors, performance issues, and any profiles that may have been collected. - -In addition, looking at the Trace View allows you to drill down into a single trace so you can visualize the high-level transactions and spans that took place within that trace. This makes debugging slow services, identifying related errors, and rooting out bottlenecks easier and faster, since you no longer have to navigate around multiple pages of the Sentry product. - -## [Product Walkthrough: Trace View Page](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#product-walkthrough-trace-view-page) - -Sentry's default visualization of a trace is a waterfall-like structure, where the entries (transactions and spans) in the list are organized chronologically and through ancestry (child spans will fall under their parents). This allows you to follow the order of operations and drill into sub-operations. - -On the left side is a list of operations, and on the right is their duration and any events, such as errors, which may have occurred in that timeframe. - -By default, the waterfall view shows a list of transactions. If you need more granular data and want to see spans as well, click "+" to the left of a transaction to expand the waterfall. The waterfall view helps surface any performance issues or profiles collected during a given timeframe. - -![Step 3](<Base64-Image-Removed>)![Expand transaction to view which span produced the error.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/9ee9049b-14ca-4c93-8829-e41a05b6fa2b.png) - -![](<Base64-Image-Removed>) - -### [Helpful Tips](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#helpful-tips) - -Because debugging often involves multiple people or teams, we've made it easy to draw attention to specific areas of the trace and share a link that shows what you've highlighted with your colleagues. To do this, click on the row you'd like to draw attention to and share the resulting URL. Your colleague will see exactly what you want them to. - -Whatever you highlight will also be saved if you navigate away from the page and will still be there when you use your browser's back and forward buttons. - -If you're doing a comparison and want an easy way to go back and forth between highlighted areas of interest in your trace, you can pin the tabs. When a tab is pinned, the view will be persistent throughout your session. - -Trace View — Tabbing - -Trace View — Tabbing - -![Pinning a tab will persist it.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/d2c464e2-9c6a-4212-8c9c-f84302a9ecac.png) - -![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/65d725cb-0e5f-4d04-960f-4c7118ddc307.png) - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -Sometimes, duration gaps between entries can be small, but critical to your debugging effort. That's why the Trace View enables you to zoom into certain areas of the trace, either by double clicking on row elements (which zooms into the row) or by using your scroll wheel. - -Trace View — Zooming - -Trace View — Zooming - -![Scroll to move around or scroll + meta key to zoom.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/37fcd5f8-b2b5-4483-b5e5-cd9904dca78d.png)![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/980a208b-3fda-41fd-a52b-09d051b3f7d5.png) - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -The Trace View has other features like search, which makes it easy to visualize matching spans that you can then iterate over using the up or down arrows. You can also tailor the layout to your preference. - -We're going to continue adding features that enable you to perform efficient investigation into whatever issues you might be facing. If you have feedback or requests, please share it with us. We'd love to hear how we can make your life easier and your users happier. - -## [Troubleshooting](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#troubleshooting) - -### [Orphan Traces and Broken Subtraces](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#orphan-traces-and-broken-subtraces) - -In a fully instrumented system, a span in one service will connect to a transaction in a subsequent service. For a variety of reasons, a transaction in a service may not arrive in Sentry. When Sentry encounters these types of transactions within a trace, the transactions are linked with a dashed line since they can no longer be directly connected to the root, creating an orphan trace. - -In addition, broken subtraces can occur when Sentry receives an error for a trace, but the corresponding transaction does not exist. Such errors are linked using dashed lines and clicking on the row takes you to the corresponding **Issue Details** page. - -Also, in these cases you can click "Open In Discover" to see all the events in the trace. - -Broken subtraces may be caused by: - -- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](https://docs.sentry.io/organization/dynamic-sampling/#deciding-on-your-sdk-sample-rate). -- [Ad blockers](https://docs.sentry.io/platforms/javascript/troubleshooting/#dealing-with-ad-blockers) may prevent transactions in browsers being sent, but HTTP requests to backend projects will still create child transactions -- [Rate-limiting](https://docs.sentry.io/product/accounts/quotas/#limiting-events) on a project may cause only some events to be sent to Sentry -- [Project permissions](https://docs.sentry.io/product/accounts/membership/#restricting-access) may mean you do not have access to transactions in another project -- [Differences in quota limits](https://docs.sentry.io/product/accounts/quotas/) between transactions and errors. When a quota limit is reached - for example, for transactions - an error is received, but corresponding transaction is not. -- Exceeding the span limit. Transactions are associated via the child spans of the parent transaction, but if the number of spans exceed the limit, the association cannot be made - -### [Multiple Roots](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#multiple-roots) - -Each trace ID should have only one root, a transaction without any parents. Automatic instrumentation should prevent multiple roots; however, if the trace ID of your transactions is being set using custom instrumentation, you may encounter multiple roots. - -[Previous\\ -\\ -Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) - -[Next\\ -\\ -Search](https://docs.sentry.io/concepts/search) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/trace-view.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) -- [Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta/) - -# Vanta - -## Learn about Sentry's Vanta integration and how it helps automate security compliance. - -Sentry's Vanta integration grants Vanta read-only access to verify that Sentry organization members are associated with employees in your organization, which automates security compliance. This integration is maintained and supported by the company that created it. For more details, check out our [Integration Platform documentation](https://docs.sentry.io/organization/integrations/integration-platform/). - -## [Install and Configure](https://docs.sentry.io/organization/integrations/compliance/vanta/\#install-and-configure) - -Sentry owner, manager, or admin permissions are required to install this integration. - -1. Navigate to **Settings > Integrations > Vanta** - -2. Follow the full [Vanta installation instructions](https://help.vanta.com/hc/en-us/articles/13045851267092). - - -[Previous\\ -\\ -Truto](https://docs.sentry.io/organization/integrations/compliance/truto) - -[Next\\ -\\ -Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/vanta/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/) - -# How to Write - Configuration - -The Configuration section of the content covers, unsurprisingly, how customers can configure an SDK. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/configuration/` \- feel free to peruse the files in that directory to help answer any questions. - -Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. - -Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions if any questions arise by opening an issue on GitHub. - -## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#start-here) - -Determine if the page applies: - -- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. -- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting that customers open an issue for the missing sample. - -### [Basic Options](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#basic-options) - -This file is `options.mdx`. It explains all the configuration options. - -To develop content for this file: - -1. Create the `configuration/config-intro/` statement, which covers how options can be set. - -2. For individual options that the guide does NOT support, add the name of the guide to the `ConfigKey` statement for that option. This will prevent that option from displaying for this SDK. For example: - -`<ConfigKey name="debug" notSupported={["javascript.react"]}>` - -Alternately, for individual options that the guide DOES support, add the name of the guide to `ConfigKey` statement for that option, which ensures the option displays. For example: - -`<ConfigKey name="send-default-pii" supported={["javascript.electron", "javascript.ember"]}>` - -3. For a grouping of options that the guide DOES support, add the name of the guide to the `PlatformSection` statement for those options, which ensures the option displays. For example: - -`<PlatformSection supported={["javascript.react"]}>` - - -### [Releases & Health](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#releases--health) - -This file is `releases.mdx`. It explains how to configure the SDK to tell Sentry about releases. Provide a code sample for this SDK to set a release, then add the code sample to this directory: - -- `/platform-includes/set-release/` - -A few nuances: - -- If adding an SDK related to JavaScript, update the source maps-related paragraph, as appropriate, in the `PlatformSection supported` statement. -- For SDKs that support release health, we control the display of content with a `PlatformSection supported` statement. For these SDKs, provide the following code sample: Opt out of auto session tracking, stored in `/platform-includes/configuration/auto-session-tracking`. - -### [Environments](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#environments) - -This file is `environments.mdx`. It explains how to configure the SDK to set an environment. - -Add the code sample to this directory: - -- `/platform-includes/set-environment/` - -### [Filtering Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#filtering-events) - -This file is `filtering.mdx`. It explains how to configure the SDK to filter events sent to Sentry. Add code samples to these directories: - -- `/platform-includes/configuration/before-send/` -- `/platform-includes/configuration/before-send-hint/` - -Enable or disable the content for "Using Hints", as appropriate to the SDK, by adding it to the list of either `supported` or `notSupported`, then add code sample to these directories: - -- `/platform-includes/configuration/before-send-fingerprint/` -- `/platform-includes/configuration/decluttering/` - -Enable or disable the content for "Using Sampling to Filter Transaction Events" by adding the SDK to the list of either `supported` or `notSupported`, then add code sample to this directory: - -- `/platform-includes/performance/traces-sampler-as-filter/` - -### [Sampling Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#sampling-events) - -This file is `sampling.mdx`. It explains how to set the sample rate for the SDK. - -Add code samples to these directories: - -- `/platform-includes/configuration/sample-rate/` -- `/platform-includes/performance/uniform-sample-rate/` -- `/platform-includes/performance/sampling-function-intro/` -- `/platform-includes/performance/default-sampling-context` -- `/platform-includes/performance/custom-sampling-context` -- `/platform-includes/performance/always-inherit-sampling-decision` -- `/platform-includes/performance/force-sampling-decision` - -### [Shutdown and Draining](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#shutdown-and-draining) - -This file is `draining.mdx`. Add the drain example content to this directory: - -- `/platform-includes/configuration/drain-example/` - -### [Integrations](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration/\#integrations) - -This content is developed at the primary SDK/platform level. It resides in `/docs/platforms/<SDK>/integrations/` or `/docs/platforms/<SDK>/common/integrations/` and is typically composed of the following: - -1. Default Integrations - `default.mdx` \- system integrations are enabled by default. We document them so customers can both be aware of what they do and disable them if they cause issues. -2. Pluggable Integrations - `plugin.mdx` \- pluggable integrations are snippets of code that augment functionality for specific applications and/or frameworks. We document them so customers can see what they do and that they can be enabled. -3. Custom Integrations - `custom.mdx` \- explains how to enable a custom integration. - -[Previous\\ -\\ -How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started) - -[Next\\ -\\ -How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-configuration.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Sending Events](https://docs.sentry.io/cli/send-event/) - -# Sending Events - -## Learn how Sentry's command line interface can be used for sending events. - -The `sentry-cli` tool can also be used for sending events. If you want to use it, you need to export the `SENTRY_DSN` environment variable and point it to the DSN of a project of yours: - -Bash - -`` - -```bash code-highlight -export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0' - -``` - -Once that is done, you can start using the `sentry-cli send-event` command. - -## [Basic Events](https://docs.sentry.io/cli/send-event/\#basic-events) - -For basic message events, you just need to provide the `--message` or `-m` parameter to send a message: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m "Hello from Sentry" - -``` - -This will send a single message to Sentry and record it as an event. Along with that event, it sends basic information about the machine you are running `sentry-cli` on. You can provide `-m` multiple times to send multiple lines: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m "Hello from Sentry" -m "This is more text" - -``` - -## [Events with Parameters](https://docs.sentry.io/cli/send-event/\#events-with-parameters) - -In addition you can use `%s` as placeholder in a message and fill it in with the `-a` parameter. This helps reviewing them, as all messages will be grouped together automatically: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m "Hello %s!" -a "Joe" -sentry-cli send-event -m "Hello %s!" -a "Peter" - -``` - -## [Sending Breadcrumbs](https://docs.sentry.io/cli/send-event/\#sending-breadcrumbs) - -You can also pass a logfile to the `send-event` command which will be parsed and sent along as breadcrumbs. The last 100 items will be sent: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m “task failed” –-logfile error.log - -``` - -The logfile can be in various formats. If you want to create one yourself you can do something along those lines: - -Bash - -`` - -```bash code-highlight -echo "$(date +%c) This is a log record" >> output.log -echo "$(date +%c) This is another record" >> output.log -sentry-cli send-event -m "Demo Event" --logfile output.log -rm output.log - -``` - -## [Extra Data](https://docs.sentry.io/cli/send-event/\#extra-data) - -Extra data can be attached with the `-e` parameter as `KEY:VALUE`. For instance, you can send some key value pairs like this: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m "a failure" -e task:create-user -e object:42 - -``` - -Likewise, tags can be sent with `-t` using the same format: - -Bash - -`` - -```bash code-highlight -sentry-cli send-event -m "a failure" -t task:create-user - -``` - -## [Stored Events](https://docs.sentry.io/cli/send-event/\#stored-events) - -As of version `1.71`, the `send-event` command can accept an optional argument that specifies a path to the stored JSON representation of an [event payload](https://develop.sentry.dev/sdk/data-model/event-payloads/). When used, it will load the file, validate the event and send it to Sentry. - -Bash - -`` - -```bash code-highlight -sentry-cli send-event ./events/20211029150006.json - -``` - -This argument can be also provided in the form of a glob, which will cause it to process all matched events. - -Bash - -`` - -```bash code-highlight -sentry-cli send-event "./events/*.json" - -``` - -If `send-event` is called with the `--raw` flag, the event will not be validated before being sent. - -Bash - -`` - -```bash code-highlight -sentry-cli send-event --raw ./events/20211029150006.json - -``` - -## [Specifying Releases](https://docs.sentry.io/cli/send-event/\#specifying-releases) - -Releases can be sent with the `--release` parameter. A default release is picked up automatically if you are using sentry-cli from within a git repository. - -## [Bash Hook](https://docs.sentry.io/cli/send-event/\#bash-hook) - -For bash scripts you can also enable automatic error sending by using the sentry-cli bash hook. That enables `set -e` and will send a Sentry event for unhandled errors. - -The limitations for this are: - -- sentry-cli really only works if `set -e` is enabled (which it will by default enable for you). -- sentry-cli registers an `EXIT` and `ERR` trap. - -Usage: - -Bash - -`` - -```bash code-highlight -#!/bin/bash -export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0' -eval "$(sentry-cli bash-hook)" -# rest of the script goes here - -``` - -Alternatively you can use other mechanisms like [a `.sentryclirc` file](https://docs.sentry.io/cli/configuration/#configuration-file) to configure the DSN. - -[Previous\\ -\\ -Debug Information Files](https://docs.sentry.io/cli/dif) - -[Next\\ -\\ -Crons (CLI)](https://docs.sentry.io/cli/crons) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/send-event.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Markdown Variables](https://docs.sentry.io/contributing/pages/variables/) - -# Markdown Variables - -A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within `remark-variables.js`. - -For example: - -ReplacmentSource - -`` - -```code-highlight markdown -JavaScript SDK: 9.3.0 - -``` - -In this case, we expose `packages` as an accessor in the package registry, which is why there's a `packages.version` function available. Additionally, we expose a default context variable of `page`, which contains the frontmatter of the given markdown node. For example, `{{@inject page.title }}`. - -When a variable call is invalid (or errors), or doesn't match something in the known scope, it will produce an error message in the output in development mode. It will force the build to fail in production. - -To escape an expression add a leading `\` to the `@inject`. - -## [`packages`](https://docs.sentry.io/contributing/pages/variables/\#packages) - -The `packages` helper is an instance of `PackageRegistry` and exposes several methods. - -### [`packages.version`](https://docs.sentry.io/contributing/pages/variables/\#packagesversion) - -Returns the latest version of the given package. - -Source - -`` - -```text code-highlight -{{@inject packages.version("sentry.javascript.browser") }} - -``` - -You may also optionally specify a fallback for if the package isn't found (or there's an upstream error): - -Source - -`` - -```text code-highlight -{{@inject packages.version("sentry.javascript.browser", "1.0.0") }} - -``` - -### [`packages.checksum`](https://docs.sentry.io/contributing/pages/variables/\#packageschecksum) - -Returns the checksum of a given file in a package. - -Source - -`` - -```text code-highlight -{{@inject packages.checksum("sentry.javascript.browser", "bundle.min.js", "sha384") }} - -``` - -[Previous\\ -\\ -MDX Components](https://docs.sentry.io/contributing/pages/components) - -[Next\\ -\\ -Redirects](https://docs.sentry.io/contributing/pages/redirects) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/variables.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) -- [Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/) - -# Amazon SQS - -## Learn about Sentry's Amazon SQS integration, which allows you to forward Sentry events to Amazon SQS for further analysis. - -Amazon SQS is useful for a more in-depth analysis of exceptions, making it quick and easy to pipe exceptions back into your own systems. Or, use it to empower other teams, such as a Business Intelligence function. - -This integration needs to be set up in each project for which you wish to use it. It is maintained and supported by the [Sentry community](https://open.sentry.io/). - -## [Install and Configure](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/\#install-and-configure) - -Sentry owner, manager, or admin permissions are required to install this integration. - -Navigate to **Settings > Integrations > Amazon SQS** - -[![Install Amazon SQS integration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Famazon-sqs-OYODE3CU.png%231500x666&w=3840&q=75)](https://docs.sentry.io/mdx-images/amazon-sqs-OYODE3CU.png) - -### [Data Forwarding](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/\#data-forwarding) - -Configure [data forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) in **\[Project\] > Settings > Data Forwarding**, and provide the required information for the given integration. - -The payload for Amazon is identical to our standard API event payload and will evolve over time. For more details on the format of this data, see our [API documentation](https://docs.sentry.io/api/events/retrieve-an-event-for-a-project/). - -[Previous\\ -\\ -Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization) - -[Next\\ -\\ -Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/amazon-sqs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) - -# Pages - -Documentation is written in Markdown (via Remark) and MDX. - -[`Read the quick reference`](https://daringfireball.net/projects/markdown/syntax) - -## [Additional Topics](https://docs.sentry.io/contributing/pages/\#additional-topics) - -[Previous\\ -\\ -Linking Variables](https://docs.sentry.io/contributing/linking) - -[Next\\ -\\ -Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) - -# Issue Grouping - -## Learn about fingerprinting, Sentry's default error grouping algorithms, and other ways to customize how events are grouped into issues. - -A fingerprint is a way to uniquely identify an event, and all events have one. Events with the same fingerprint are grouped together into an issue. - -By default, Sentry will run one of our built-in grouping algorithms to generate an event fingerprint based on information available within the event. The available information and the grouping algorithms vary by event type. Sentry fingerprints error events based on information like `stacktrace`, `exception`, and `message`. Transaction events are fingerprinted by their `spans`. - -## [Default Error Grouping Algorithms](https://docs.sentry.io/concepts/data-management/event-grouping/\#default-error-grouping-algorithms) - -Each time default error grouping behavior is modified, Sentry releases it as a new version. As a result, modifications to the default behavior do not affect the grouping of existing issues. - -When you create a Sentry project, the most recent version of the error grouping algorithm is automatically selected. This ensures that grouping behavior is consistent within a project. - -To upgrade an existing project to a new error grouping algorithm version, navigate to **Settings > Projects > \[project\] > Issue Grouping > Upgrade Grouping**. After upgrading to a new error grouping algorithm, you will very likely see new groups being created. - -All versions consider the `fingerprint` first, the `stack trace` next, then the `exception`, and then finally the `message`. - -To see how an isssue was grouped, go to its **Issue Details** page and scroll down to "Event Grouping Information". There, you'll see if it was grouped by a fingerprint, stack trace, exception, or message. - -### [Grouping by Built-In Fingerprinting Rules](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-built-in-fingerprinting-rules) - -Some kinds of errors, like [chunk load errors](https://sentry.io/answers/chunk-load-errors-javascript/) and [hydration errors](https://sentry.io/answers/hydration-error-nextjs/), often have various different error types, values, or transaction messsages that may result in separate but similar issues. To better handle these cases, Sentry maintains a set of built-in fingerprinting rules to better group such errors. - -Issues grouped by Sentry's built-in fingerprinting rules will list "Sentry Defined Fingerprint" in the "Event Grouping Information" at the bottom of the **Issue Details** page. - -[![event grouping information for a sentry defined fingerprint](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-defined-fingerprint-7P7JYDQM.png%231372x706&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-defined-fingerprint-7P7JYDQM.png) - -Built-in fingerprinting rules work the same as custom fingerprinting rules and are applied by default. If an user defined custom fingerprinting rule matches an event, the custom rule will always take precedence over the built-in ones. - -### [Grouping by Stack Trace](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-stack-trace) - -When Sentry detects a stack trace in the event data (either directly or as part of an exception), the grouping is effectively based entirely on the stack trace. - -The first and most crucial part is that Sentry only groups by stack trace frames that the SDK reports and associates with your application. Not all SDKs report this, but when that information is provided, it’s used for grouping. This means that if two stack traces differ only in parts of the stack that are unrelated to the application, those stack traces will still be grouped together. - -Depending on the information available, the following data can be used for each stack trace frame: - -- Module name -- Normalized filename (with revision hashes, and so forth, removed) -- Normalized context line (essentially a cleaned up version of the source code of the affected line, if provided) - -This grouping usually works well, but two specific situations can throw it off: - -1. Minimized JavaScript source code will destroy the grouping in detrimental ways. To avoid this, ensure that Sentry can access your [Source Maps](https://docs.sentry.io/platforms/javascript/sourcemaps/). -2. Modifying your stack trace by introducing a new level through decorators changes your stack trace, so the grouping will also change. To handle this, many SDKs support hiding irrelevant stack trace frames. For example, the Python SDK will skip all stack frames with a local variable called `__traceback_hide__` set to _True_. - -### [Grouping By Exception](https://docs.sentry.io/concepts/data-management/event-grouping/\#grouping-by-exception) - -If the stack trace is not available, but exception information is, then the grouping will consider the `type` and `value` of the exception if both pieces of data are present on the event. This grouping is a lot less reliable because of changing error messages. - -### [Fallback Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#fallback-grouping) - -Grouping falls back to messages if the stack trace, `type`, and `value` are not available. When this happens, the grouping algorithm will try to use the message without any parameters. If that is not available, the grouping algorithm will use the full message attribute. - -### [AI-Enhanced Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#ai-enhanced-grouping) - -In addition to fingerprint-based grouping, Sentry uses AI to further improve issue grouping accuracy. This system helps identify semantically similar errors that might have different fingerprints due to minor code variations. The AI grouping system works alongside traditional fingerprinting - it only attempts to group new issues and will never split up issues that were grouped by fingerprint. - -This system will not apply to any events that have fully custom fingerprints (either set via SDK or [fingerprint rules](https://docs.sentry.io/product/issues/grouping-and-fingerprints/#fingerprint-rules)). However, events with fingerprints containing `{{ default }}` will use AI grouping to calculate the `{{ default }}` portion of the fingerprint. - -When Sentry's default fingerprinting algorithm generates a new hash, it automatically sends the error data to [Seer](https://github.com/getsentry/seer), our AI/ML service. That error data includes the message and in-app stack frames (including those configured with stack trace rules), or all frames when no in-app frames are present. - -Seer performs the following steps: - -1. It generates a vector representation of the error's stack trace using a transformer-based text embedding model -2. It compares this embedding against existing error embeddings for that project in the database -3. If a semantically similar error is found within the configured threshold, Sentry merges the new error into the existing issue - -[![Sentry Seer PostgreSQL.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-seer-postgresql-LJOM3IZL.png%231024x365&w=2048&q=75)](https://docs.sentry.io/mdx-images/sentry-seer-postgresql-LJOM3IZL.png) - -This algorithm is particularly effective at handling cases where: - -- Similar errors occur in different parts of the codebase -- Code changes or deployments introduce slight variations in stack traces -- Different error types represent the same underlying problem - -You can see issues that have been merged through this system in the “Merged Issues” section of the Issue Details UI. You can always unmerge any fingerprints that you would not like to see grouped, and our system will avoid grouping them in the future. - -[![Merged issues.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmerged-issues-AQLAWKNX.png%23653x302&w=1920&q=75)](https://docs.sentry.io/mdx-images/merged-issues-AQLAWKNX.png) - -## [Ways to Customize Error Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/\#ways-to-customize-error-grouping) - -If the way that Sentry is grouping issues for your organization is already ideal, you don't need to make any changes. However, you may find that Sentry is either creating too many similar groups, or is grouping disparate events into groups that should be separate. If this is the case, for **error issues**, you can extend and change the default grouping behavior. Error grouping can be extended and changed completely according to your needs. Transaction grouping currently cannot be customized. - -You can customize error grouping using a combination of the following options, listed from least to most complex: - -1. In your project, by [Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues/) - -> Merges together similar issues that have already been created. No settings or configuration changes are required for this. - -2. In your project, using [Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) - -> Sets a new fingerprint for incoming events based on matchers. This doesn't affect already existing issues. - -3. In your project, using [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/) - -> Sets rules for how incoming events should be treated based on matchers. This doesn't affect already existing issues. - -4. In your SDK, using [SDK Fingerprinting](https://docs.sentry.io/platform-redirect/?next=/usage/sdk-fingerprinting/) - -> Sets a new fingerprint for incoming events based on matchers in the SDK. This doesn't affect already existing issues. Note that is not supported in WebAssembly. - - -Stack trace rules can work as a combination of both SDK and project settings. As a result, we maintain the documentation in one location. - -## [How to View the Fingerprint](https://docs.sentry.io/concepts/data-management/event-grouping/\#how-to-view-the-fingerprint) - -You can see a fingerprint by opening an issue, clicking " View JSON", and finding the _fingerprint_ property in that file. If the default grouping was used, you'll see "default" written there. If a different grouping was used, you'll see the actual fingerprint value itself. - -View Issue Fingerprint - -View Issue Fingerprint - -![Find the "fingerprint" property. Here, the default grouping was used.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/5658b67b-26f6-43e4-b387-5f03fec20a58.png)![Step 3](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/a7572aab-076a-43a1-b9c2-2c13a5b9bddb.png)![Click to open the JSON file.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/75e0d829-0db7-43f6-ac17-4d3a363f7015.png) - -Click to open the JSON file. - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -[iframe](cid:frame-935AB59C0A5CD926EDCF406CE7365D34@mhtml.blink) - -## [Transaction Grouping Algorithms](https://docs.sentry.io/concepts/data-management/event-grouping/\#transaction-grouping-algorithms) - -Sentry groups transactions with performance problems into [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) using the transaction's `spans`. We fingerprint by the span evidence related to the performance problem found in the event. This includes the spans directly involved in the problem, as well as spans that might have caused the problem or are closely related to it. This algorithm isn't currently customizable or extendable. - -## [Learn More](https://docs.sentry.io/concepts/data-management/event-grouping/\#learn-more) - -[Previous\\ -\\ -Data Management](https://docs.sentry.io/concepts/data-management) - -[Next\\ -\\ -Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Permissions & Scopes](https://docs.sentry.io/api/permissions/) - -# Permissions & Scopes - -If you're building on top of Sentry's API (i.e using [Auth Tokens](https://docs.sentry.io/api/auth/)), you'll need certain scopes to access different API endpoints. - -To set the scopes for an [integration token](https://docs.sentry.io/organization/integrations/integration-platform/#permissions), select the scopes from the dropdown. These can be edited later. - -To set the scopes for an auth token, select the scopes from the dropdown when [creating an auth token](https://sentry.io/api/). These cannot be edited later. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fuser-auth-token-create-ZKQIPVXA.png%232396x1404&w=3840&q=75)](https://docs.sentry.io/mdx-images/user-auth-token-create-ZKQIPVXA.png) - -If you're looking for information on membership roles please visit the [membership](https://docs.sentry.io/organization/membership/) documentation. - -### [Organizations](https://docs.sentry.io/api/permissions/\#organizations) - -| | | -| --- | --- | -| **GET** | `org:read` | -| **PUT/POST** | `org:write` | -| **DELETE** | `org:admin` | - -### [Projects](https://docs.sentry.io/api/permissions/\#projects) - -| | | -| --- | --- | -| **GET** | `project:read` | -| **PUT/POST** | `project:write` | -| **DELETE** | `project:admin` | - -##### Note - -The `project:releases` scope will give you access to both **project** and **organization** release endpoints. The available endpoints are listed in the [Releases](https://docs.sentry.io/api/releases/) section of the API Documentation. - -### [Teams](https://docs.sentry.io/api/permissions/\#teams) - -| | | -| --- | --- | -| **GET** | `team:read` | -| **PUT/POST** | `team:write` | -| **DELETE** | `team:admin` | - -### [Members](https://docs.sentry.io/api/permissions/\#members) - -| | | -| --- | --- | -| **GET** | `member:read` | -| **PUT/POST** | `member:write` | -| **DELETE** | `member:admin` | - -### [Issues & Events](https://docs.sentry.io/api/permissions/\#issues--events) - -| | | -| --- | --- | -| **GET** | `event:read` | -| **PUT** | `event:write` | -| **DELETE** | `event:admin` | - -##### Note - -**PUT/DELETE** methods only apply to updating/deleting issues. Events in Sentry are immutable and can only be deleted by deleting the whole issue. - -### [Releases](https://docs.sentry.io/api/permissions/\#releases) - -| | | -| --- | --- | -| **GET/PUT/POST/DELETE** | `project:releases` | - -##### Note - -Be aware that if you're using `sentry-cli` to [manage your releases](https://docs.sentry.io/cli/releases/), you'll need a token which also has `org:read` scope. - -[Previous\\ -\\ -Paginating Results](https://docs.sentry.io/api/pagination) - -[Next\\ -\\ -Rate Limits](https://docs.sentry.io/api/ratelimits) - -- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) - -# Authentication - -[Previous\\ -\\ -Set Up Your Organization](https://docs.sentry.io/organization/getting-started) - -[Next\\ -\\ -Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) - -# Searchable Properties - -## Learn more about searchable properties. - -Sentry's search provides you with reserved keywords, like `is`, `user`, `server`, and `browser`, that you can use to search on the properties of issues, events and replays (as well as the special case of releases). You can also create [custom tags](https://docs.sentry.io/concepts/search/searchable-properties/#custom-tags) on which to search. This page provides guidance for how to use these properties and links you to the respective seachable property lists. - -## [Search Properties](https://docs.sentry.io/concepts/search/searchable-properties/\#search-properties) - -Sentry's searchable properties fall into one of five categories: - -- [Issue properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/) -- [Event properties](https://docs.sentry.io/concepts/search/searchable-properties/events/) -- [Span properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) -- [Session Replay properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/) -- [User Feedback properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/) -- [Release properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/) - -## [Search Tips](https://docs.sentry.io/concepts/search/searchable-properties/\#search-tips) - -Search terms should auto-complete, and when they don't that means you have an invalid dataset. If you enter an invalid search term and tap Return or Enter, an error message is displayed. For example, in **Discover**, you cannot search using a grouping function (properties with a parentheses in the key, for example `epm()`) if you don't already have a grouping function included in the "Results" table columns. - -When you search using a property that's a function, if the key includes a parameter, you still need to add a filter or value to have a complete search token. For example, the function `count_unique(field)` takes whichever field you choose as the parameter and then you add a number as your value to filter on. So a typical search might look like: `count_unique(user):>=20`. - -Other things to note: - -- Search properties that are duration or number types are typically used with a [comparison operator](https://docs.sentry.io/concepts/search/#comparison-operators) rather than just a colon ( `:`) to find exact matches, as an exact match is unlikely to exist. -- Properties with the notation "Doesn't take a parameter" still require a filter or value, but don't take a parameter inside the parentheses. For example, `epm():>12`. -- Default fields/parameters in search functions can be updated. For example, the default parameters `column`, `operator`, and `value` can be updated for `count_if(column,operator,value)`. - -## [Custom Tags](https://docs.sentry.io/concepts/search/searchable-properties/\#custom-tags) - -Additionally, you can use any tag you’ve specified as a token. Tags are various key/value pairs that get assigned to an event, and you can use them later as a breakdown or quick access to finding related events. - -Most SDKs generally support configuring tags by [configuring the scope](https://docs.sentry.io/platform-redirect/?next=%2Fenriching-events%2Ftags%2F). - -Several common uses for tags include: - -- The hostname of the server -- The version of your platform (for example, iOS 5.0) -- The user’s language - -## [Device Classification](https://docs.sentry.io/concepts/search/searchable-properties/\#device-classification) - -`device.class` provides a simple way for developers to understand the performance level of an event's client device in a single searchable property. This is particularly useful for projects that serve a large range of mobile devices, in which case developers would typically have had to parse through a vast range of specs and models across iOS and Android. - -Possible values for `device.class` are `high`, `medium`, and `low`, indicating the estimated performance level of the device. This is a calculated property that is based on the following specs: - -| `device.class` for iOS | `model` | -| --- | --- | -| high | iPhone 12 series or higher | -| medium | iPhone 7 series to iPhone 11 series | -| low | iPhone 6 series or lower | - -| `device.class` for Android | `processor_count` | `processor_frequency` | `memory_size` | -| --- | --- | --- | --- | -| high | >= 8 | >= 2500 MHz | >= 6 GiB | -| medium | >= 8 | >= 2000 MHz | >= 4 GiB | -| low | < 8 | < 2000 MHz | < 4 GiB | - -These classifications are based on an analysis of the mobile devices available in the market today and are subject to change as the market evolves. - -[Previous\\ -\\ -Search](https://docs.sentry.io/concepts/search) - -[Next\\ -\\ -Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) - -# Organization Settings - -## Learn how to configure your organization's Sentry account, including 2FA authentication, user management, and data storage location. - -[Previous\\ -\\ -Account Settings](https://docs.sentry.io/account) - -[Next\\ -\\ -Set Up Your Organization](https://docs.sentry.io/organization/getting-started) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Metrics](https://docs.sentry.io/cli/metrics/) - -# Metrics - -## Learn how Sentry's command line interface can be used for sending metrics. - -##### The Metrics beta has ended on October 7th - -Thank you for participating in our Metrics beta program. After careful consideration, we have ended the beta program and retired the current Metrics solution. We're actively developing a new solution that will make tracking and debugging any issues in your application easier. [Learn more](https://sentry.zendesk.com/hc/en-us/articles/26369339769883-Upcoming-API-Changes-to-Metrics). - -Metrics help you track and visualize the data points you care about, making it easier to monitor your application's health and identify issues. Learn more about [Metrics](https://docs.sentry.io/product/explore/metrics/). - -## [Requirements](https://docs.sentry.io/cli/metrics/\#requirements) - -- [Install](https://docs.sentry.io/cli/installation/) the Sentry CLI (min v2.32.0). - -## [Configuration](https://docs.sentry.io/cli/metrics/\#configuration) - -The Sentry CLI uses your project's DSN to authorize sending metrics. To set it up, export the `SENTRY_DSN` environment variable: - -Bash - -`` - -```bash code-highlight -export SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 - -``` - -Alternatively, you can add it to your `~/.sentryclirc` config file: - -Ini - -`~/.sentryclirc` - -```code-highlight ini -[auth] -dsn = https://examplePublicKey@o0.ingest.sentry.io/0 - -``` - -## [Sending metrics](https://docs.sentry.io/cli/metrics/\#sending-metrics) - -You can send metrics using the CLI's `send-metric` command. You need to provide at least the `--name` or `-n` parameter to identify the metric. When emitting a metric that doesn't exist, the metric will be created for you. If it already exists, it will be updated. All metric types support custom units and tags provided with the `-u` and `-t` parameters respectively: - -Bash - -`` - -```bash code-highlight -sentry-cli send-metric increment -n "MyMetric" -u "MyUnit" -t "tag1:val1","tag2:val2" - -``` - -The metric's name, unit, and tags will undergo normalization to only include supported characters. Learn more about [Limits and Restrictions](https://docs.sentry.io/product/explore/metrics/#limits-and-restrictions). - -### [Counters](https://docs.sentry.io/cli/metrics/\#counters) - -To increment a counter metric by one, you only need to provide the `--name` or `-n` parameter. A counter metric can also be incremented by a custom value using the `-v` parameter: - -Bash - -`` - -```bash code-highlight -sentry-cli send-metric increment -n "button_click" -v 2 - -``` - -### [Gauges](https://docs.sentry.io/cli/metrics/\#gauges) - -To emit a gauge metric, you always need to provide the name and value: - -Bash - -`` - -```bash code-highlight -sentry-cli send-metric gauge -n "bundle_size" -v 384 -u "byte" - -``` - -### [Distributions](https://docs.sentry.io/cli/metrics/\#distributions) - -Similar to gauges, you need to provide the name and value to emit a distribution metric: - -Bash - -`` - -```bash code-highlight -sentry-cli send-metric distribution -n "build_time" -v 120 -u "millisecond" - -``` - -### [Sets](https://docs.sentry.io/cli/metrics/\#sets) - -To emit a set metric, you need to provide the name and value where the value can be any number or string: - -Bash - -`` - -```bash code-highlight -sentry-cli send-metric set -n "build_platform" -v "android" - -``` - -[Previous\\ -\\ -Sentry CLI](https://docs.sentry.io/cli) - -[Next\\ -\\ -Installation](https://docs.sentry.io/cli/installation) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/metrics.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Requests](https://docs.sentry.io/api/requests/) - -# Requests - -All API requests should be made to the `/api/0/` prefix, and will return JSON as the response: - -BashHttp - -`` - -```bash code-highlight -curl -i https://sentry.io/api/0/ - -``` - -## [HTTP Verbs](https://docs.sentry.io/api/requests/\#http-verbs) - -Sentry makes an attempt to stick to appropriate HTTP verbs, but we always prioritize usability over correctness. - -| Method | Description | -| --- | --- | -| `DELETE` | Used for deleting resources. | -| `GET` | Used for retrieving resources. | -| `OPTIONS` | Describes the given endpoint. | -| `POST` | Used for creating resources. | -| `PUT` | Used for updating resources. Partial data is accepted where possible. | - -## [Parameters and Data](https://docs.sentry.io/api/requests/\#parameters-and-data) - -Any parameters not included in the URL should be encoded as JSON with a Content-Type of `'application/json'`: - -Bash - -`` - -```bash code-highlight -curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/ \ - -d '{"status": "resolved"}' \ - -H 'Content-Type: application/json' - -``` - -Additional parameters are sometimes specified via the querystring, even for `POST`, `PUT`, and `DELETE` requests: - -Bash - -`` - -```bash code-highlight -curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/?status=unresolved \ - -d '{"status": "resolved"}' \ - -H 'Content-Type: application/json' - -``` - -[Previous\\ -\\ -Rate Limits](https://docs.sentry.io/api/ratelimits) - -[Next\\ -\\ -Alerts & Notifications](https://docs.sentry.io/api/alerts) - -- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) - -# API Reference - -The Sentry web API is used to access the Sentry platform programmatically. You can use the APIs to manage account-level resources, like organizations and teams, as well as manage and export data. - -If you're looking for information about the API surface for Sentry's SDKs, see the [SDK Development](https://develop.sentry.dev/sdk/overview/) docs. - -## [Versioning](https://docs.sentry.io/api/\#versioning) - -The current version of the Sentry's web API is considered **v0**. Our public endpoints are generally stable, but beta endpoints are subject to change. - -## [Getting Started](https://docs.sentry.io/api/\#getting-started) - -- [Authentication](https://docs.sentry.io/api/auth/) -- [Pagination](https://docs.sentry.io/api/pagination/) -- [Permissions](https://docs.sentry.io/api/permissions/) -- [Rate Limits](https://docs.sentry.io/api/ratelimits/) -- [Requests](https://docs.sentry.io/api/requests/) - -### [Sentry API Tutorials](https://docs.sentry.io/api/\#sentry-api-tutorials) - -- [Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) -- [Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial/) - -## [Choosing the Right API Base Domain](https://docs.sentry.io/api/\#choosing-the-right-api-base-domain) - -While many of our APIs use `sentry.io` as the host for API endpoints, if you want to indicate a specific [data storage location](https://docs.sentry.io/organization/data-storage-location/#what-types-of-data-are-stored-where), you should use region-specific domains. - -- US region is hosted on `us.sentry.io` -- DE region is hosted on `de.sentry.io`. - -To find out which API resources are available on region-based domains, see [what types of data are stored where](https://docs.sentry.io/organization/data-storage-location/#what-types-of-data-are-stored-where) for more information. - -[Previous\\ -\\ -Sentry CLI](https://docs.sentry.io/cli) - -[Next\\ -\\ -Authentication](https://docs.sentry.io/api/auth) - -- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Search](https://docs.sentry.io/contributing/pages/search/) - -# Search - -Search is powered by Algolia, and will index all content in `/docs/` that is Markdown or MDX formatted. - -It will _not_ index documents with any of the following in their frontmatter: - -- `draft: true` -- `noindex: true` - -[Previous\\ -\\ -Redirects](https://docs.sentry.io/contributing/pages/redirects) - -[Next\\ -\\ -Banners](https://docs.sentry.io/contributing/pages/banners) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/search.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Account Settings](https://docs.sentry.io/account/) -- [Account Preferences](https://docs.sentry.io/account/user-settings/) - -# Account Preferences - -## Learn how to customize your User Settings for a more personalized Sentry experience. - -[Account preferences](https://sentry.io/settings/account/details/) help you customize your Sentry experience. Manage your account by selecting "User settings" from the dropdown under your organization’s name. On this page, you can control the frequency of your [email notifications](https://docs.sentry.io/account/user-settings/#notifications), [change your primary email](https://docs.sentry.io/account/user-settings/#emails), and update your security settings. - -## [Security Settings](https://docs.sentry.io/account/user-settings/\#security-settings) - -Security Settings include options to reset a password, sign out of all devices, and enable two-factor authentication. - -### [Two-Factor Authentication](https://docs.sentry.io/account/user-settings/\#two-factor-authentication) - -After setting up your two-factor authentication codes, click "View Codes" to download, print, or copy your codes to a secure location. If you cannot receive two-factor authentication codes in the future, such as if you lose your device, use your recovery codes to access your account. - -Clicking "Sign out of all devices" will end your sessions with any device logged in to Sentry using your account. - -## [Notifications](https://docs.sentry.io/account/user-settings/\#notifications) - -In **Notifications**, you can configure your personal settings for the following Sentry notifications: - -- Alerts (issue alerts only) -- Deploy -- Workflow -- Weekly Reports -- My Activity - -You can also set your email routing here. - -Learn more in the [full Notifications documentation](https://docs.sentry.io/product/alerts/notifications/). - -## [Emails](https://docs.sentry.io/account/user-settings/\#emails) - -The email address used to log into your Sentry account is, by default, your primary email address. Add an alternative email address in the [Add Secondary Emails](https://sentry.io/settings/account/emails/) section. After verifying your secondary email, you can set it to become your primary email. - -[![After verifying the secondary email, you can change it to the primary email.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fchange-primary-email-WHCEW7FR.png%231500x514&w=3840&q=75)](https://docs.sentry.io/mdx-images/change-primary-email-WHCEW7FR.png) - -## [Close Account](https://docs.sentry.io/account/user-settings/\#close-account) - -Warning: Deleting your account cannot be undone. - -Closing your Sentry account automatically [removes all data](https://sentry.io/security/#data-removal) associated with your account after a 24-hour waiting period to prevent accidental cancellation. If your account is the sole owner of an organization, this organization will be deleted. Organizations with multiple owners will remain unchanged. For details about termination of service, see [Term, Termination, and Effect of Termination](https://sentry.io/terms/#term-termination-and-effect-of-termination). - -[Previous\\ -\\ -Account Settings](https://docs.sentry.io/account) - -[Next\\ -\\ -Auth Tokens](https://docs.sentry.io/account/auth-tokens) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/user-settings/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) - -# Data & Visualization - -## Learn more about Sentry's data and visualization integrations. - -- [Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs/) -- [Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana/) -- [Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment/) -- [Splunk](https://docs.sentry.io/organization/integrations/data-visualization/splunk/) - -[Previous\\ -\\ -Deployment](https://docs.sentry.io/organization/integrations/deployment) - -[Next\\ -\\ -Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling/) - -# Dynamic Sampling - -## Learn how to prioritize important events and increase visibility in lower-volume projects with Dynamic Sampling. - -## [Overview](https://docs.sentry.io/organization/dynamic-sampling/\#overview) - -Projects that generate large event volume can quickly consume your billing quota. This may create an imbalance where high-volume projects get more visibility, leaving insufficient quota for monitoring your other projects. That's where dynamic sampling comes in. - -Dynamic Sampling employs advanced sampling techniques to retain a representative sample of the data you send to Sentry. Its algorithms are designed to prioritize keeping samples that are valuable for debugging and analysis, while reducing the retention of common or redundant data. - -This process is applied directly on Sentry's servers, which allows you to configure and adjust sampling rates for stored spans right from the UI without needing to modify your SDK. This makes it possible for you to make instant updates without waiting for code freezes, app store approvals, or redeployments. - -By analyzing incoming traffic patterns, Dynamic Sampling is able to tailor its decisions to both the actual traffic volume as well as the content of accepted spans. For more details, check out the [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) section. - -Dynamic Sampling including Sampling Priorities has been available on paid plans since November 2022. Configuration of custom sample rates has been available on our latest Enterprise plans since June 2024. - -## [Prerequisites](https://docs.sentry.io/organization/dynamic-sampling/\#prerequisites) - -- [Admin-level permissions](https://docs.sentry.io/organization/membership/). -- Latest version of one of the below SDKs: - - Python: 1.7.2 or later - - JavaScript: 7.6.0 or later - - Apple: 7.23.0 or later - - Android: 6.5.0 or later - - React Native: 4.3.0 or later - - Dart and Flutter: 6.11.0 or later - - PHP: 3.9.0 or later - - Laravel: 3.0.0 or later - - Symfony: 4.4.0 or later - - Ruby: 5.5.0 or later - - Java: 6.5.0 or later - - .NET: 3.22.0 or later - - Go: 0.16.0 or later - -## [Configuration](https://docs.sentry.io/organization/dynamic-sampling/\#configuration) - -In this section, you'll learn how to use Dynamic Sampling in your organization. Dynamic Sampling offers two modes based on the desired sampling control: - -- **Default mode** allows you to set an organization level target sample rate and automatically adjusts project level sampling to match the organization level sample rate. -- **Advanced mode** gives you more granular control by allowing you to manually set the sampling rate at the project level. - -[![The dynamic sampling settings overview](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmode-and-target-sample-rate-KAGWNIMW.png%231625x785&w=3840&q=75)](https://docs.sentry.io/mdx-images/mode-and-target-sample-rate-KAGWNIMW.png) - -### [Default Mode](https://docs.sentry.io/organization/dynamic-sampling/\#default-mode) - -To use Dynamic Sampling in default mode, you have to specify a target sample rate for your entire organization, which determines how much incoming traffic should be stored across all your projects. Dynamic Sampling then distributes this sample rate across your projects automatically. Sample rates are adjusted continuously to account for changes in event volume over time. - -**The following adjustments are performed:** - -- Low-Volume Projects get a higher sample rate, ensuring important data isn’t missed. -- High-Volume Projects have reduced sample rates to balance overall storage. -- Sample rates are continuously adjusted based on recent traffic patterns, using a short sliding window to adapt to seasonal changes like holidays, weekends, and nighttime traffic. - -Dynamic Sampling also prioritizes the most valuable data within each project's allocated sample rate. You can learn more about this in the [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) section. This dynamic system ensures your sampling adapts to changing traffic and maintains balance across projects. - -### [Advanced Mode](https://docs.sentry.io/organization/dynamic-sampling/\#advanced-mode) - -If you want more fine-grained control, you can customize data retention by setting individual sample rates for specific projects by enabling the advanced mode. - -Here you can configure a fixed sample rate for each project in your organization. This value will specify the percentage of incoming traffic that should be stored for each respective project. The sample rate can be between 0% and 100%, defaulting to 100% if not adjusted. - -[![Advanced dynamic sampling settings](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fadvanced-DILP6TJT.png%231623x897&w=3840&q=75)](https://docs.sentry.io/mdx-images/advanced-DILP6TJT.png) - -When you edit the sample rates for individual projects, an estimated overall sample rate for your organization will also be calculated. This is a weighted average based on the volume of traffic for each project. Keep in mind that this value is an estimate and may change as the volume of traffic fluctuates. - -To adjust the sample rates of all your projects at once, edit the overall sample rate for your organization by going to the [Dynamic Sampling settings page](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/). This will proportionally update each project's sample rate to meet your chosen target. The maximum rate is 100%, and adjustments will be made to balance the rates across projects. You'll be able to review and finalize the updated sample rates before saving. Make sure to click the "Apply changes" button to save the new sample rates. - -[![Change all projects at once in Advanced Mode](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fadvanced-org-level-X3NSW7CF.png%231500x631&w=3840&q=75)](https://docs.sentry.io/mdx-images/advanced-org-level-X3NSW7CF.png) - -Whether advanced mode is activated or not, [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/#dynamic-sampling-priorities) will be applied within each project, boosting certain spans and deprioritizing others. - -When you deactivate advanced mode, the recalibration process will start immediately and the per-project sample rates will be reset to the calculated values. There's no way to restore the manually configured project sample rates once you've deactivated advanced mode. - -### [Project Preview](https://docs.sentry.io/organization/dynamic-sampling/\#project-preview) - -The [project preview](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/) table on the Dynamic Sampling settings page shows you how your projects might be affected by the sample rate you've chosen. The preview shows the dynamically allocated rates for your projects based on either the last 24 hours or the last 30 days of traffic. - -[![The Dynamic Sampling mode and target sample rate setting](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-sample-rate-preview-3CFQ3HW3.png%231884x1160&w=3840&q=75)](https://docs.sentry.io/mdx-images/project-sample-rate-preview-3CFQ3HW3.png) - -Because project rates continuously change, we recommend that you choose the 24-hour preview to get a more accurate view of your current sample rates for real-time analysis. We recommend the 30-day preview for seeing average sample rates in your billing cycle for long-term planning. - -## [Sample Rates for Distributed Traces](https://docs.sentry.io/organization/dynamic-sampling/\#sample-rates-for-distributed-traces) - -Because [distributed traces](https://docs.sentry.io/product/tracing/#whats-distributed-tracing) can originate in one project and have spans going across multiple other projects, it's important to note that Sentry **always applies the sample rate of the project where the trace originated** to every project that's part of that trace. - -For example, if a trace starts in your frontend application, the sample rate you've set there will apply to a connected backend application that's part of the same trace. The same rule applies if the trace starts in a backend application. - -If you navigate to the [project preview](https://sentry.io/orgredirect/organizations/:orgslug/settings/dynamic-sampling/) table, you'll see the number of sent spans next to the origin project where the trace started. This includes any spans from propogated traces in other projects that are connected to the origin project. This gives you a direct view of how many spans will be affected by the sample rates you configure. To see the span counts broken down by the project they belong to, click the expand icon to the left of each project in the preview. - -[![Diagram showing the effect of dynamic sampling on distriubuted traces](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fclient-to-backend-accumulated-sampling-effect-55JKSEJV.png%232832x1790&w=3840&q=75)](https://docs.sentry.io/mdx-images/client-to-backend-accumulated-sampling-effect-55JKSEJV.png) - -## [SDK versus Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling/\#sdk-versus-dynamic-sampling) - -SDK sampling happens at the application level, before events are sent to Sentry. It filters events by sending only a set percentage, reducing data volume and instrumentation overhead. This helps with managing high event volumes directly at the source. - -Dynamic sampling, on the other hand, happens at the server level after events are sent to Sentry. Sample rates are adjusted dynamically based on the volume of events received by Sentry, without requiring any changes to the application. - -SDK sample rates can usually only be changed when a new version of the application is deployed, unless a custom mechanism has been implemented making it possible to change the sample rate dynamically. But with Dynamic Sampling, it's possible to configure the sampling rate for each project in your organization dynamically, without requiring any changes to the application. - -Additionally, advanced mode is not active, Dynamic Sampling continuously monitors the traffic for each project and adjusts the sample rate of each to prioritize the most relevant data. - -### [When to Use Dynamic Versus SDK Sampling](https://docs.sentry.io/organization/dynamic-sampling/\#when-to-use-dynamic-versus-sdk-sampling) - -The biggest benefit of Dynamic Sampling is its flexibility. It adjusts the sample rate based on the volume of events received by Sentry. This makes it a great choice for organizations with both high and low-volume projects, as it helps maximize your quota by tailoring the sample rate to each project's event volume. - -Dynamic Sampling can prioritize spans based on their content, offering more insight than SDKs. For example, it can focus on spans from the latest release or low-volume projects, giving you better visibility into the most important parts of your application. - -SDK sampling uses a static rate set in the SDK configuration. It’s ideal for organizations with consistent event volumes that want to limit the percentage of events sent to Sentry. This helps reduce spans to lower overhead, save bandwidth (especially for mobile apps), or decrease the number of accepted spans. - -### [Deciding on Your SDK Sample Rate](https://docs.sentry.io/organization/dynamic-sampling/\#deciding-on-your-sdk-sample-rate) - -To give Sentry the fullest, most accurate picture of your application’s health, we recommend sending us 100% of your events. You can do this by setting your [tracesSampleRate](https://docs.sentry.io/platform-redirect/?next=/performance/) to 1.0. If this isn't feasible for your organization, set a lower value, or switch to sampling selectively by using the [tracesSampler](https://docs.sentry.io/platform-redirect/?next=/performance/) to filter your events based on contextual data. Note, that when calculating throughput, metering is based on received, not stored events. - -Changes to your SDK sampling configuration may affect your quota. If you increase your SDK sampling rate, you'll also be increasing the volume of events you send to Sentry. This may require that you adjust your quota. - -You can use both Dynamic and SDK Sampling together to further optimize your event volume for your specific use case. For example, you can set a low SDK sample rate to ensure that only a certain percentage of events are sent to Sentry, and then use Dynamic Sampling to adjust the sample rate based on the event volume received by Sentry. - -## [Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#dynamic-sampling-priorities) - -Below is a list of the strategies Dynamic Sampling employs to prioritize and deprioritize data. They are enabled by default, but can be updated on a per-project basis to better fit your organization's needs. To customize this behavior, go to Project Settings > Performance. - -### [How to Change Dynamic Sampling Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#how-to-change-dynamic-sampling-priorities) - -To make changes to a project's dynamic sampling priorities in Sentry, go to **Settings > Projects**, select the project you're interested in, then scroll down to "Performance" in the "PROCESSING" section and make any updates under "DYNAMIC SAMPLING PRIORITIES" using the toggles. Each of your projects can have an individual set of dynamic sampling priorities. - -General Settings — totes-ma-gotes — Sentry - -General Settings — totes-ma-gotes — Sentry - -![Choose the project you'd like to update retention priorities for.](<Base64-Image-Removed>)![Scroll down to Performance](<Base64-Image-Removed>)![Select Settings, then Projects](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/80f05eeb-d09d-4814-a0d3-3af39c4e1ba0.png) - -Select Settings, then Projects - -![](<Base64-Image-Removed>) - -reCAPTCHA - -Recaptcha requires verification. - -[Privacy](https://www.google.com/intl/en/policies/privacy/) \- [Terms](https://www.google.com/intl/en/policies/terms/) - -protected by **reCAPTCHA** - -[Privacy](https://www.google.com/intl/en/policies/privacy/) \- [Terms](https://www.google.com/intl/en/policies/terms/) - -### [Automatic Priorities](https://docs.sentry.io/organization/dynamic-sampling/\#automatic-priorities) - -Sentry automatically prioritizes or deprioritizes based on the following rules: - -#### [Latest Release](https://docs.sentry.io/organization/dynamic-sampling/\#latest-release) - -Latest releases are a dynamic sampling priority because when you create a new release, we assume you'll want to have more visibility during the early adoption phase, which improves your ability to catch new issues as your release is gaining traction. Because you may want to deploy the same release in different environments, we'll also take your environment into account and prioritize those traces. - -#### [Dev Environments](https://docs.sentry.io/organization/dynamic-sampling/\#dev-environments) - -Since dev environments usually generate a small number of events as compared to prod environments, we prioritize them during your testing phase so you can get meaningful insights. We consider an environment to be a dev environment if its name matches one of the following glob patterns: - -- `*debug*` -- `*dev*` -- `*local*` -- `*qa*` -- `*test*` - -#### [Low Volume Projects](https://docs.sentry.io/organization/dynamic-sampling/\#low-volume-projects) - -You won't be able to disable the Low Volume Projects dynamic sampling priority because it's set on an organization-wide level, not on a per-project basis. - -Some projects within your organization are very high-volume compared to others. This means that low-volume projects might get drowned out if we treat all projects equally. To ensure that you have enough samples regardless of project scale, we prioritize low-volume projects. - -#### [Low Volume Transactions](https://docs.sentry.io/organization/dynamic-sampling/\#low-volume-transactions) - -Spans can be logically grouped by their transaction name within a project. This means that spans with the same transaction name most likely indicate the same operation or code path, while spans with different transaction names usually indicate different operations. We prioritize low-volume transactions for the same reason we prioritize low-volume projects: so they don't get drowned out by high-volume transactions. We want to make sure that low-volume code paths are sampled in enough quantities to generate a complete view of your application. - -#### [Health Checks](https://docs.sentry.io/organization/dynamic-sampling/\#health-checks) - -We deprioritize health check type transactions because while they're important for checking the stability of your application, they don't have any value beyond the task associated with them. We consider a transaction to be a health check if its name matches one of the following glob patterns: - -- `*healthcheck*` -- `*heartbeat*` -- `*/health` -- `*/healthy` -- `*/healthz` -- `*/live` -- `*/livez` -- `*/ready` -- `*/readyz` -- `*/ping` - -### [Get Samples](https://docs.sentry.io/organization/dynamic-sampling/\#get-samples) - -Our automated dynamic sampling priorities work well in a generic manner to collect a baseline of samples because they prioritize retaining data that's valuable for any customer at any given time. However, there are certain scenarios, such as investigating a particular issue, when very specific data becomes temporarily more important. In such cases, the automated sampling priorities may not provide enough samples, so you may want to create investigation rules. - -Investigation rules are sampling rules that can be created through the Sentry UI to temporarily boost the number of events collected for a particular scenario (for example, events with specific tag values). These rules can be created to retain more samples when too few (less than 5) are available. Once created, a rule will be active for up to 48 hours or until 100 samples are collected. You'll be notified via email when enough events have been collected. - -Investigation sampling rules only apply to transactions and don't guarantee that full traces will be sampled. The maximum number of sampling rules that can exist at the same time is 50. - -#### [Creating a New Rule](https://docs.sentry.io/organization/dynamic-sampling/\#creating-a-new-rule) - -When you query transactions either in [Discover](https://docs.sentry.io/product/explore/discover-queries/) or in [Transaction Summary](https://docs.sentry.io/product/performance/transaction-summary/) and receive fewer than 5 samples, you can click "Get Samples" to create a new investigation rule and retain more samples of transactions for the respective query. - -[![Investigation Mode in Discover](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-discover-SEDWQ64B.png%232176x1562&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-discover-SEDWQ64B.png) - -This feature only applies to transactions. Therefore, in Discover, you have to specify `event.type:transaction` in the query to access the feature, whereas in Performance the event type is implicit. - -Clicking this button creates an investigation rule for the query. Once the rule is successfully created, a notification appears, and the button is replaced with a message showing the investigation is in progress and the amount of time it's been active. - -[![Rule successfully created](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-rule-created-Y4JFENSI.png%231970x644&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-rule-created-Y4JFENSI.png) - -If a user performs the same search later and the investigation is still active, the notification will indicate that there's an active rule already collecting data for the query. - -It's also possible to create a rule from the Transaction Summary page in Performance. - -[![Investigation Mode in Transaction Summary](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Finvestigation-bias-tx-summary-CQIO4I7G.png%231834x1532&w=3840&q=75)](https://docs.sentry.io/mdx-images/investigation-bias-tx-summary-CQIO4I7G.png) - -[Previous\\ -\\ -Data Storage Location (US or EU)](https://docs.sentry.io/organization/data-storage-location) - -[Next\\ -\\ -Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/dynamic-sampling/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) - -# Search - -## Learn more about how to search in Sentry, including the correct query syntax, searchable properties, and custom tags. - -Search is available on several features throughout [sentry.io](https://sentry.io/), such as **Issues**, **Discover** and **Dashboards**. - -## [Query Syntax](https://docs.sentry.io/concepts/search/\#query-syntax) - -You'll only need to use query syntax if you're using a Sentry [API](https://docs.sentry.io/api/). You'll get pre-populated suggestions once you start typing in your search terms when using the search bar anywhere in [Sentry.io](https://sentry.sentry.io/). - -Search queries are constructed using a `key:value` pattern, with an optional raw search at the end. Each `key:value` pair is a `token` and the optional raw search is itself a single `token`. The `key:value` pair `tokens` are treated as issue or event properties. The optional raw search is treated as a single `token` and searches event titles/messages. - -For example: - -Bash - -`` - -```bash code-highlight -is:resolved user.username:"Jane Doe" server:web-8 example error - -``` - -In the example above, there are three keys ( `is:`, `user.username:`, `server:`), but four tokens: - -- `is:resolved` -- `user.username:"Jane Doe"` -- `server:web-8` -- `example error` - -The tokens `is:resolved` and `user.username:"Jane Doe"` are standard search tokens because both use reserved keywords. See [Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/#issue-properties) and [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/#event-properties) for appropriate keyword usage. The token `server:web-8` is pointing to a custom tag sent by the Sentry SDK. See [Custom Tags](https://docs.sentry.io/concepts/search/searchable-properties/#custom-tags) for more information on how to set tags. - -The token `example error` is utilizing the optional raw search and is passed as part of the issue search query (which uses a CONTAINS match similar to SQL). When using the optional raw search, you can provide _one_ string, and the query uses that entire string. - -Search terms should auto-complete, and when they don't, that means your term is incompatible with the dataset. If you complete the term and tap the Return/Enter key, an error message is displayed. - -### [Comparison Operators](https://docs.sentry.io/concepts/search/\#comparison-operators) - -Sentry search supports the use of comparison operators: - -- greater than ( **`>`**) -- less than ( **`<`**) -- greater than or equal to ( **`>=`**) -- less than or equal to ( **`<=`**) - -Typically, when you search using properties that are numbers or durations, you should use comparison operators rather than just a colon ( `:`) to find exact matches, since an exact match isn't likely to exist. - -Here are some examples of valid comparison operator searches: - -- `event.timestamp:>2023-09-28T00:00:00-07:00` -- `count_dead_clicks:<=10` -- `transaction.duration:>5s` - -### [Using `OR` and `AND`](https://docs.sentry.io/concepts/search/\#using-or-and-and) - -`OR` and `AND` search conditions are only available for [Discover](https://docs.sentry.io/product/explore/discover-queries/), [Insights Overview](https://docs.sentry.io/product/insights/overview/), and [Metric Alerts](https://docs.sentry.io/product/alerts-notifications/metric-alerts/). - -Use `OR` and `AND` between tokens, and use parentheses `()` to group conditions. `AND` can also be used between non-aggregates and aggregates. However, `OR` cannot. - -- Non-aggregates filter data based on specific tags or attributes. For example, `user.username:jane` is a non-aggregate field. - -- Aggregates filter data on numerical scales. For example, `count()` is an aggregate function and `count():>100` is an aggregate filter. - - -Some examples of using the `OR` condition: - -Bash - -`` - -```bash code-highlight -# a valid `OR` query -browser:Chrome OR browser:Opera - -# an invalid `OR` query -user.username:janedoe OR count():>100 - -``` - -Also, the queries prioritize `AND` before `OR`. For example, "x `AND` y `OR` z" is the same as "(x `AND` y) `OR` z". Parentheses can be used to change the grouping. For example, "x `AND` (y `OR` z)". - -### [Multiple Values on the Same Key](https://docs.sentry.io/concepts/search/\#multiple-values-on-the-same-key) - -You can search multiple values for the same key by putting the values in a list. For example, "x:\[value1, value2\]" will find the the same results as "x:value1 `OR` x:value2". When you do this, the search returns issues/events that match any search term. - -An example of searching on the same key with a list of values: - -Bash - -`` - -```bash code-highlight -release:[12.0, 13.0] - -``` - -Currently, you can't use this type of search on the keyword `is` and you can't use wildcards with this type of search. - -### [Explicit Tag Syntax](https://docs.sentry.io/concepts/search/\#explicit-tag-syntax) - -We recommend you never use reserved keywords (such as `project_id`) as tags. But if you do, you must use the following syntax to search for it: - -Bash - -`` - -```bash code-highlight -tags[project_id]:tag_value - -``` - -### [Advanced](https://docs.sentry.io/concepts/search/\#advanced) - -Sentry also offers the following advanced search options: - -#### [Exclusion](https://docs.sentry.io/concepts/search/\#exclusion) - -By default, search terms use the `AND` operator; that is, they return the intersection of issues/events that match all search terms. - -To change this, you can use the negation operator `!` to _exclude_ a search parameter. - -Bash - -`` - -```bash code-highlight -is:unresolved !user.email:example@customer.com - -``` - -In the example above, the search query returns all Issues that are unresolved _and_ have not affected the user with the email address `example@customer.com`. - -#### [Wildcards](https://docs.sentry.io/concepts/search/\#wildcards) - -Search supports the wildcard operator `*` as a placeholder for specific characters and strings. - -Bash - -`` - -```bash code-highlight -browser:"Safari 11*" - -``` - -In the example above, the search query will match on `browser` values like `"Safari 11.0.2"`, `"Safari 11.0.3"`, etc. - -You may also combine operators like so: - -Bash - -`` - -```bash code-highlight -!message:"*Timeout" - -``` - -In the above example, the search query returns results which do not have message values like `ConnectionTimeout`, `ReadTimeout`, etc. - -## [Page Filters](https://docs.sentry.io/concepts/search/\#page-filters) - -Page filters allow you to narrow down the results shown on a page by selecting specific projects, environments, and date ranges. After you've set your filters, they'll persist as you navigate across pages in Sentry. - -[![Project selector](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-selector-G2TQ3YHO.png%23407x576&w=828&q=75)](https://docs.sentry.io/mdx-images/project-selector-G2TQ3YHO.png) - -If you want to see data for all your projects, click "Clear" in the project selector to clear any project filters. - -## [Learn more](https://docs.sentry.io/concepts/search/\#learn-more) - -[Previous\\ -\\ -Concepts](https://docs.sentry.io/concepts/key-terms) - -[Next\\ -\\ -Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Linking Variables](https://docs.sentry.io/contributing/linking/) - -# Linking Variables - -We create a variety of links in our documentation, but the most commonly-used link type connects content either between product guides and the platform pages or between platform pages themselves. Each of these may take a different format, depending on whether a platform needs to be specified. - -## [Product & Platform Links](https://docs.sentry.io/contributing/linking/\#product--platform-links) - -### [From Product to Platform](https://docs.sentry.io/contributing/linking/\#from-product-to-platform) - -We use this format when linking from the product guides to the platform content because it allows the user to specify their platform, if it is not already specified. For example: - -`Releases also offer significant additional features when you fully [configure your SDK](/platform-redirect/?next=/configuration/releases/).` - -In the above example, when the user clicks the link to the releases configuration content, but hasn't yet visited a platform page, they will be asked to specify their platform so the page can be populated with the correct code sample when viewed. If they have navigated into product from the platform content, and are now navigating back into their platform, the platform context is maintained. - -### [Within Platforms](https://docs.sentry.io/contributing/linking/\#within-platforms) - -We use this format when linking among or within the platform content: - -`You can set your own <PlatformLink to="/enriching-events/breadcrumbs/">breadcrumbs</PlatformLink> to make them more useful for debugging.` - -In the above example, when the user clicks the link to the breadcrumbs content, they will be navigated to the breadcrumbs content **within their specific platform**. If this link is used in product guides, and no platform is specified, the user will be navigated to the first platform listed, which is currently the Apple family of SDKs. - -### [Hardcoding the Platform](https://docs.sentry.io/contributing/linking/\#hardcoding-the-platform) - -We use this format when there's only one option for the platform, the content is not common to multiple platforms, or we want to force the reader to use this source of truth: - -`[NDK integration](/platforms/android/configuration/using-ndk/) is packed with the SDK and requires API level 16, though other levels are supported.` - -In the above example, there is only one place for users to learn about using Android's NDK, which is nested within the Android directory, so we can hardcode the path. - -### [To Product Pages](https://docs.sentry.io/contributing/linking/\#to-product-pages) - -We use this format when linking with our product content. Product guides do not currently need a platform to be specified. As a result, linking can define the path to the correct content in the `product` folder. For example: - -`You can also customize how events are grouped. Learn more about customized grouping in [Issue Grouping](/concepts/data-management/event-grouping/).` - -### [To External Pages](https://docs.sentry.io/contributing/linking/\#to-external-pages) - -We use this format when linking to external pages. Most typically, this is to the UI: - -`The **Performance** page is the main view in [sentry.io](https://sentry.io) where you can search or browse for transaction data.` - -### [To Sandbox](https://docs.sentry.io/contributing/linking/\#to-sandbox) - -Sandbox allows the user to explore the feature in an actual Sentry application with mocked data. - -`Learn more about this feature in our <SandboxLink scenario="releases">sandbox</SandboxLink>.` - -This will take the user to a project based on the current platform selection. However, you can also manually specify the target project using the `projectSlug` parameter. - -The `scenario` parameter specifies the landing page within the Sandbox application that the user will see, and if it is not specified, we default to the `issues` page. Possible values are: - -- `performance` -- `releases` -- `alerts` -- `discover` -- `dashboards` -- `projects` -- `oneDiscoverQuery` -- `oneIssue` -- `oneBreadcrumb` -- `oneStackTrace` -- `oneTransaction` -- `oneWebVitals` -- `oneTransactionSummary` -- `oneRelease` - -Additionally, you can use the `errorType` parameter to select a particular type of error. - -`Learn more about breadcrumbs in our <SandboxLink scenario="oneBreadcrumb" errorType="EXC_BAD_ACCESS" projectSlug="ios">sandbox</SandboxLink>.` - -## [Anchor Links](https://docs.sentry.io/contributing/linking/\#anchor-links) - -Anchor links (appended by the # symbol) further direct users to a specific section (rather than the general page). - -### [Within the Same Page](https://docs.sentry.io/contributing/linking/\#within-the-same-page) - -We use this format to link users to content that's further down the page (typically beyond the initial fold): - -`On this page, you can control the frequency of your [email notifications](#notifications), [change your primary email](#emails), and update your security settings.` - -### [On Another Page](https://docs.sentry.io/contributing/linking/\#on-another-page) - -We use this format to direct users to a specific heading on another page: - -`To add to your quota or review what happens when you exceed it, see [Increasing Quotas](/pricing/quotas/#increasing-quotas).` - -This type of link can be used also for linking to anchors on external pages: - -`Sessions last for [Django's default session length](https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-cookie-based-sessions), which is two weeks.` - -## [Images](https://docs.sentry.io/contributing/linking/\#images) - -All images live in the `/public/` folder. You can reference images in this folder by using its full path (minus `/public/`). - -For instance, to use the image, `/public/product/alerts/issue-alert.png`, in any file: - -`![Image alt text](product/alerts/issue-alert.png)` - -The folder structure of `docs` is duplicated in `public` so that you can still use relative paths to reference images in your content files. For more details, see [Images](https://docs.sentry.io/contributing/pages/images/). - -## [Email address](https://docs.sentry.io/contributing/linking/\#email-address) - -We use this format when we want to link an email address (often used for Early Adopter or Beta features): - -`For more information about access to Metric Alerts, feel free to reach out at [alerting-feedback@sentry.io](mailto:alerting-feedback@sentry.io).` - -[Previous\\ -\\ -Platforms & Guides](https://docs.sentry.io/contributing/platforms) - -[Next\\ -\\ -Pages](https://docs.sentry.io/contributing/pages) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/linking.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) -- [Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso/) - -# Okta SSO - -## Set up Okta single sign-on (SSO) on Sentry. - -## [Installation](https://docs.sentry.io/organization/authentication/sso/okta-sso/\#installation) - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. - -1. Sign in to your Okta organization with your administrator account. - -2. From the admin console's sidebar, click **Applications > Applications**, then click on "Browse App Catalog" (or "Add Application" for the old interface). - -3. Search for `Sentry`, then click "Add Integration" to be brought to the setup wizard. - -[![Sentry in Okta Gallery of Integrations](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-gallery-N6S553CH.png%232560x1000&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-gallery-N6S553CH.png) - -4. Provide the settings. Note that for "1. General Settings", you will not need to provide any special settings. For "2. Sign On Options", provide the following: - - - - Base URL: `https://sentry.io` Ensure that the Base URL does not have a trailing slash or whitespace at the end as they will break the redirect from Okta to Sentry. - - - Organization Slug: _YOUR\_ORG\_SLUG_ - - - You can find your organization slug in the URL: `https://sentry.io/organizations/YOUR_ORG_SLUG/` - - Email: `Email` - - -[![Configuring Sentry in Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-settings-for-sentry-4MRBQPLO.png%231332x2112&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-settings-for-sentry-4MRBQPLO.png) - -5. Click "Save" to create the Sentry app. - -6. When you're redirected to the app settings page, click "Sign On". - -7. Copy the "Metadata URL" in the set up instructions. - -[![Okta metadata URL in setup instructions](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-setup-instructions-page-3S3DZNQU.png%231890x672&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-setup-instructions-page-3S3DZNQU.png) - -8. Sign in to Sentry. Select **Settings > Auth > Configure Okta**. - -[![Sentry single sign-on configuration page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-sso-settings-page-NHI7KU7L.png%231024x663&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-sso-settings-page-NHI7KU7L.png) - -9. Paste the Metadata URL from Step 8, then click "Continue". - -[![Sentry single sign-on configuration for Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-settings-metadata-url-DNXJPERF.png%231024x292&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-settings-metadata-url-DNXJPERF.png) - - -Sentry will attempt to authenticate and link your account with Okta. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can: - -- Share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. - -- Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Okta. - -- Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. - - -If you make any changes, click "Save Settings" to complete your set up. - -[![Sentry single sign-on settings for Okta](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-sentry-settings-for-okta-GIZIAQZJ.png%231024x980&w=2048&q=75)](https://docs.sentry.io/mdx-images/okta-sentry-settings-for-okta-GIZIAQZJ.png) - -## [SCIM Integration](https://docs.sentry.io/organization/authentication/sso/okta-sso/\#scim-integration) - -- See [Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim). - -[Previous\\ -\\ -Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso) - -[Next\\ -\\ -Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/okta-sso/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) - -# Compliance - -## Learn more about Sentry's compliance integrations. - -- [Truto](https://docs.sentry.io/organization/integrations/compliance/truto/) -- [Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta/) - -[Previous\\ -\\ -Feature Flags](https://docs.sentry.io/organization/integrations/feature-flag) - -[Next\\ -\\ -Truto](https://docs.sentry.io/organization/integrations/compliance/truto) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) - -# Platforms & Guides - -Platform content lives in `docs/platforms` and follows some specific rules to generate content. The content is rendered using the same features as all other [pages](https://docs.sentry.io/contributing/), but has some additional functionality exposed to clone content and encapsulate platforms as portals. - -Directory structure has meaning within the platforms directory, and looks something akin to: - -Bash - -`` - -```bash code-highlight -[platformName]/ - child.mdx - childTwo/ - index.mdx - common/ - aSharedPage.mdx - guides/ - [guideName]/ - uniqueChild.mdx - childTwo/ - index.mdx - -``` - -Platforms will generate a list of "guides" that inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs: - -Bash - -`` - -```bash code-highlight -/platforms/platformName/ -/platforms/platformName/config.yml -/platforms/platformName/child/ -/platforms/platformName/childTwo/ -/platforms/platformName/aSharedPage/ -/platforms/platformName/guides/guideName/ -/platforms/platformName/guides/guideName/config.yml -/platforms/platformName/guides/guideName/child/ -/platforms/platformName/guides/guideName/uniqueChild/ -/platforms/platformName/guides/guideName/childTwo/ -/platforms/platformName/guides/guideName/aSharedPage/ - -``` - -This is generated by inheriting all content with the `common/` directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see `aSharedPage` is loaded at two different URLs, and `childTwo` is overwritten by `guideName`. - -The sidebar on platform pages (handled by `<PlatformSidebar>`) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation. - -## [Configuration](https://docs.sentry.io/contributing/platforms/\#configuration) - -Configuration is read (in order) from `[namespace]/index.mdx` and `[namespace]/config.yml`. This means that a platform's index can be fully rendered via a common page. - -Valid configuration attributes are: - -`title` - -The display name for a platform. - -`supportLevel` - -The level of support. `production` (default) or `community` - -`caseStyle` - -The casing style for code samples. `canonical` (default), `camelCase`, `snake_case`, or `PascalCase` - -`categories` - -A list of categories for future support. Known values are `browser`, `mobile`, `desktop`, and `server`. - -`fallbackPlatform` - -The key to use for defaults. Can use full key syntax of `platformName` or `platformName.guideName`. - -`sdk` - -The name of the SDK, if available. Used to embed SDK information on pages. - -`aliases` - -A list of aliases for this platform. For example, "Cocoa" might apply to Apple, or "C#" might apply to .NET. - -`showIntegrationsInSearch` - -Whether to show integrations in the search results on the home page. - -**Note:** This is only applicable to platforms that have no guides like Python. - -## [Shared Content](https://docs.sentry.io/contributing/platforms/\#shared-content) - -Shared (duplicated) content within an SDK (platform) is available in the `src/platforms/[platformName]/common/` folder. - -All of this content will be automatically duplicated within every guide. This leverages components like `PlatformContent` which can automatically substitute content out. - -### [Page Visibility](https://docs.sentry.io/contributing/platforms/\#page-visibility) - -Sometimes a page may not make sense within the context of a given guide. To control this, you can use the `supported` and `notSupported` frontmatter on common pages in platforms. - -Page visibility works similar to the supported/notSupported attributes in other platform components (such as `PlatformSection`). - -For example, if you wanted to make hide the content for a platform by default, but enable it for a guide, you can do that like so: - -Markdown - -`` - -```code-highlight markdown ---- -supported: - - native.wasm -notSupported: - - native ---- - -``` - -If the page you're conditionally hiding has subpages, you'll need to add the `supported`/ `notSupported` annotations to the subpages as well. - -## [Platform-Specific Components](https://docs.sentry.io/contributing/platforms/\#platform-specific-components) - -There are a number of components that aid the development of platform specific pages, as well as behave differently when a platform is active. For more information, see [components](https://docs.sentry.io/contributing/pages/components/). - -## [Delineation](https://docs.sentry.io/contributing/platforms/\#delineation) - -We differentiate platforms by language and developer interaction. A top-level SDK is considered a platform. A platform may have guides for frameworks that it supports, and these guides often inherit much of their content from their parent platform. - -In general, use this decision tree: - -- Is it a new programming language? -> new platform -- Does it require a separate SDK or way of sending data to Sentry? -> new platform -- Does it count as a "platform" -> new platform -- Otherwise -> add it as a Guide to an existing platform - -### [Example](https://docs.sentry.io/contributing/platforms/\#example) - -JavaScript is a top-level SDK because the frameworks that it supports share much of the same content. - -On the other hand, Android and Java have very little overlap. As a result, they are both top level platforms. - -[Previous\\ -\\ -Our Approach](https://docs.sentry.io/contributing/approach) - -[Next\\ -\\ -Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering/) - -# Inbound Filters - -## Learn about the different methods for filtering data in your project. - -Sentry provides several methods to filter data in your project. Using sentry.io to filter events is a simple method since you don't have to [configure and deploy your SDK to filter projects](https://docs.sentry.io/platform-redirect/?next=/configuration/filtering/). - -## [Inbound Data Filters](https://docs.sentry.io/concepts/data-management/filtering/\#inbound-data-filters) - -Inbound data filters allow you to determine which errors, if any, Sentry should ignore. Explore these by navigating to **\[Project\] > Project Settings > Inbound Filters.** - -These filters are exclusively applied at ingest time and not later in processing. This, for instance, lets you discard an error by error message when the error is ingested through the JSON API. On the other hand, this filter doesn't apply to ingested minidumps. Filtered events do not consume quota, as discussed in [What Counts Toward My Quota](https://docs.sentry.io/pricing/quotas/#what-counts-toward-my-quota-an-overview). - -Inbound filters include: - -- Common browser extension errors -- Transactions coming from health checks and ping requests -- Events coming from legacy browsers -- Events coming from localhost -- Errors from known web crawlers -- React hydration errors -- ChunkLoadErrors -- Events from certain IP addresses -- Events with certain error messages -- Events from specific release versions of your code - -### [Legacy Browser Filters](https://docs.sentry.io/concepts/data-management/filtering/\#legacy-browser-filters) - -The legacy browser filters allow you to filter out certain legacy versions of browsers that are known to cause problems. - -Legacy browser filters were updated in Feb 2024 and will be periodically evaluated to include additional legacy versions. - -If you had a legacy browser filter on before the update, the old filter will appear in your settings as "Deprecated". Deprecated legacy browser filters still work. However, if you turn them off, you won’t be able to turn them on again and will need to use the new filters instead. - -### [Browser Extension Errors](https://docs.sentry.io/concepts/data-management/filtering/\#browser-extension-errors) - -Some browser extensions are known to cause errors. You can filter these out using the browser extension filter, which checks the error message and event source to see if it's a known error coming from a browser extension. To see the full list of errors filtered out by the browser extension filter, see the [source code in relay](https://github.com/getsentry/relay/blob/master/relay-filter/src/browser_extensions.rs#L9-L76). - -### [Web Crawler Errors](https://docs.sentry.io/concepts/data-management/filtering/\#web-crawler-errors) - -Due to their nature, web crawlers often encounter errors that normal users won't see. You can use the web crawler filter to filter out errors from web crawlers, determined by the event's user-agent, from the following sites: Baidu, Yahoo, Sogou, Facebook, Alexa, Slack, Google Indexing, Pingdom, Lytics, AWS Security Scanner, Hubspot, Bytedance, and other generic bots and spiders. Errors from Slack's Slackbot web crawler will not be filtered. - -### [IP Addresses](https://docs.sentry.io/concepts/data-management/filtering/\#ip-addresses) - -Filters events based on the **originating IP address of the client making the request**, not the user IP contained within the user data inside the request. This ensures that filtering decisions rely on the actual source of the request, as determined by network-level information, rather than data provided in the event payload. - -Sentry attempts to identify the request’s origin using the **forwarded IP address**. If no forwarded IP is available, it falls back to the **direct IP** of the client connecting to Sentry’s servers. - -The supported IP address formats are: - -- **IPv4 Addresses**: Standard dotted-decimal notation (e.g., 1.2.3.4, 122.33.230.14, 127.0.0.1). -- **IPv6 Addresses**: Standard colon-separated hexadecimal notation (e.g., aaaa:bbbb::cccc, a:b:c::1). -- **IPv4 Network Ranges (CIDR Notation)**: IPv4 address with a subnet mask (e.g., 122.33.230.0/30, 127.0.0.0/8). -- **IPv6 Network Ranges (CIDR Notation)**: IPv6 address with a subnet mask (e.g., a:b:c::0/126). - -### [Transactions Coming from Health Check](https://docs.sentry.io/concepts/data-management/filtering/\#transactions-coming-from-health-check) - -In essence, the health check filter serves the purpose of excluding transactions that are generated as a part of health check procedures. - -By applying this filter, you effectively bypass transactions that, while crucial for app stability assessment, hold limited value for you beyond their designated function. - -We consider a transaction to be a health check if its name matches one of the following glob patterns: - -- `*healthcheck*` -- `*heartbeat*` -- `*/health` -- `*/healthy` -- `*/healthz` -- `*/_health` -- `*/[_health]` -- `*/live` -- `*/livez` -- `*/ready` -- `*/readyz` -- `*/ping` -- `*/up` - -* * * - -##### Note - -Filters do not apply to [sessions](https://docs.sentry.io/product/releases/health/#session). Error messages from minidumps also do not yet apply. - -Once applied, you can track the filtered events (numbers and cause) using the graph provided at the top of the Inbound Data Filters view. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fbuiltin-inbound-filters-7W2K2Z5Q.png%231928x648&w=3840&q=75)](https://docs.sentry.io/mdx-images/builtin-inbound-filters-7W2K2Z5Q.png) - -## [How Custom Filtering Works](https://docs.sentry.io/concepts/data-management/filtering/\#how-custom-filtering-works) - -This feature is available only if your organization is on [a Trial, Business, or Enterprise plan](https://sentry.io/pricing/). - -Inbound data filters are not case-sensitive. - -### [Error Message](https://docs.sentry.io/concepts/data-management/filtering/\#error-message) - -To use inbound data filters for error messages, keep the following in mind: - -- You can provide multiple patterns, one per line. The filter applies if any of the patterns match. -- On error events, the filter matches the entire error description in the format `{exception.type}: {exception.value}`. We do not recommend matching the full error description including the colon, and suggest you match with wildcards. For example, to match any "ConnectionError", use the filter `*ConnectionError*`. The wildcard matcher can be used at the beginning or end of the string. -- On message events, the filter matches the fully formatted message. -- Transactions are never matched by this filter. - -To ensure you’re adding the correct message to the inbound filter setting, check the JSON for an event in the issue. The filter by error message setting matches the data found in the "title" field near the end of the file. - -### [Releases](https://docs.sentry.io/concepts/data-management/filtering/\#releases) - -To filter releases, keep the following in mind: - -- The filter matches the full release name provided during SDK initialization. If you provide the recommended package prefix, the release is in the format `package@version`, for example: `my-example@1.4.0-beta.1`. -- Globbing rules apply and there is no special casing for SemVer. This allows for matching prefixes, such as `my-example@1.*`. -- The filter never applies to events without a release. - -### [Glob Matching](https://docs.sentry.io/concepts/data-management/filtering/\#glob-matching) - -The error messages and releases filters use glob patterns. Globs are case insensitive and allow you to specify wildcards to match variable input. For example, `*panic*` matches any error that contains the words "panic", "PANIC" or "PaNiC". - -Some symbols, such as the `*` character, receive special meaning as meta characters. To match a literal asterisk, escape it with a backslash: `\*`. Inbound data filters use the following meta characters: - -- `?` matches any single character. -- `*` matches zero or more characters. -- `\` escapes the next character making it literal. If it precedes a non-meta character, the backslash is ignored. -- `[`, `]`, `{`, and `}` are reserved meta characters. -- `!` works for negation, but only within brackets, such as in `[!1-4]` to match any character that is not `[1-4]`. - -Generally, `bash`'s out-of-the-box behavior for globbing is close to what Sentry supports: - -Bash - -`` - -```bash code-highlight -touch 1.2.3 -touch 1.2.4 -echo 1.2.* -echo 1.2.[!3] - -``` - -[Previous\\ -\\ -Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding) - -[Next\\ -\\ -Size Limits](https://docs.sentry.io/concepts/data-management/size-limits) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/filtering/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Development Environment](https://docs.sentry.io/contributing/environment/) - -# Development Environment - -This setup assumes you have [Yarn](https://yarnpkg.com/), [Volta](https://volta.sh/) and [pre-commit](https://pre-commit.com/) installed. - -If you prefer not to use Volta, make sure you're using Node 20. - -First, open a terminal and clone the `sentry-docs` repo: - -Bash - -`` - -```bash code-highlight -# Clone the docs repo -git clone git@github.com:getsentry/sentry-docs.git - -``` - -Next, navigate into the cloned repo and run the following to install dependencies: - -Bash - -`` - -```bash code-highlight -# Install or update application dependencies -make - -``` - -Now, run the development webserver (depending on the docs you want to run): - -Bash - -`` - -```bash code-highlight -# Start dev server for user docs -yarn dev - -# Start dev server for developer docs -yarn dev:developer-docs - -``` - -You will now be able to access docs via [http://localhost:3000](http://localhost:3000/). - -## [Linting](https://docs.sentry.io/contributing/environment/\#linting) - -A few linters are available. Run `yarn lint` to apply them all. - -Some lints can be autofixed with eslint - -Bash - -`` - -```bash code-highlight -yarn lint:eslint:fix - -``` - -Additionally we use prettier to format our code and markdown. Run prettier if you get linting errors in CI: - -Bash - -`` - -```bash code-highlight -yarn lint:prettier:fix - -``` - -[Previous\\ -\\ -Contributing to Docs](https://docs.sentry.io/contributing) - -[Next\\ -\\ -Our Approach](https://docs.sentry.io/contributing/approach) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/environment.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) -- [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) - -# Trace View - -## Learn more about the Trace View page, where you can drill down into the details of a single trace, allowing you to debug slow services, identify related errors, and find other bottlenecks. - -The Trace View page is designed to be your one-stop-shop when debugging performance or errors. It gives you full context on what was happening when an error or performance issue occurred, all in one place. The waterfall Trace View allows you to see everything that may have occurred during a trace, including errors, performance issues, and any profiles that may have been collected. - -In addition, looking at the Trace View allows you to drill down into a single trace so you can visualize the high-level transactions and spans that took place within that trace. This makes debugging slow services, identifying related errors, and rooting out bottlenecks easier and faster, since you no longer have to navigate around multiple pages of the Sentry product. - -## [Product Walkthrough: Trace View Page](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#product-walkthrough-trace-view-page) - -Sentry's default visualization of a trace is a waterfall-like structure, where the entries (transactions and spans) in the list are organized chronologically and through ancestry (child spans will fall under their parents). This allows you to follow the order of operations and drill into sub-operations. - -On the left side is a list of operations, and on the right is their duration and any events, such as errors, which may have occurred in that timeframe. - -By default, the waterfall view shows a list of transactions. If you need more granular data and want to see spans as well, click "+" to the left of a transaction to expand the waterfall. The waterfall view helps surface any performance issues or profiles collected during a given timeframe. - -![Step 3](<Base64-Image-Removed>)![Expand transaction to view which span produced the error.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/9ee9049b-14ca-4c93-8829-e41a05b6fa2b.png) - -![](<Base64-Image-Removed>) - -### [Helpful Tips](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#helpful-tips) - -Because debugging often involves multiple people or teams, we've made it easy to draw attention to specific areas of the trace and share a link that shows what you've highlighted with your colleagues. To do this, click on the row you'd like to draw attention to and share the resulting URL. Your colleague will see exactly what you want them to. - -Whatever you highlight will also be saved if you navigate away from the page and will still be there when you use your browser's back and forward buttons. - -If you're doing a comparison and want an easy way to go back and forth between highlighted areas of interest in your trace, you can pin the tabs. When a tab is pinned, the view will be persistent throughout your session. - -Trace View — Tabbing - -Trace View — Tabbing - -![Pinning a tab will persist it.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/d2c464e2-9c6a-4212-8c9c-f84302a9ecac.png) - -![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/65d725cb-0e5f-4d04-960f-4c7118ddc307.png) - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -Sometimes, duration gaps between entries can be small, but critical to your debugging effort. That's why the Trace View enables you to zoom into certain areas of the trace, either by double clicking on row elements (which zooms into the row) or by using your scroll wheel. - -Trace View — Zooming - -Trace View — Zooming - -![Scroll to move around or scroll + meta key to zoom.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/37fcd5f8-b2b5-4483-b5e5-cd9904dca78d.png)![Step 1](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/980a208b-3fda-41fd-a52b-09d051b3f7d5.png) - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -The Trace View has other features like search, which makes it easy to visualize matching spans that you can then iterate over using the up or down arrows. You can also tailor the layout to your preference. - -We're going to continue adding features that enable you to perform efficient investigation into whatever issues you might be facing. If you have feedback or requests, please share it with us. We'd love to hear how we can make your life easier and your users happier. - -## [Troubleshooting](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#troubleshooting) - -### [Orphan Traces and Broken Subtraces](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#orphan-traces-and-broken-subtraces) - -In a fully instrumented system, a span in one service will connect to a transaction in a subsequent service. For a variety of reasons, a transaction in a service may not arrive in Sentry. When Sentry encounters these types of transactions within a trace, the transactions are linked with a dashed line since they can no longer be directly connected to the root, creating an orphan trace. - -In addition, broken subtraces can occur when Sentry receives an error for a trace, but the corresponding transaction does not exist. Such errors are linked using dashed lines and clicking on the row takes you to the corresponding **Issue Details** page. - -Also, in these cases you can click "Open In Discover" to see all the events in the trace. - -Broken subtraces may be caused by: - -- SDK sampling. Setting a sample rate that's too low may prevent the SDK from sending a transaction. We recommend [sending us all of your transaction data](https://docs.sentry.io/organization/dynamic-sampling/#deciding-on-your-sdk-sample-rate). -- [Ad blockers](https://docs.sentry.io/platforms/javascript/troubleshooting/#dealing-with-ad-blockers) may prevent transactions in browsers being sent, but HTTP requests to backend projects will still create child transactions -- [Rate-limiting](https://docs.sentry.io/product/accounts/quotas/#limiting-events) on a project may cause only some events to be sent to Sentry -- [Project permissions](https://docs.sentry.io/product/accounts/membership/#restricting-access) may mean you do not have access to transactions in another project -- [Differences in quota limits](https://docs.sentry.io/product/accounts/quotas/) between transactions and errors. When a quota limit is reached - for example, for transactions - an error is received, but corresponding transaction is not. -- Exceeding the span limit. Transactions are associated via the child spans of the parent transaction, but if the number of spans exceed the limit, the association cannot be made - -### [Multiple Roots](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/\#multiple-roots) - -Each trace ID should have only one root, a transaction without any parents. Automatic instrumentation should prevent multiple roots; however, if the trace ID of your transactions is being set using custom instrumentation, you may encounter multiple roots. - -[Previous\\ -\\ -Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing) - -[Next\\ -\\ -Search](https://docs.sentry.io/concepts/search) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/trace-view.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Account Settings](https://docs.sentry.io/account/) - -# Account Settings - -## Learn about Sentry's user settings and auth tokens. - -[Next\\ -\\ -Account Preferences](https://docs.sentry.io/account/user-settings) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/account/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) -- [Merging Issues](https://docs.sentry.io/concepts/data-management/event-grouping/merging-issues/) - -# Merging Issues - -## Learn about merging similar issues that aren't automatically grouped. - -This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. - -Escalating issues currently does not work for merged/unmerged issues, but we're working on fixing this. - -If you have similar-looking issues that have not been grouped together automatically and you want to reduce noise, you can do so by merging them. - -In this example, before merge, there are two issues that are very similar, but have not been grouped together. One issue has 39 events in the past 24 hours, and the other has 76: [![Before merge.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fbefore-merge-V2WAWJEZ.png%231484x444&w=3840&q=75)](https://docs.sentry.io/mdx-images/before-merge-V2WAWJEZ.png) - -After the two issues are merged into one, the event count of 115 on that one issue reflects that they've been grouped together: [![After merge.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fafter-merge-OQJFIWHK.png%231484x389&w=3840&q=75)](https://docs.sentry.io/mdx-images/after-merge-OQJFIWHK.png) - -You can also do this from inside a single issue. Click the "Similar Issues" tab, select all of the issues that you want to merge, and click "Merge": [![Similar Issues](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsimilar-issues-EYK6NV5S.png%231484x617&w=3840&q=75)](https://docs.sentry.io/mdx-images/similar-issues-EYK6NV5S.png) - -If you'd like to unmerge issues, go to the **Issue Details** page and click the “Merged Issues” tab. You will see the fingerprints that have been merged into that issue. Select the appropriate checkbox(es) and click “Unmerge”. - -It's important to note that we don't infer any new grouping rules from how you merge issues. Future events will be added to the merged set of issues by the same criteria as they would've been added to the individual issues that are now in the merged set. - -If Sentry creates more issues than you can merge, or too few issues, you can try updating your [Fingerprinting Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules/) or [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/). - -[Previous\\ -\\ -Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) - -[Next\\ -\\ -Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/merging-issues/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) - -# Tutorial: Create a Sentry Authentication Token - -To use Sentry's APIs, you must have an authentication token. This tutorial walks you through creating an organizational auth token through an internal integration. Sentry recommends using organizational auth tokens whenever possible, as they aren't linked to specific user accounts. - -See our documentation on [authentication](https://docs.sentry.io/api/auth/) to learn more about the different types of authentication tokens available. - -## [Prerequisites](https://docs.sentry.io/api/guides/create-auth-token/\#prerequisites) - -- A Sentry account with an organization-level role of Manager or Admin. - -## [Create an Internal Integration](https://docs.sentry.io/api/guides/create-auth-token/\#create-an-internal-integration) - -[Internal integrations](https://docs.sentry.io/organization/integrations/integration-platform/internal-integration/) are used to create custom Sentry integrations for your organization. They can also be used to create and manage your organization auth tokens. - -1. Open [sentry.io](https://sentry.io/) - -2. Click "Settings" in the left menu to open the **Organization Settings** page. - -3. Click "Custom Integrations" in the left side panel to create a new internal integration and org-level auth token. - -4. Press the "Create New Integration" button. - -5. Make sure "Internal Integration" is selected in the modal and press "Next". - -6. Enter a name for your integration. - - -[![Sentry.io UX walkthrough of creating an internal integration.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcreate-internal-integration-IFN34264.gif%23800x533&w=1920&q=75)](https://docs.sentry.io/mdx-images/create-internal-integration-IFN34264.gif) - -## [Create a API Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/\#create-a-api-authentication-token) - -1. Under "Permissions" select the permissions required for the APIs you wish to call. - -Each API endpoint docs page lists the required permissions, in the "Scopes" section. For example, the [Create a New Project](https://docs.sentry.io/api/projects/create-a-new-project/) endpoint requires project:write permissions or higher. - -2. Click "Save Changes". - -3. Scroll down to the bottom of the page and copy the generated token under "Tokens". - - -[![Sentry.io UX walkthrough of creating a token and setting it's permissions.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fset-token-permissions-Q4IZFS2Y.gif%23800x533&w=1920&q=75)](https://docs.sentry.io/mdx-images/set-token-permissions-Q4IZFS2Y.gif) - -Keep your auth token around on your clipboard or in an environment variable to use in API calls. - -[Previous\\ -\\ -Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial) - -[Next\\ -\\ -Authentication](https://docs.sentry.io/api/auth) - -- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/) - -# Session Replay Properties - -## Learn more about searchable session replay properties. - -[Session Replay](https://docs.sentry.io/product/explore/session-replay/) provides a video-like reproduction of user interactions on a site or web app. All user interactions, including page visits, mouse movements, clicks, and scrolls, are captured, helping developers connect the dots between a known issue and how a user experienced it in the UI. - -You can search by session replay properties on the **Replay** page. - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the session replay search. - -### [`activity`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#activity) - -Replay activity is calculated based on the number of errors, the number of ui events, and the duration of the replay. It's represented as a number from `1` to `10`. - -- **Type:** number - -### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#browsername) - -Name of the users' web browser. For example, `Chrome`, `Firefox`, or `Safari` - -- **Type:** string - -### [`browser.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#browserversion) - -The version string of the browser. - -- **Type:** string - -### [`click.alt`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickalt) - -The `alt` of an element that was clicked. For example, `"a good dog"` would match the element `<img src="/lassie.jpeg" alt="a good dog" />` - -- **Type:** string - -### [`click.class`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickclass) - -The `class` of an element that was clicked. No leading `.` is necessary. For example, `btn-primary` would match the element `<a class="btn btn-primary">Save</a>` - -- **Type:** string - -### [`click.component_name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickcomponent_name) - -The name of the frontend component that was clicked. For example, `MyAwesomeComponent` would match the React component `<MyAwesomeComponent>`. - -Note: This property requires that your project have [React component name capturing configured](https://docs.sentry.io/platforms/javascript/guides/react/features/component-names/). - -- **Type:** string - -### [`click.id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickid) - -The `id` of an element that was clicked. No leading `#` is necessary. For example, `reset-password` would match the element `<a id="reset-password">Reset</a>` - -- **Type:** string - -### [`click.label`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicklabel) - -The `aria-label` of an element that was clicked. For example, `Expand` would match the element `<button aria-label="Expand"><img src="/icons/expand.png"/></button>` - -- **Type:** string - -### [`click.role`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickrole) - -The `role` of an element that was clicked. For example, `button` would match both `<button>Save</button>` and `<a role="button">Submit</a>` - -- **Type:** string - -### [`click.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clickselector) - -An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. - -- **Type:** string - -### [`click.tag`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktag) - -The tag name of an element that was clicked. For example, `input` would match `<input name="username" />` - -- **Type:** string - -### [`click.testid`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktestid) - -The `data-testid` or `data-test-id` of an element that was clicked. For example, `user-name` would match the element `<a data-testid="user-name">User Name</a>` - -- **Type:** string - -### [`click.textContent`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktextcontent) - -The immediate `textContent` of an element that was clicked. For example, `Save` would match `<button>Save</button>` but wouldn't match `<button><h1>Save</h1></button>` - -- **Type:** string - -### [`click.title`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#clicktitle) - -The `title` of an element that was clicked. For example, `Save this comment` would match the element `<a title="Save this comment" class="btn btn-primary">Save</a>` - -- **Type:** string - -### [`count_dead_clicks`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_dead_clicks) - -The number of [dead clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Dead%20Clicks%3A%20User%20clicks%20on%20a%20and%20button%20tags%20that%20do%20not%20result%20in%20any%20page%20activity%20after%207%20seconds) within a replay. - -- **Type:** number - -### [`count_errors`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_errors) - -The number of errors within a replay. - -- **Type:** number - -### [`count_rage_clicks`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_rage_clicks) - -The number of [rage clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Rage%20Clicks%3A%20Five%20or%20more%20clicks%20on%20a%20dead%20element%20(it%20exhibits%20no%20page%20activity%20after%207%20seconds.)%20Rage%20clicks%20are%20a%20subset%20of%20dead%20clicks) within a replay. - -- **Type:** number - -### [`count_segments`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_segments) - -The number of segments within a replay. More segments represent more activity over time. - -- **Type:** number - -### [`count_urls`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#count_urls) - -The number of URLs that the user visited during a replay recording. - -- **Type:** number - -### [`dead.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#deadselector) - -Similar to the `click.selector` search property, but only queries on [dead clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Dead%20Clicks%3A%20User%20clicks%20on%20a%20and%20button%20tags%20that%20do%20not%20result%20in%20any%20page%20activity%20after%207%20seconds). An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. - -- **Type:** string - -### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicebrand) - -Brand of the device - -- **Type:** string - -### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicefamily) - -Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. - -- **Type:** string - -### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicemodel_id) - -Internal hardware revision to identify the device exactly. - -- **Type:** n/a - -### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#devicename) - -Details of the device - -- **Type:** string - -### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#dist) - -Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. - -- **Type:** string - -### [`duration`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#duration) - -Duration of a replay in seconds. - -- **Type:** number - -### [`error_ids`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#error_ids) - -Error event IDs that have occurred within a replay. - -- **Type:** array - -### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#id) - -The event or replay id. In **Issues**, use only the ID value without the `id` key. - -- **Type:** UUID - -### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#level) - -Severity of the event (such as: fatal, error, warning). Always set to info for transactions. - -- **Type:** string - -### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#osname) - -The name of the operating system. For example, `Windows`, `Mac OS X`, or `Linux` - -- **Type:** string - -### [`os.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#osversion) - -The version number of the operating system. - -- **Type:** string - -### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#platform) - -Name of the platform. This is only a metrics property for [valid platforms](https://github.com/getsentry/relay/blob/9d0d2dc54233d46043a369e1dacf7db900953c14/relay-general/src/protocol/constants.rs#L1-L21), defaulting to `other`. - -- **Type:** string - -### [`project_id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#project_id) - -The id of the project. - -- **Type:** string - -### [`rage.selector`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#rageselector) - -Similar to the `click.selector` search property, but only queries on [rage clicks](https://docs.sentry.io/product/explore/session-replay/replay-page-and-filters/#:~:text=Rage%20Clicks%3A%20Five%20or%20more%20clicks%20on%20a%20dead%20element%20(it%20exhibits%20no%20page%20activity%20after%207%20seconds.)%20Rage%20clicks%20are%20a%20subset%20of%20dead%20clicks). An element identified using a subset of CSS selector syntax. For example, `#section-1` or `span.active` or `span[role=button]` or `.active[role=button]` would all match the element `<span id="section-1" class="active" role="button"/>`. Note that, CSS combinators, pseudo selectors, and attr selectors other than `=` are not supported. - -- **Type:** string - -### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#release) - -A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). - -- **Type:** string - -### [`replayType`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#replaytype) - -The reason a replay was triggered. For example, `session` when `replaysSessionSampleRate` takes effect, or `error` when `replaysOnErrorSampleRate` is sampled instead of `session`. - -- **Type:** string - -### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#sdkname) - -Name of the Sentry SDK that sent the event. - -- **Type:** string - -### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#sdkversion) - -Version of the Sentry SDK that sent the event. - -- **Type:** string - -### [`seen_by_me`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#seen_by_me) - -Whether you've seen this replay. Alias: `viewed_by_me` - -- **Type:** boolean - -### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#trace) - -A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. - -- **Type:** UUID - -### [`url`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#url) - -A specific URL that the user visited during the replay. You can also search for multiple URLs at once using `urls` and passing in an array of strings. - -- **Type:** string - -### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#useremail) - -An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. - -- **Type:** string - -### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userid) - -Application-specific internal identifier for the user. - -- **Type:** string - -### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userip) - -User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. - -- **Type:** string - -### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/session-replay/\#userusername) - -Username, which is typically a better label than the `user.id`. - -- **Type:** string - -[Previous\\ -\\ -Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans) - -[Next\\ -\\ -User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/session-replay.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Tracing](https://docs.sentry.io/concepts/key-terms/tracing/) -- [Distributed Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) - -# Distributed Tracing - -## With distributed tracing, you can track software performance and measure throughput & latency, while seeing the impact of errors across multiple systems. - -Distributed tracing provides a connected view of your application from frontend to backend. It helps track software performance, measure [metrics](https://docs.sentry.io/product/insights/overview/metrics/) like throughput and latency, and display the impact of errors across multiple systems. This makes Sentry a more complete [performance monitoring](https://docs.sentry.io/product/insights/overview/) solution, aiding in diagnosing problems and measuring your application's overall health. - -[Tracing](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/) in Sentry provides insights such as: - -- What occurred for a specific error event or issue -- The conditions causing bottlenecks or latency issues -- The endpoints or operations consuming the most time - -## [What Is Distributed Tracing?](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#what-is-distributed-tracing) - -A tracing tool focuses on what happened (and when), logging events during a program's execution across multiple systems. Traces often include timestamps, allowing durations to be calculated, but their purpose is broader, showing how interconnected systems interact and how problems in one can affect another. While tracing can be useful if instrumented in just the frontend or backend, it's most powerful when set up for your full stack (distributed tracing). - -It's important to note that tracing is not [profiling](https://docs.sentry.io/product/explore/profiling/). A profiler measures various aspects of an application's operation, resulting in a statistical summary. While both diagnose application problems, they differ in what they measure and how data is recorded. - -Learn more in this [Tracing: Frontend issues with backend solutions](https://sentry.io/resources/tracing-frontend-issues-with-backend-solutions/?original_referrer=https%3A%2F%2Fblog.sentry.io%2F) workshop. - -### [The Tracing Data Model](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#the-tracing-data-model) - -Ultimately, any data structure is defined by the kind of data it contains, and relationships between data structures are defined by how links between them are recorded. Traces, transactions, and spans are no different. - -#### [Traces](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#traces) - -Traces are defined as the collection of all transactions that share a `trace_id` value. - -#### [Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#transactions) - -Transactions share most properties (start and end time, tags, and so on) with their root spans. They also have a `transaction_name` property, used in the UI to identify the transaction. Common examples include endpoint paths for backend request transactions, task names for cron job transactions, and URLs for page-load transactions. - -Before the transaction is sent, the `tags` and `data` properties will get merged with data from the global scope. (Global scope data is set in `Sentry.init()` or by using `Sentry.configureScope()`, `Sentry.setTag()`, `Sentry.setUser()`, or `Sentry.setExtra()`.) - -Transaction names can contain **sensitive data**. See [Scrubbing Sensitive Data](https://docs.sentry.io/platforms/javascript/data-management/sensitive-data/#scrubbing-data) for more information. - -#### [Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#spans) - -Span data includes: - -- `parent_span_id`: ties the span to its parent span -- `op`: short string identifying the type or category of operation the span is measuring -- `start_timestamp`: when the span was opened -- `end_timestamp`: when the span was closed -- `description`: longer description of the span's operation -- `status`: short code indicating operation's status -- `tags`: key-value pairs holding additional data about the span -- `data`: arbitrarily-structured additional data about the span - -An example use of the `op` and `description` properties together is `op: db.query` and `description: SELECT * FROM users WHERE last_active < %s`. The `status` property indicates the success or failure of the span's operation, or a response code for HTTP requests. `Tags` and `data` attach further contextual information to the span, such as `function: middleware.auth.is_authenticated` for a function call or `request: {url: ..., headers: ... , body: ...}` for an HTTP request. To search span data see [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) - -### [What Can Tracing Help With?](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#what-can-tracing-help-with) - -Applications consist of interconnected components or services. For example, a modern web application may include: - -- Frontend (Single-Page Application) -- Backend (REST API) -- Task Queue -- Database Server -- Cron Job Scheduler - -Each component can be instrumented individually using a Sentry SDK to capture error data or crash reports, but this doesn't provide the full picture. Distributed tracing ties all the data together. - -Distributed tracing allows you to follow a request from the [frontend](https://docs.sentry.io/product/sentry-basics/integrate-frontend/) to the [backend](https://docs.sentry.io/product/sentry-basics/integrate-backend/) and back, pulling in data from any background tasks or notification jobs that request creates. This helps correlate Sentry error reports and gain insights into which services may negatively impact your application's performance. - -## [Traces, Transactions, and Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#traces-transactions-and-spans) - -A **trace** represents the record of the entire operation you want to measure or track, like page load or a user action. When a trace includes work in multiple services, it's called a **distributed trace**. - -Each trace consists of one or more tree-like structures called [**transactions**](https://docs.sentry.io/product/insights/overview/transaction-summary/), with nodes called **spans**. Each transaction represents a single instance of a service being called, and each span represents a single unit of work. Here's an example trace, broken down into transactions and spans: - -[![Diagram illustrating how a trace is composed of multiple transactions, and each transaction is composed of multiple spans.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-trace-LTDLDUUH.png%231800x1031&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-trace-LTDLDUUH.png) - -Top-level spans can be broken down into smaller spans, mirroring the way one function may call others. Every span may be the **parent span** to multiple **child spans**. One span in every transaction represents the transaction itself, with all other spans descending from that root span. Here's a zoomed-in view of one of the transactions from the diagram above: - -[![Diagram illustrating the parent-child relationship between spans within a single transaction.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-spans-55HVFBGN.png%231801x927&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-spans-55HVFBGN.png) - -### [Tracing Example: Investigating Slow Page Load](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#tracing-example-investigating-slow-page-load) - -Suppose your web application is slow to load. A lot has to happen for your app to get to a usable state: multiple requests to your backend, calls to your database or external APIs, and browser processing. Which part is slowing things down? - -In this simplified example, when a user loads the app in their browser, the following happens: - -- _Browser_ - - 1 request each for HTML, CSS, and JavaScript - - 1 rendering task, which sets off 2 requests for JSON data -- _Backend_ - - 3 requests to serve static files (HTML, CSS, JS) - - 2 requests for JSON data - 1 requiring a database call, 1 requiring an external API call and processing -- _Database Server_ - - 1 request requiring 2 queries (authentication and data retrieval) - -_Note:_ The external API is not listed as it's external and can't be seen inside. - -The entire page-loading process is represented by a single **trace**. That trace consists of the following **transactions**: - -- 1 browser transaction (for page load) -- 5 backend transactions (one for each request) -- 1 database server transaction (for the single DB request) - -Each transaction is broken down into **spans**: - -- _Browser Page-load Transaction_: 7 spans - - 1 root span for the entire page load - - 1 span each (3 total) for HTML, CSS, and JS requests - - 1 span for the rendering task, containing 2 child spans for each JSON request - -Some spans in the browser transaction correspond to backend transactions. When a span in one service gives rise to a transaction in another, the original span is a parent span to both the transaction and its root span. In the diagram below, squiggly lines represent this parent-child relationship. - -[![Diagram illustrating the trace-transaction-span relationship applied to the example.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdiagram-transaction-example-G467OIQ5.png%231800x1031&w=3840&q=75)](https://docs.sentry.io/mdx-images/diagram-transaction-example-G467OIQ5.png) - -In our example, every transaction other than the initial browser page-load transaction is the child of a span in another service. In a fully-instrumented system, this pattern always holds true. The only parentless span is the root of the initial transaction; every other span has a parent. Parents and children live in the same service, except when the child span is the root of a child transaction, in which case the parent span lives in the calling service and the child transaction/child root span lives in the called service. - -A fully-instrumented system creates a trace which is a connected tree, with each transaction a subtree. The boundaries between subtrees/transactions are the boundaries between services. The diagram above shows one branch of our example's full trace tree. - -Now, back to our spans: - -- _Backend HTML/CSS/JS Request Transactions_: 1 span each - - 1 root span for the entire request (child of a browser span) -- _Backend Request with DB Call Transaction_: 2 spans - - 1 root span for the entire request (child of a browser span) - - 1 span for querying the database (parent of the database server transaction) -- _Backend Request with API Call Transaction_: 3 spans - - 1 root span for the entire request (child of a browser span) - - 1 span for the API request (not a parent span, as the API is external) - - 1 span for processing the API data -- _Database Server Request Transaction_: 3 spans - - 1 root span for the entire request (child of the backend span above) - - 1 span for the authentication query - - 1 span for the data retrieval query - -After instrumenting all services, you might discover that the auth query in your database server is causing the slowdown. Tracing can't tell you _why_ it's happening, but now you know where to look! - -### [Further Examples of Tracing, Transactions & Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#further-examples-of-tracing-transactions--spans) - -#### [Measuring a Specific User Action](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#measuring-a-specific-user-action) - -For an e-commerce application, you might measure the time between a user clicking "Submit Order" and the order confirmation appearing. This process is one trace, with transactions ( _T_) and spans ( _S_) for: - -- Browser's full process ( _T_ and root span _S_) - - XHR request to backend\* ( _S_) - - Rendering confirmation screen ( _S_) -- Backend's processing of the request ( _T_ and root span _S_) - - Function call to compute total ( _S_) - - DB call to store order\* ( _S_) - - API call to payment processor ( _S_) - - Queuing of email confirmation\* ( _S_) -- Database's work updating the customer's order history ( _T_ and root span _S_) - - Individual SQL queries ( _S_) -- Queued task of sending the email ( _T_ and root span _S_) - - Function call to populate email template ( _S_) - - API call to email-sending service ( _S_) - -\\* Starred spans are parents of later transactions (and their root spans). - -#### [Monitoring a Background Process](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#monitoring-a-background-process) - -For a backend periodically polling for data from an external service, processing it, caching it, and forwarding it to an internal service, each instance is a trace, with transactions ( _T_) and spans ( _S_) for: - -- Cron job completing the entire process ( _T_ and root span _S_) - - API call to external service ( _S_) - - Processing function ( _S_) - - Call to caching service\* ( _S_) - - API call to internal service\* ( _S_) -- Work done in your caching service ( _T_ and root span _S_) - - Checking cache for existing data ( _S_) - - Storing new data in cache ( _S_) -- Internal service's processing of the request ( _T_ and root span _S_) - - Handling the request ( _S_) - -\\* Starred spans are parents of later transactions (and their root spans). - -### [Important Information About Tracing, Spans & Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#important-information-about-tracing-spans--transactions) - -#### [Trace Duration](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#trace-duration) - -A trace begins when the earliest transaction starts, and ends when the last transaction ends. You can't "start" or "end" a trace, but you can initiate a transaction which will triggers a trace. Completing all transactions ends a trace. - -#### [Async Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#async-transactions) - -Child transactions may outlive the transactions containing their parent spans. For example, if a backend API call sets off a long-running task and then immediately returns a response, the backend transaction will finish long before the async task transaction does. Asynchronicity means that the order in which transactions are sent to Sentry won't depend on the order they were created. However, order of receipt for transactions in the same trace is correlated with order of completion. - -#### [Orphan Transactions](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#orphan-transactions) - -In a fully instrumented system, each trace should contain only one transaction and one span (the transaction's root) without a parent. However, you may not have tracing enabled in every service, or an instrumented service may fail to report a transaction. This can result in gaps in your trace hierarchy, with non-originating, parentless transactions called **orphan transactions**. - -#### [Nested Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#nested-spans) - -There's no set limit to how deep the nesting of spans can go, but practical limits exist: transaction payloads sent to Sentry have a maximum allowed size, and there's a balance between data granularity and usability. - -#### [Zero-duration Spans](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#zero-duration-spans) - -A span can have equal start and end times which will be recorded as taking no time. This can occur if the span is being used as a marker, for example, in the browser's [performance API](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark), or if the operation's duration is less than the measurement resolution (which will vary by service). - -#### [Clock Skew](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#clock-skew) - -Collecting transactions from multiple machines may result in **clock skew**, where timestamps in one transaction don't align with timestamps in another. To reduce this, use Network Time Protocol (NTP) or your cloud provider's clock synchronization services. - -#### [How Data is Sent](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#how-data-is-sent) - -Individual spans aren't sent to Sentry; the entire transaction is sent as one unit. No span data is recorded by Sentry's servers until the transaction is closed and dispatched. Transactions are still valid and sent even if they only contain their root span. - -## [Data Sampling](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#data-sampling) - -When you enable sampling, you choose a percentage of collected transactions to send to Sentry. For example, a sampling rate of `0.25` for an endpoint receiving 1000 requests per minute results in approximately 250 transactions being sent to Sentry each minute. Sampling helps manage the number of events sent to Sentry and balances performance and volume concerns with data accuracy. - -### [Consistency Within a Trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#consistency-within-a-trace) - -Sentry uses a "head-based" approach: a sampling decision is made in the originating service and passed to subsequent services. For example, if a browser makes requests to your backend, it includes the sampling decision in the headers. The backend collects transaction and span data if the decision is "yes" and passes the decision to subsequent services. This ensures either all transactions for a given trace are collected, or none are. - -Dynamic sampling ensures complete traces by retaining all transactions associated with a trace if the head transaction is preserved. However, transactions or other items may still be missing from a trace when rate limiting or quota enforcement drops them. - -## [Viewing Trace Data](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/\#viewing-trace-data) - -Use the [Trace Explorer](https://docs.sentry.io/product/explore/traces/) to search for traces containing spans that meet your specific query conditions. This helps you find distributed traces that give you a connected view of your application and can help you debug and optimize your code. - -Through [Performance](https://docs.sentry.io/product/insights/overview/) and [Discover](https://docs.sentry.io/product/explore/discover-queries/), you can also view trace data in the [Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view/) page. - -[Previous\\ -\\ -Tracing](https://docs.sentry.io/concepts/key-terms/tracing) - -[Next\\ -\\ -Trace View](https://docs.sentry.io/concepts/key-terms/tracing/trace-view) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/tracing/distributed-tracing.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) - -# Data Source Name (DSN) - -## A Data Source Name (DSN) tells Sentry where to send events so they’re associated with the correct project. Learn more about DSN structure and use here. - -Sentry automatically assigns you a Data Source Name (DSN) when you create a project to start monitoring events in your app. - -### [What the Data Source Name (DSN) Does](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#what-the-data-source-name-dsn-does) - -A DSN tells a Sentry SDK where to send events so the events are associated with the correct project. - -If this value is not provided, SDKs will try to read it from the `SENTRY_DSN` environment variable, where applicable. This fallback does not apply in cases like a web browser, where the concept of environment variables does not exist. - -If an SDK is not initialized or if it is initialized with an empty DSN, the SDK will not send any data over the network, such as captured exceptions. - -### [DSN Utilization](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#dsn-utilization) - -DSNs are safe to keep public because they only allow submission of new events and related event data; they do not allow read access to any information. - -While there is a risk of abusing a DSN, where any user can send events to your organization with any information they want, this is a rare occurrence. Sentry provides controls to [block IPs](https://docs.sentry.io/platform-redirect/?next=/configuration/options/) and similar concerns. You can also rotate (and revoke) DSNs by navigating to **\[Project\] > Settings > Client Keys (DSN)**. - -If your application is shipped to client devices, if possible, we recommend having a way to configure the DSN dynamically. In an ideal scenario, you can "ship" a new DSN to your application without the customer downloading the latest version. We recognize that this may not always be practical, but we cannot offer further advice as this scenario is implementation specific. - -### [Where to Find Your Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#where-to-find-your-data-source-name-dsn) - -If you're in the process of setting up a project, you can find your DSN in the installation or configuration code snippets provided in [sentry.io](https://sentry.io/) during setup: - -[![DSN in code snippet](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcreate-new-project-04-VZTPA47T.png%231400x766&w=3840&q=75)](https://docs.sentry.io/mdx-images/create-new-project-04-VZTPA47T.png) - -You can also find the DSN in your project settings by navigating to **\[Project\] > Settings > Client Keys (DSN)** in [sentry.io](https://sentry.io/). - -### [The Parts of the Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer/\#the-parts-of-the-data-source-name-dsn) - -The DSN configures the protocol, public key, server address, and project identifier. It is composed of the following parts: - -`{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}` - -For example: - -JavaScript - -`` - -```javascript code-highlight -Sentry.init({ dsn: "https://public@sentry.example.com/1" }); - -``` - -Has the following settings: - -- URI = [https://sentry.example.com](https://sentry.example.com/) -- Public Key = public -- Project ID = 1 - -The secret part of the DSN is optional and effectively deprecated. While clients will still honor it, if supplied, future versions of Sentry will entirely ignore it. - -[Previous\\ -\\ -Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms) - -[Next\\ -\\ -Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/dsn-explainer.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) -- [Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana/) - -# Grafana - -## Learn about Sentry's Grafana integration, which alows you to query and visualize Sentry data within Grafana. - -If you make changes to your organization slug, you'll need to update your configuration for this integration. Learn more in our [troubleshooting guide](https://docs.sentry.io/organization/integrations/troubleshooting/). - -Visualize your Sentry [Issues](https://docs.sentry.io/product/issues/) and [Stats](https://docs.sentry.io/product/stats/) data in Grafana with the Sentry [data source plugin](https://grafana.com/grafana/plugins/grafana-sentry-datasource/). Once installed, you can combine Sentry data with that of other sources, like your infrastructure data through Prometheus or your business data from your data warehouse, in a single dashboard. - -[Previous\\ -\\ -Amazon SQS](https://docs.sentry.io/organization/integrations/data-visualization/amazon-sqs) - -[Next\\ -\\ -Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/grafana.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs/) - -# Product Documentation Structure - -The topics in this section describe how to create Sentry product documentation. - -[Previous\\ -\\ -SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) - -[Next\\ -\\ -How to Write - Index Pages](https://docs.sentry.io/contributing/approach/product-docs/write-index) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/product-docs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) -- [Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/) - -# Cloudflare Workers - -## Learn more about how you can use Sentry to monitor errors in your Cloudflare Workers applications. - -Cloudflare Workers allow you to deploy serverless applications instantly across the globe with exceptional performance, reliability, and scale. - -This integration is maintained and supported by the company that created it. For more details or questions, please contact Cloudflare through their support portal: [https://developers.cloudflare.com/support/contacting-cloudflare-support/](https://developers.cloudflare.com/support/contacting-cloudflare-support/) - -## [Install and Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/\#install-and-configure) - -Sentry owner, manager, or admin permissions are required to install this integration. - -1. Navigate to **Settings > Integrations > Cloudflare Workers** - -2. Follow the full [Cloudflare Workers installation instructions](https://developers.cloudflare.com/workers/observability/sentry-integration/). - - -[Previous\\ -\\ -AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) - -[Next\\ -\\ -Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/cloudflare-workers/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Environments](https://docs.sentry.io/concepts/key-terms/environments/) - -# Environments - -## Learn more about how environments can help you better filter issues, releases, and user feedback in the Issue Details page on sentry.io. - -`Environment` is a Sentry-supported tag that you can (and should) add to your SDK. Generally, the tag accepts any value, but it's intended to refer to your code deployments' naming convention, such as _development_, _testing_, _staging_, or _production_. - -Environments help you better filter issues, releases, and user feedback in the **Issue Details** page of [sentry.io](https://sentry.io/). On that page, you can view information about a specific environment, focusing on the most recent release. If you’re using a multi-staged release process, you can also select a different default environment and set conditions that match the `environment` attribute to restrict alerts to only specific release stages. - -Use projects to separate different services or applications, and environments to separate different environments or release stages within each. If you've selected one or more projects in the filters of Sentry's web UI, the environment selector shows only environments associated with events from the selected projects. - -[![All Envs dropdown](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-env-LUSK3KCI.png%232550x824&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-env-LUSK3KCI.png) - -Environments are unique to each organization. Environment settings, however, are defined per project since you can hide environments per project. - -## [Creating Environments](https://docs.sentry.io/concepts/key-terms/environments/\#creating-environments) - -Sentry automatically creates environments when it receives an event with the environment tag. Environments are case-sensitive. You can also create an environment when you first `init` your SDK, [as documented for each SDK](https://docs.sentry.io/platform-redirect/?next=/configuration/environments/). - -## [Environment Filter](https://docs.sentry.io/concepts/key-terms/environments/\#environment-filter) - -### [Issues](https://docs.sentry.io/concepts/key-terms/environments/\#issues) - -If an issue has events from multiple environments, the issue will appear when you select any of those environments. Sentry defines an issue as a grouping of similar events. If you tag one or more events within an issue with a specific environment, that issue will appear in your view when filtered by that environment. For example, if an issue is composed of one event tagged with `Production` and one event tagged with `Staging`, the issue will appear in your view when filtering by `Production`, as well as by `Staging`. - -Also, the environment filter affects all issue-related metrics, such as the count of users affected, times series graphs, and event count. - -### [Releases](https://docs.sentry.io/concepts/key-terms/environments/\#releases) - -A release by itself is not associated with an environment but can be deployed to different environments. When you select an environment on the releases page, it shows releases that were deployed to that environment. For example, a release deployed to the `QA` and `Prod` environment will appear in your view when filtering by `QA`, as well as `Prod`. All issue-related metrics within a given release will be affected by the environment filter. A deploy must have an environment. - -For more details about configuring releases and deploys, see the [full documentation on Releases](https://docs.sentry.io/product/releases/). - -## [Hidden Environments](https://docs.sentry.io/concepts/key-terms/environments/\#hidden-environments) - -Since you can't delete environments, Sentry has an option to hide it from the UI. Hiding environments can be useful when you're no longer sending events from an environment, or you've accidentally created an environment you no longer want. You can hide environments from your environments dropdown by navigating to **Project Settings > Environments**, and selecting "Hide", but events sent to that environment **will still count against your quota**. - -If a project is hidden, you won't see that environment in the environment selector, unless another project with events from the same environment is also selected (and doesn't have it hidden in its project settings). - -Follow along with the interactive demo below to see how to hide and unhide environments. - -Environments - Hide/show - -Environments - Hide/show - -![Click to manage the project's environments.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/86a983ea-b01e-4467-b279-8acb0b6380cb.png)![Click to hide this environment.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/8e47441a-fe6b-4a44-a917-e59603034d0a.png)![Open this project's settings.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/5a1e819b-d387-475c-be8f-84bba1b6f1e2.png) - -Open this project's settings. - -![](data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%2724%27%20height=%2724%27/%3e)![](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=48/watermark-logos/sentry.io-1678147382564.png) - -[Previous\\ -\\ -Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates) - -[Next\\ -\\ -Event Data](https://docs.sentry.io/concepts/key-terms/enrich-data) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/environments/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [Release Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/) - -# Release Properties - -## Learn more about searchable release properties. - -In **Releases**, you can only search by the following properties: - -- [`release`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#release) -- [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasebuild) -- [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasepackage) -- [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releasestage) -- [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/releases/#releaseversion) - -However, these properties are also searchable in the other pages of [sentry.io](https://sentry.io/) listed above (under [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/#event-properties)). - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the release search. - -### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#release) - -A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). - -- **Type:** string - -### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasebuild) - -The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** number - -### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasepackage) - -The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releasestage) - -The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). - -- **Type:** string - -### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/releases/\#releaseversion) - -A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -[Previous\\ -\\ -User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback) - -[Next\\ -\\ -Saved Searches](https://docs.sentry.io/concepts/search/saved-searches) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/releases.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Redirects](https://docs.sentry.io/contributing/pages/redirects/) - -# Redirects - -Redirects allow you to automatically redirect an incoming request path to a new destination path. When you move or rename a file, you should make sure to set up a redirect from the old path to the new path, so that the old URL still takes users to the right place. - -## [Add a New Redirect](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect) - -There are two ways to add redirects in the Sentry docs: - -- [Add a New Redirect in `middleware.ts` (Recommended)](https://docs.sentry.io/contributing/pages/redirects/#add-a-new-redirect-in-middlewarets-recommended) -- [Add a New Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/#example-redirect-in-redirectsjs) - -Both files make the distinction between SDK docs (ie. end user docs) and developer docs. - -Because Sentry has a limited number of `next.config.js` redirects, you should configure your redirects in `middleware.ts` whenever possible. You should only use `redirects.js` ie ( `next.config.js`) if you need to use regular expressions and wildcard path segments in your redirects. - -It's no longer recommended to use `vercel.json` for redirects due to its limitations (doesn't work on localhost, requires a static file ...) - -### [Add a New Redirect in `middleware.ts` (Recommended)](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect-in-middlewarets-recommended) - -Set up all simple one-to-one redirects in `src/middleware.ts`. - -To add a new redirect in [`src/middleware.ts`](https://github.com/getsentry/sentry-docs/blob/master/src/middleware.ts), add a new object to `REDIRECTS` with the following properties: - -- `from`: The incoming request path. -- `to`: The new destination path you want to route to. - -#### [Example Redirect in `middleware.ts`](https://docs.sentry.io/contributing/pages/redirects/\#example-redirect-in-middlewarets) - -The example below redirects `https://docs.sentry.io/performance/` to `https://docs.sentry.io/product/performance/`: - -TypeScript - -`middleware.ts` - -```code-highlight typescript -const REDIRECTS: { from: PathWithTrailingSlash; to: string }[] = [\ - {\ - from: "/performance/",\ - to: "/product/performance/",\ - },\ -]; - -``` - -### [Add a New Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/\#add-a-new-redirect-in-redirectsjs) - -Sentry has a limited number of Vercel redirects, so you should only configure redirects in `vercel.json` if your redirects need to use regular expressions. Otherwise, use [`middleware.ts`](https://docs.sentry.io/contributing/pages/redirects/#add-a-new-redirect-in-middlewarets-recommended). - -To add a new redirect in `redirects.js` (which is consumed by `next.config.js`'s [`redirects`](https://nextjs.org/docs/app/api-reference/next-config-js/redirects)), add a new object to the corresponding redirects with the following properties: - -- `source`: The incoming request path pattern. -- `destination`: The new destination path you want to route to. - -#### [Example Redirect in `redirects.js`](https://docs.sentry.io/contributing/pages/redirects/\#example-redirect-in-redirectsjs) - -The example below redirects URLs like `https://docs.sentry.io/cli/:path*` to `https://docs.sentry.io/product/cli/:path*` with a [path pattern](https://nextjs.org/docs/app/api-reference/next-config-js/redirects#path-matching) or a [Regex](https://nextjs.org/docs/app/api-reference/next-config-js/redirects#regex-path-matching). - -For example, `https://docs.sentry.io/cli/installation/` would be redirected to `https://docs.sentry.io/product/cli/installation/`. - -JSON - -`redirects.js` - -```code-highlight json - "redirects": [\ - {\ - "source": "/cli/:path*",\ - "destination": "/product/cli/:path*",\ - },\ - ] - -``` - -[Previous\\ -\\ -Markdown Variables](https://docs.sentry.io/contributing/pages/variables) - -[Next\\ -\\ -Search](https://docs.sentry.io/contributing/pages/search) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/redirects.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Two-Factor Authentication (2FA)](https://docs.sentry.io/organization/authentication/two-factor-authentication/) - -# Two-Factor Authentication (2FA) - -## Learn about adding two-factor authentication (2FA) across your organization. - -For an added layer of security, you can require your organization members to sign in to Sentry with two-factor authentication (2FA). - -## [Preface](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#preface) - -Sentry owner permissions are required to enforce two-factor authentication across your organization. - -1. Before you can require organization members to use 2FA, you must [enable two-factor authentication](https://sentry.io/settings/account/security/) for your own user account. - -2. We recommend notifying your organization members, and asking them to setup 2FA for their accounts before requiring two-factor authentication. You can see which members are enrolled on your organization's members page. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-members-MDCYZAVC.png%232302x644&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-members-MDCYZAVC.png) - - -## [Setup Require 2FA](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#setup-require-2fa) - -When you require two-factor authentication, members who are not enrolled in 2FA will be removed from your organization. They will lose access to your organization's projects and notifications, and will be sent an email to setup 2FA. They can reinstate their access and settings within three months of their removal from your organization. - -1. Go to **Organization Settings** >\> General Settings. - -2. Under Security & Privacy, toggle the **Require Two-Factor Authentication** switch. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-switch-PEMDTERA.png%232268x510&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-switch-PEMDTERA.png) - -3. Click **Confirm**. - - -## [View Removed Members](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#view-removed-members) - -To view members who were removed from your organization for 2FA non-compliance, you can look at your organization's audit log. - -1. Go to **Organization Settings** >\> Audit Log. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-audit-log-I7U3UAPT.png%231151x314&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-audit-log-I7U3UAPT.png) - -2. You can filter for action **member.pending** to see removed organization members, and action **org.edit** to see when the require\_2fa organization setting was changed. - - -## [Require 2FA and SSO](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#require-2fa-and-sso) - -Require 2FA is currently not available with single sign-on (SSO), so you would need to require two-factor authentication with your identity provider. - -## [Steps to Rejoin an Organization](https://docs.sentry.io/organization/authentication/two-factor-authentication/\#steps-to-rejoin-an-organization) - -To reinstate your access and previous settings, you need to setup 2FA within three months of being removed from your organization. - -If you were removed from an organization due to 2FA non-compliance, follow these steps to rejoin the organization and reinstate your access and settings: - -1. Look in your inbox for an email from Sentry titled **Mandatory: Enable Two-Factor Authentication**. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-email-LIDX2RQV.png%231452x716&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-email-LIDX2RQV.png) - -2. Click the **Enable Two-Factor Authentication** button. - -3. If you can't find the email, ask an organization Owner or Manager to go to the **Organization Settings** >\> Members page and resend your invite. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-resend-invite-5O5DOKPB.png%232300x508&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-resend-invite-5O5DOKPB.png) - -4. After clicking through the email, you will be prompted to **Setup Two-Factor Authentication** before rejoining the organization. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-rejoin-7FOGWUDE.png%231594x718&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-rejoin-7FOGWUDE.png) - -5. This will take you to your **Account Settings** >\> [Security](https://sentry.io/settings/account/security/) page where you need to setup at least one form of two-factor authentication. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frequire-2fa-add-auth-6XIZZ7ZY.png%231804x1158&w=3840&q=75)](https://docs.sentry.io/mdx-images/require-2fa-add-auth-6XIZZ7ZY.png) - -6. Once you've enrolled in 2FA, remember to save your recovery codes in a safe place and consider adding a backup phone number. - -7. Then use the left sidebar to navigate to your organization. - - -[Previous\\ -\\ -Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) - -[Next\\ -\\ -Organization and User Management](https://docs.sentry.io/organization/membership) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/two-factor-authentication/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) -- [AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) - -# AWS Lambda - -## Learn more about Sentry's AWS Lambda integration and how you can automatically instrument your Node or Python Lambda functions with Sentry without changing your code. - -This method of setting up Sentry in your Lambda functions only works if your Lambda functions are run in Node CommonJS ( `require` syntax) or in Python. For all other setups, check out these docs for [Node](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/) or [Python](https://docs.sentry.io/platforms/python/integrations/aws-lambda/) instead. - -Connect Sentry to your AWS account to automatically add Sentry error and performance monitoring to your Node/Python Lambda functions. - -## [Install](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#install) - -Sentry owner, manager, or admin permissions are required to install this integration. - -1. Navigate to **Settings > Integrations > AWS Lambda**. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fdirectory-YJU2HMO4.png%23784x148&w=1920&q=75)](https://docs.sentry.io/mdx-images/directory-YJU2HMO4.png) - -2. Press **Add Installation** to open the installation modal. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fintegration_detail-N2MWP2PA.png%23766x358&w=1920&q=75)](https://docs.sentry.io/mdx-images/integration_detail-N2MWP2PA.png) - -3. Select the project for your Lambda integration. **Note:** This project cannot be changed after installation is complete. If you only have a single project, you'll skip this step. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fproject-Z67O7VPA.png%23807x817&w=1920&q=75)](https://docs.sentry.io/mdx-images/project-Z67O7VPA.png) - -4. Click **Go To AWS**. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Faws_account_1-HPNEZBRF.png%23831x874&w=1920&q=75)](https://docs.sentry.io/mdx-images/aws_account_1-HPNEZBRF.png) - -5. Scroll to the bottom of the Create Stack page, check the box, then press **Create Stack** to create a CloudFormation stack in your current region. This stack allows Sentry to automatically instrument your Lambda functions. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcloudformation-create-stack-7BTDG2LP.png%23843x954&w=1920&q=75)](https://docs.sentry.io/mdx-images/cloudformation-create-stack-7BTDG2LP.png) - -6. Wait for the stack to be created. Once it's confirmed and the status changes to **Create Complete**, click **I've created the stack** in the Sentry popup. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcloudformation-stack-create-complete-EEVLPRGY.png%23816x429&w=1920&q=75)](https://docs.sentry.io/mdx-images/cloudformation-stack-create-complete-EEVLPRGY.png) - -7. Now copy your AWS Account ID, select the region you want to use, and press **Next**. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Faws_account_2-NJCMJDLP.png%23772x806&w=1920&q=75)](https://docs.sentry.io/mdx-images/aws_account_2-NJCMJDLP.png) - - -You need to create the CloudFormation stack only once per account, even when installing the integration in multiple regions. If you are setting up the integration in a second region, copy the externalId from the existing CloudFormation stack on the "Parameters" tab into the form shown above. - -8. Select the Lambda functions to automatically add the Sentry layer and necessary environment variables when you **Finish Setup**. **Note:** You can enable or disable Sentry on Lambda functions after installation. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fselect_lambdas-X5V2NHJW.png%23817x976&w=1920&q=75)](https://docs.sentry.io/mdx-images/select_lambdas-X5V2NHJW.png) - - -Wait a few minutes as the Lambda functions are enabled. If any functions failed to instrument, follow the suggestions in Troubleshooting. - -### [Troubleshooting](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#troubleshooting) - -If you need help solving issues with your Sentry AWS Lamba integration, you can read the edge cases documented here. If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. - -- #### [Error `SentryRole already exists`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-sentryrole-already-exists) - - -The stack already exists in your account; you can proceed to the next step and add your AWS account information. - -- #### [Error `Invalid existing layer`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-invalid-existing-layer) - - -Your Lambda function has a layer that no longer exists. Please remove the problematic layer, then enable Sentry on the Lambda in the configuration view for the integration. - -- #### [Error `Please validate the CloudFormation stack was created successfully`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-please-validate-the-cloudformation-stack-was-created-successfully) - - -Sentry is unable to access your AWS account through your CloudFormation stack. This means either the stack has not been created or the external ID used doesn't match the one in your installation. You can go to the Parameters tab of the CloudFormation stack to copy the value of the external ID and paste it into the form field. - -- #### [Error `Invalid role associated with the lambda function`](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#error-invalid-role-associated-with-the-lambda-function) - - -The role associated with your Lambda function no longer exists. Please add a new role to your Lambda function, then enable Sentry on the Lambda in the configuration view for the integration. - - -## [Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#configure) - -The integration configuration view in Sentry allows you to do the following with your Lambda functions: - -- Enable Sentry -- Disable Sentry -- Update the Sentry Lambda Layer to the latest version - -In the table view, you will also see the version of the Lambda layer below the name. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-manage-functions-YDXF7XDR.png%23885x296&w=1920&q=75)](https://docs.sentry.io/mdx-images/sentry-manage-functions-YDXF7XDR.png) - -## [Verify](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#verify) - -Run your AWS Lambda function. Performance data will be sent to Sentry and will show up on the **Performance** page in Sentry. If your function raises an error it will show up on the **Issues** page in Sentry. - -## [Remove Installation](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#remove-installation) - -Note that when the integration is uninstalled, your Lambda functions will still be instrumented with Sentry and you will continue to receive errors. If you want to disable Sentry for all your Lambda functions, you should disable Sentry for each function before uninstalling. Note, you can also uninstall and then reinstall if you would like to change the Sentry project for your Lambdas. - -Learn more about [how this integration works](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/). - -## [Notes on Specific Frameworks](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#notes-on-specific-frameworks) - -### [Serverless Framework](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#serverless-framework) - -If you're using [Serverless framework](https://www.serverless.com/), note that this integration will configure your existing Lambda functions correctly to use the SDK layer and set the appropriate environment variables. Learn more about it [here](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/). - -You can confirm that the output works by inputting `aws lambda get-function-configuration --function-name <yourFunctionName>`. However, when you perform a subsequent `sls deploy` the environment variables aren't maintained even though it looks like the reference to the layer is retained. - -You can set the layer definition and environment variables in `serverless.yml` as a workaround, but you'll have to do two things manually: maintain the latest layer version and add the reference to the SDK layer for every function you want "Sentrified". - -**Serverless Framework Using Node:** - -YAML - -`serverless.yml` - -```yaml code-highlight -# other configuration - -provider: - # more configuration - region: <AWS_REGION> - environment: - SENTRY_TRACES_SAMPLE_RATE: "1.0" - SENTRY_DSN: "<SENTRY_DSN>" - NODE_OPTIONS: "-r @sentry/aws-serverless/dist/awslambda-auto" - -custom: - layers: - - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryNodeServerlessSDK:26 -# - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryNodeServerlessSDK:latest - -functions: - <yourFunctionName>: - handler: <yourLambdaHandlerFunctionPath> - layers: ${self:custom.layers} - -``` - -**Serverless Framework Using Python:** - -YAML - -`serverless.yml` - -```yaml code-highlight -# other configuration - -provider: - # more configuration - region: <AWS_REGION> - environment: - SENTRY_TRACES_SAMPLE_RATE: "1.0" - SENTRY_DSN: "<SENTRY_DSN>" - -custom: - layers: - - arn:aws:lambda:${self:provider.region}:943013980633:layer:SentryPythonServerlessSDK:6 -# - arn:aws:lambda:${self:provider.region:943013980633:layer:SentryPythonServerlessSDK:latest - -functions: - <yourFunctionName>: - handler: sentry_sdk.integrations.init_serverless_sdk.sentry_lambda_handler - environment: - SENTRY_INITIAL_HANDLER: "<yourLambdaHandlerFunctionPath>" - layers: ${self:custom.layers} - -``` - -Currently, there's no way of using the [latest layer plugin](https://www.npmjs.com/package/serverless-latest-layer-version) since the `lambda:ListLayerVersions on resource: arn:aws:lambda:eu-west-1:943013980633:layer:SentryNodeServerlessSDK` hasn't been given the necessary permissions. - -### [SST](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/\#sst) - -If you use Node functions in [SST](https://serverless-stack.com/) and you want to use this integration, you'll need to: - -1. Import the [Lambda layer](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/layer/) using the [`LayerVersion`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-lambda.LayerVersion.html) construct and set it by calling [`addDefaultFunctionLayers`](https://docs.serverless-stack.com/constructs/Stack#adddefaultfunctionlayers). -2. Then set the `NODE_OPTIONS`, `SENTRY_DSN`, and `SENTRY_TRACES_SAMPLE_RATE` environment variables with the [`addDefaultFunctionEnv`](https://docs.serverless-stack.com/constructs/Stack#adddefaultfunctionenv) method. - -Read [how this integration works](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/) and [the SST docs](https://docs.serverless-stack.com/monitoring-your-app-in-prod#sentry) for more information. - -[Previous\\ -\\ -Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring) - -[Next\\ -\\ -Lambda Layer Modifications](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/aws-lambda/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [User Feedback Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/) - -# User Feedback Properties - -## Learn more about searchable user feedback properties. - -[User Feedback](https://docs.sentry.io/product/user-feedback/) allows your users to create bug reports so they can let you know about sneaky issues right away. Every report will automatically include related replays, tags, and errors, making fixing the issue dead simple. - -You can search by user feedback properties on the **User Feedback** page. - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the user feedback search. - -### [`assigned`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#assigned) - -Returns user feedback submissions assigned to the defined user(s) or team(s). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee, `my_teams` or `#team-name` for teams you belong to. - -- **Type:** team or org user - -### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#browsername) - -Name of the browser. - -- **Type:** string - -### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicebrand) - -Brand of the device. - -- **Type:** string - -### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicefamily) - -Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. - -- **Type:** string - -### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicemodel_id) - -Internal hardware revision to identify the device exactly. - -- **Type:** n/a - -### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#devicename) - -Name of the device. - -- **Type:** string - -### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#dist) - -Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. - -- **Type:** string - -### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#environment) - -The environment that the event was first seen in. - -- **Type:** string - -### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#id) - -The feedback ID. - -- **Type:** UUID - -### [`is`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#is) - -The properties of a user feedback submission. Values can be: `unresolved`, `resolved`, `assigned`, `unassigned`, `linked`, or `unlinked`. The `linked` and `unlinked` values return user feedback submissions based on whether they are linked to an external issue tracker or not. - -- **Type:** status - -### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#level) - -The severity of the user feedback submissions. If the feedback came in through the crash-report modal then the level is tied to the error experienced by the end-user. For feedback from the user feedback widget, the level is `info`. - -- **Type:** string - -### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#osname) - -The name of the operating system. - -- **Type:** string - -### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#sdkname) - -Name of the Sentry SDK that sent the event. - -- **Type:** string - -### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#sdkversion) - -Version of the Sentry SDK that sent the event. - -- **Type:** string - -### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#timestamp) - -The finish timestamp of the transaction. Returns events with matching datetime. - -- **Type:** datetime - -### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#transaction) - -The error or transaction name identifier. - -- **Type:** string - -### [`url`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#url) - -The URL of the page that the feedback is triggered on. - -- **Type:** string - -### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#useremail) - -The user's email address exists only if Sentry received it from the `Sentry.setUser` SDK option as a tag. This property does not apply to emails entered inside the user feedback widget, which are not searchable. - -- **Type:** string - -### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userid) - -Application-specific internal identifier for the user. - -- **Type:** string - -### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userip) - -User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. - -- **Type:** string - -### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/user-feedback/\#userusername) - -Username, which is typically a better label than the `user.id`. - -- **Type:** string - -[Previous\\ -\\ -Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay) - -[Next\\ -\\ -Release Properties](https://docs.sentry.io/concepts/search/searchable-properties/releases) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/user-feedback.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Configuration and Authentication](https://docs.sentry.io/cli/configuration/) - -# Configuration and Authentication - -## Learn about the functionality of Sentry's command line interface and how you can install, configure, authenticate, set up release management, debug information files, and send events. - -For most functionality you need to authenticate with Sentry. Setting this up can be done either automatically, using `sentry-cli`, or manually via [Organization Auth Tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/). - -## [To use the automatic option:](https://docs.sentry.io/cli/configuration/\#to-use-the-automatic-option) - -Bash - -`` - -```bash code-highlight -sentry-cli login - -``` - -This will give you the option to visit your auth token user settings, where you can create a new auth token, or simply copy an existing one. When you return to the CLI, you'll paste in your token and it will get added to `~/.sentryclirc` automatically. - -By default, `sentry-cli` will connect to sentry.io, but for self-hosted you can also sign in elsewhere: - -Bash - -`` - -```bash code-highlight -sentry-cli --url https://myserver.invalid/ login - -``` - -## [To Authenticate Manually:](https://docs.sentry.io/cli/configuration/\#to-authenticate-manually) - -You can manually create an [Organization Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) and pass it to sentry-cli. - -You can also sign in to your Sentry account (if you're not already) and create an Auth Token directly from this page. - -Some CLI functionality, such as [Crons Monitoring](https://docs.sentry.io/product/crons/getting-started/cli/), is dependent on DSN authentication. - -You can create an Auth Token from this page in one of the following three ways: - -- add it to `~/.sentryclirc`: - - - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). - -Ini - -`` - -```code-highlight ini -[auth] -token=sntrys_YOUR_TOKEN_HERE - -``` - -- export it as an environment variable: - - - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). - -Bash - -`` - -```bash code-highlight -export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE - -``` - -- pass it as a parameter when you invoke `sentry-cli`: - - - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/configuration/). - -Bash - -`` - -```bash code-highlight -$ sentry-cli login --auth-token sntrys_YOUR_TOKEN_HERE - -``` - - -## [Configuration File](https://docs.sentry.io/cli/configuration/\#configuration-file) - -The `sentry-cli` tool can be configured with a config file named `.sentryclirc` as well as environment variables and `.env` files. The config file is looked for upwards from the current path and defaults from `~/.sentryclirc` are always loaded. You can also override these settings from command line parameters. - -The config file uses standard INI syntax. - -By default `sentry-cli` will connect to sentry.io. For on-prem you can export the `SENTRY_URL` environment variable and point it to your installation: - -Bash - -`` - -```bash code-highlight -export SENTRY_URL=https://mysentry.invalid/ - -``` - -Alternatively you can add it to your `~/.sentryclirc` config. This is also what the `login` command does: - -Ini - -`` - -```code-highlight ini -[defaults] -url = https://mysentry.invalid/ - -``` - -## [Configuration Values](https://docs.sentry.io/cli/configuration/\#configuration-values) - -The following settings are available (first is the environment variable, the value in the parentheses is the config key in the config file): - -`SENTRY_AUTH_TOKEN` ( _auth.token_): - -The authentication token to use for all communication with Sentry. - -`SENTRY_API_KEY` ( _auth.api\_key_): - -The legacy API key for authentication if you have one. - -`SENTRY_DSN` ( _auth.dsn_): - -The DSN to use to connect to Sentry. - -`SENTRY_URL` ( _defaults.url_): - -The URL to use to connect to Sentry. This defaults to `https://sentry.io/`. - -`SENTRY_ORG` ( _defaults.org_): - -The ID or slug of the organization to use for a command. - -`SENTRY_PROJECT` ( _defaults.project_): - -The ID or slug of the project to use for a command. - -`SENTRY_VCS_REMOTE` ( _defaults.vcs\_remote_): - -The name of the _remote_ in the versioning control system. This defaults to `origin`. - -`SENTRY_PIPELINE` ( _defaults.pipeline_): - -The name of the environment to be appended to `User-Agent` header. - -`CUSTOM_HEADER` ( _defaults.custom\_header_): - -The header that will be added to every outgoing request in `key:value` format. - -`SENTRY_ALLOW_FAILURE` - -Note: This option will ignore the CLI's failure when uploading symbols. **BE AWARE** this will unblock your CI in case Sentry has issues, but you won't have unminified/unsymbolicated crashes in production. When using this flag, you should download your sourcemaps/debug files from CI, to re-run the upload symbols command at a later point once Sentry is available. - -( _http.keepalive_): - -This ini only setting is used to control the behavior of the SDK with regards to HTTP keepalives. The default is _true_ but it can be set to _false_ to disable keepalive support. - -`http_proxy` ( _http.proxy\_url_): - -The URL that should be used for the HTTP proxy. The standard `http_proxy` environment variable is also honored. Note that it is lowercase. - -( _http.proxy\_username_): - -This ini only setting sets the proxy username in case proxy authentication is required. - -( _http.proxy\_password_): - -This ini only setting sets the proxy password in case proxy authentication is required. - -( _http.verify\_ssl_): - -This can be used to disable SSL verification when set to false. You should never do that unless you are working with a known self signed server locally. - -( _http.check\_ssl\_revoke_): - -If this is set to false then SSL revocation checks are disabled on Windows. This can be useful when working with a corporate SSL MITM proxy that does not properly implement revocation checks. Do not use this unless absolutely necessary. - -`SENTRY_HTTP_MAX_RETRIES` ( _http.max\_retries_): - -Sets the maximum number of retry attempts for upload operations (e.g., uploads of release files and debug symbols). The default is `5`. - -( _ui.show\_notifications_): - -If this is set to false some operating system notifications are disabled. This currently primarily affects xcode builds which will not show notifications for background builds. - -`SENTRY_LOG_LEVEL` ( _log.level_): - -Configures the log level for the SDK. The default is `warn`. If you want to see what the library is doing you can set it to `info` which will spit out more information which might help to debug some issues with permissions. Possible values are `trace`, `debug`, `info`, `warn`, and `error`. - -( _dif.max\_upload\_size_): - -Sets the maximum upload size in bytes (before compression) of debug symbols into one batch. The default is 35MB or 100MB (depending on the version of sentry-cli) which is suitable for sentry.io but if you are using a different Sentry server you might want to change this limit if necessary. (Prior to version 1.72.0, this option was called `dsym.max_upload_size`.) - -( _dif.max\_item\_size_): - -Sets the maximum file size of a single file inside DIF bundle. The default is 1MB. - -`SENTRY_DISABLE_UPDATE_CHECK` ( _update.disable\_check_): - -If set to `true`, then the automatic update check in sentry-cli is disabled. The update check is also not enabled for npm based installations of sentry-cli at the moment. - -`SENTRY_NO_PROGRESS_BAR`: - -If set to `1`, then `sentry-cli` will not display progress bars for any operations. - -`SENTRY_LOAD_DOTENV`: - -Set to `0` to prevent sentry-cli from loading an `.env` file. - -`SENTRY_DOTENV_PATH`: - -Specify a path to `.env` file to be loaded during setup. This was introduced in version 1.70. - -`DEVICE_FAMILY` ( _device.family_): - -Device family value reported to Sentry. - -`DEVICE_MODEL` ( _device.model_): - -Device model value reported to Sentry. - -## [Validating The Config](https://docs.sentry.io/cli/configuration/\#validating-the-config) - -To make sure everything works you can run `sentry-cli info` and it should print out some basic information about the Sentry installation you connect to as well as some authentication information. - -## [Working with Projects](https://docs.sentry.io/cli/configuration/\#working-with-projects) - -Many commands require you to specify the organization and project to work with. There are multiple ways in which you can specify this. - -### [Config Defaults](https://docs.sentry.io/cli/configuration/\#config-defaults) - -If you are always working with the same projects you can set it in the `.sentryclirc` file: - -Ini - -`` - -```code-highlight ini -[defaults] -project=my-project -org=my-org - -``` - -### [Environment Variables](https://docs.sentry.io/cli/configuration/\#environment-variables) - -You can also set these defaults in environment variables. There are two environment variables that control this ( `SENTRY_ORG` and `SENTRY_PROJECT`) which you can export: - -Bash - -`` - -```bash code-highlight -export SENTRY_ORG=my-org -export SENTRY_PROJECT=my-project - -``` - -### [Properties Files](https://docs.sentry.io/cli/configuration/\#properties-files) - -Additionally `sentry-cli` supports loading configuration values from `.properties` files (common in the Java environment). You can instruct `sentry-cli` to load config files from there by exporting the path to a properties file in the `SENTRY_PROPERTIES` environment variable. This is commonly done automatically for some of our client integrations like Java and React Native. - -Inside the properties files you just use the dotted notation to set values. Example: - -Ini - -`` - -```code-highlight ini -defaults.url=https://mysentry.invalid/ - -``` - -To then instruct `sentry-cli` to use that file use this: - -Bash - -`` - -```bash code-highlight -export SENTRY_PROPERTIES=/path/to/sentry.properties -sentry-cli ... - -``` - -### [Explicit Options](https://docs.sentry.io/cli/configuration/\#explicit-options) - -Lastly you can also provide these values explicitly to the command you are executing. The parameters are always called `--org` or `-o` for the organization and `--project` or `-p` for the project. - -Note that they do not always go to the same command. For instance if you are managing releases (which are shared across the organization) you usually supply the organization to the `releases` command but the projects to the subcommand on it: - -Bash - -`` - -```bash code-highlight -sentry-cli releases -o my-org new -p my-project 1.0 - -``` - -For more information use the `help` command which will display documentation for all parameters. - -[Previous\\ -\\ -Installation](https://docs.sentry.io/cli/installation) - -[Next\\ -\\ -Release Management](https://docs.sentry.io/cli/releases) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/configuration.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) -- [Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons/) - -# Platform Icons - -To have consistent icons for all supported platforms across all of Sentry (the product, the docs, landing pages, etc.) we created a repo for managing those icons, called [platformicons](https://github.com/getsentry/platformicons). - -If a new platform is added, follow these steps to add a new icon that can be used in the docs: - -1. **Add the new icon to `platformicons`:** - -Create a [new issue in the platformicons repository](https://github.com/getsentry/platformicons/issues) that specifies how the icon should be named and includes a link to the platform's website. Also, make sure to specify whether it is a top-level icon (like `python`) or a subitem that is only available in one specific platform (like `python.celery`). - -You can also create a PR in the `platformicons` repository where you add two versions of the icon. See the [README](https://github.com/getsentry/platformicons) for more info on formatting.\`\`\` - -2. **Release a new version of `platformicons` to NPM.** - -If you are a Sentry employee, follow the [README.md](https://github.com/getsentry/platformicons) on how to do a release. - -If you are not a Sentry employee, ask on our [Discord server](https://discord.com/invite/Ww9hbqr) so someone can review your contribution and trigger the release. - -3. **Update the `platformicons` version used in the docs repository.** - -Update the version of your newly released `platformicons` in `package.json` and run `yarn install` to also have the new version in `yarn.lock`. - -4. **Make it available as a component in the docs repository.** - -Update [platformIcon.tsx](https://github.com/getsentry/sentry-docs/blob/master/src/components/platformIcon.tsx) to include your new icon. Make sure to: - - - Add two imports (one for each version of the icon). - - Add the icons to `formatToSVG`. - - Add a mapping for the platform and icon to `PLATFORM_TO_ICON`. - -Now the new icon is available in the docs and will be used wherever icons are rendered! - -[Previous\\ -\\ -Platforms & Guides](https://docs.sentry.io/contributing/platforms) - -[Next\\ -\\ -Versioning](https://docs.sentry.io/contributing/platforms/versioning) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/platform-icons/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)Edit this banner on \`/src/components/banner/index.tsx\` [CTA](https://docs.sentry.io/contributing/pages/banners/) - -× - -- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Banners](https://docs.sentry.io/contributing/pages/banners/) - -# Banners - -You can add arbitrary banners to the top of a page by adding adding an entry to the `BANNERS` array on the `banner/index.tsx` file. The `BANNERS` array is an array of objects with the following properties: - -TypeScript - -`banner/index.tsx` - -```typescript code-highlight -type BannerType = { - /** This is an array of strings or RegExps to feed into new RegExp() */ - appearsOn: (string | RegExp)[]; - /** The label for the call to action button */ - linkText: string; - /** The destination url of the call to action button */ - linkURL: string; - /** The main text of the banner */ - text: string; - /** Optional ISO Date string that will hide the banner after this date without the need for a rebuild */ - expiresOn?: string; -}; - -``` - -You can add as many banners as you like. If you need to disable all banners, simply delete them from the array. - -Each banner is evaluated in order, and the first one that matches will be shown. - -Examples: - -TypeScript - -`banner/index.tsx` - -```typescript code-highlight -// ... -// appearsOn = []; // This is disabled -// appearsOn = ['^/$']; // This is enabled on the home page -// appearsOn = ['^/welcome/']; // This is enabled on the "/welcome" page -// ... - -const BANNERS = [\ - // This one will take precedence over the last banner in the array\ - // (which matches all /platforms pages), because it matches first.\ - {\ - appearsOn: ["^/platforms/javascript/guides/astro/"],\ - text: "This banner appears on the Astro guide",\ - linkURL: "https://sentry.io/thought-leadership",\ - linkText: "Get webinarly",\ - },\ -\ - // This one will match the /welcome page and all /for pages\ - {\ - appearsOn: ["^/$", "^/platforms/"],\ - text: "This banner appears on the home page and all /platforms pages",\ - linkURL: "https://sentry.io/thought-leadership",\ - linkText: "Get webinarly",\ - },\ -]; - -``` - -Optionally, you can add an `expiresOn` property to a banner to hide it after a certain date without requiring a rebuild or manual removeal. the ISO Date string should be in the format `YYYY-MM-DDTHH:MM:SSZ` to be parsed correctly and account for timezones. - -TypeScript - -`banner/index.tsx` - -```typescript code-highlight -const BANNERS = [\ - {\ - appearsOn: ["^/$"],\ - text: "This home page banner will disappear after 2024-12-06",\ - linkURL: "https://sentry.io/party",\ - linkText: "RSVP",\ - expiresOn: "2024-12-06T00:00:00Z",\ - },\ -]; - -``` - -[Previous\\ -\\ -Search](https://docs.sentry.io/contributing/pages/search) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/banners.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Compliance](https://docs.sentry.io/organization/integrations/compliance/) -- [Truto](https://docs.sentry.io/organization/integrations/compliance/truto/) - -# Truto - -## Learn about Sentry's Truto integration. - -This integration is maintained and supported by the company that created it. For more details, or questions, feel free to contact [support@truto.one](mailto:support@truto.one). - -## [Install and Configure](https://docs.sentry.io/organization/integrations/compliance/truto/\#install-and-configure) - -Sentry Owner, Manager, or Admin permissions are required to install this integration. - -1. Navigate to **Settings > Integrations > Truto** - -2. Follow the full [Truto installation instructions](https://truto.one/docs/integration-guides/sentry#sentry). - - -[Previous\\ -\\ -Compliance](https://docs.sentry.io/organization/integrations/compliance) - -[Next\\ -\\ -Vanta](https://docs.sentry.io/organization/integrations/compliance/vanta) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/compliance/truto/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) - -# Data Forwarding - -## Learn about forwarding processed events to third-party providers. - -This feature is available only if your organization is on [a Trial, Business, or Enterprise plan](https://sentry.io/pricing/). - -Sentry provides the ability to forward processed error events to certain third-party providers, such as [Segment](https://segment.com/) and [Amazon SQS](https://aws.amazon.com/sqs/). - -This is often useful when you may want to analyze exceptions more deeply, or empower other teams, such as a Business Intelligence function. - -Configure Data Forwarding by navigating to your **\[Project\] » Settings » Data Forwarding**, then providing the required information for the given integration. - -Only error events will be forwarded. Forwarding of transaction events is not supported. - -## [Amazon SQS](https://docs.sentry.io/concepts/data-management/data-forwarding/\#amazon-sqs) - -Integration with Amazon SQS makes it quick and easy to pipe exceptions back into your own systems. - -The payload for Amazon is identical to our standard API event payload, and will evolve over time. For more details on the format of this data, see our [API documentation](https://docs.sentry.io/api/events/retrieve-an-event-for-a-project/). - -## [Segment](https://docs.sentry.io/concepts/data-management/data-forwarding/\#segment) - -The Segment integration will generate _Error Captured_ events within your data pipeline. These events will **only** be captured for `error` events, and only when an ID is present the user context. The general shape of the event will look roughly similar to: - -JSON - -`` - -```json code-highlight -{ - "userId": "1", - "event": "Error Captured", - "properties": { - "environment": "production", - "eventId": "002c8bbde8324dae9f12a0b96f5b1e51", - "exceptionType": "ValueError", - "release": "a2def1", - "transaction": "/api/0/users/{user}/", - "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:54.0) Gecko/20100101 Firefox/54.0", - "page": { - "url": "https://sentry.io/api/0/users/{user}/", - "method": "GET", - "search": "", - "referer": "https://sentry.io/" - } - }, - "timestamp": "2017-05-20T15:29:06Z" -} - -``` - -## [Splunk](https://docs.sentry.io/concepts/data-management/data-forwarding/\#splunk) - -For details on the Splunk integration, visit the dedicated [Splunk integration documentation](https://docs.sentry.io/organization/integrations/data-visualization/splunk/). - -[Previous\\ -\\ -Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) - -[Next\\ -\\ -Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/data-forwarding.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Usage](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/) - -# How to Write - Usage - -The Usage section of the content covers how to manually capture events and message. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/usage` \- feel free to peruse the files in that directory to help answer questions. - -Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. - -Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions, if any arise, by opening an issue on GitHub. - -### [Index file](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/\#index-file) - -This file is `index.mdx`. It explains how to manually capture events. - -Add the code sample to these directories: - -- `/src/platform-includes/capture-error/` -- `/src/platform-includes/capture-message/` - -### [Set the Level](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage/\#set-the-level) - -This file is `set-level.mdx`. It explains how to set the level of the event. Add the code sample to this directory: - -- `/src/platform-includes/set-level/` - -[Previous\\ -\\ -How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance) - -[Next\\ -\\ -Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-usage.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Platforms & Guides](https://docs.sentry.io/contributing/platforms/) -- [Versioning](https://docs.sentry.io/contributing/platforms/versioning/) - -# Versioning - -Versioning allows for the maintenance of multiple versions of the same documentation, which is crucial for supporting different SDK releases. This guide explains how to create versioned documentation in the docs platform. - -## [Creating a Versioned Page](https://docs.sentry.io/contributing/platforms/versioning/\#creating-a-versioned-page) - -To create a versioned page: - -1. Ensure the original page already exists. -2. Create a new file with the same name as the original, but append `__v{VERSION}` (two underscores) to the filename before the extension. - -**The version should follow one of these two formats:** - -- Major version only (for general version ranges): `__v{MAJOR}.x` -- Full semantic version (for specific versions): `__v{MAJOR}.{MINOR}.{PATCH}` - -For example: - -Bash - -`` - -```bash code-highlight -index.mdx (original) -index__v7.x.mdx (version 7.x.x) -index__v7.1.0.mdx (specific version 7.1.0) - -``` - -## [Versioning Platform Includes](https://docs.sentry.io/contributing/platforms/versioning/\#versioning-platform-includes) - -Pages in the `platform-includes` folder can be versioned using the same method. However, the root page referencing these includes must also be versioned. - -## [File Structure Example](https://docs.sentry.io/contributing/platforms/versioning/\#file-structure-example) - -Bash - -`` - -```bash code-highlight -docs/ -├── getting-started/ -│ ├── index.mdx -│ └── index__v7.x.mdx -└── platform-includes/ - └── configuration/ - ├── example.mdx - └── example__v7.x.mdx - -``` - -## [Version Selection and User Experience](https://docs.sentry.io/contributing/platforms/versioning/\#version-selection-and-user-experience) - -When multiple versions of a page exist: - -1. A dropdown menu appears below the platform selector, displaying all available versions for the current file. - -2. When a user selects a version: - - -- They are redirected to the chosen version of the page. -- A preference is stored in localStorage, specific to the current guide or platform. - -3. An alert is displayed when viewing "non-latest" pages to inform users they're not on the most recent version. - -4. If a user has a stored version preference: - - -- The app will perform a client-side redirect to this version whenever it's available for other pages. - -This approach ensures users can easily navigate between versions and keep their version preference across the documentation. - -## [Best Practices](https://docs.sentry.io/contributing/platforms/versioning/\#best-practices) - -1. Only add versioning to pages when necessary, to avoid content duplication and save build times. -2. Ensure all related content (including `platform-includes`) is versioned consistently. - -## [Limitations and Considerations](https://docs.sentry.io/contributing/platforms/versioning/\#limitations-and-considerations) - -- Versioning is only available for existing pages. -- The versioning system relies on the file naming convention, so it's important to follow the `__v{VERSION}` format precisely. - -By following these guidelines, it's possible to effectively manage multiple versions of documentation, ensuring users can access the appropriate information for their specific version of the software or API. - -[Previous\\ -\\ -Platform Icons](https://docs.sentry.io/contributing/platforms/platform-icons) - -[Next\\ -\\ -Linking Variables](https://docs.sentry.io/contributing/linking) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/platforms/versioning.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) -- [Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso/) - -# Ping Identity SSO - -## Set up Ping Identity Single Sign-On (SSO) on Sentry. - -## [Installation](https://docs.sentry.io/organization/authentication/sso/ping-sso/\#installation) - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. - -01. Log in to [Ping Identity](https://www.pingidentity.com/en/account/sign-on.html). - -02. Go to the "Adminstrators" environment for your organization. - -03. If you don't require a permission group for Sentry, skip to step 5. - -04. In the sidebar, click on "Identities", then "Groups", and navigate to it. From there, create a new group and add yourself and other members to it. For more details about group creation, see the [Ping ID docs](https://docs.pingidentity.com/bundle/pingone/page/vdz1610472224361.html). - -05. In the sidebar, click on "Connections", then "Applications". Click on "+ Application" and for the application type, select "Web App" and "SAML". - - [![Create web application for Ping](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fping-new-app-VKZCD57R.png%233584x1702&w=3840&q=75)](https://docs.sentry.io/mdx-images/ping-new-app-VKZCD57R.png) - -06. For section (1), labeled "Create App Profile", you can get the Sentry logo from [here](https://sentry.io/branding/). - -07. For section (2), labeled "Configure SAML", select "Manually Enter". Enter the following data in each line and save your changes. - - - Assertion Consumer Service (ACS) URL: `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` - - - Entity ID: `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` - - - Single-Logout (SLO) Endpoint: `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` - - - Target Application URL: `https://sentry.io/organizations/YOUR_ORG_SLUG/` -08. In section (3), labeled "Attribute Mappings", for "Application Attribute" ← "Outgoing Value", use: - - - `saml_subject` ← `Email address` - - - `email` ← `Email address` - - - `first_name` ← `Given Name` - - - `last_name` ← `Family Name` - - You can use custom key values, but you will need to amend the steps below. For more details about advanced attribute mappings for custom configs, see [this guide from Ping ID](https://support.pingidentity.com/s/article/PingOne-Using-Advanced-Attribute-Mapping). -09. Once the application is created, click on the Sentry application and navigate to "Configuration" and copy "IDP Metadata URL". This URL will be used in the subsequent step on Sentry. - - [![Ping configuration for Sentry](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fping-configure-sentry-INWYPDRP.png%233584x1442&w=3840&q=75)](https://docs.sentry.io/mdx-images/ping-configure-sentry-INWYPDRP.png) - -10. Go back to [Sentry](https://sentry.io/). Navigate to **Settings > Auth** (or go to `https://sentry.io/settings/YOUR_ORG_SLUG/auth/`) and click on "Configure" for SAML2. - -11. Paste the IDP Metadata URL from above and click "Get Metadata". - -12. On the next page, enter the following keys in their respective fields to map the Ping ID attributes to Sentry, and then save them: - - - IdP User ID: `saml_subject` - - - User Email: `email` - - - First Name: `first_name` - - - Last Name: `last_name` -13. Sentry will attempt to authenticate and link your account with Ping Identity. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can take the following actions: - - - You can share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. - - - Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Ping. - - - Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. - - - If you made changes, click "Save Settings" to complete your setup. - -[Previous\\ -\\ -Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) - -[Next\\ -\\ -Custom SAML Provider](https://docs.sentry.io/organization/authentication/sso/saml2) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/ping-sso.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) - -# Single Sign-On (SSO) - -## Learn about single sign-on (SSO) and how it helps manage your organization. - -Single sign-on (or SSO) allows you to manage your organization’s entire membership via a third-party provider. - -## [Preface](https://docs.sentry.io/organization/authentication/sso/\#preface) - -Before you get around to actually turning on SSO, you’ll want to keep in mind that once it’s activated, all existing users will need to link their account before they are able to continue using Sentry. Because of that we recommend coordinating with your team during off-peak hours. That said, it’s super quick to link accounts, so we don’t consider it a true hurdle. - -## [Getting Started](https://docs.sentry.io/organization/authentication/sso/\#getting-started) - -With that out of the way, head on over to your organization home. You’ll see an “Auth” link in the sidebar if you have access to SSO. Start by hitting that, and then continue to the “Configure” link next to provider you wish to configure. - -Additionally we’ll automatically send each pre-existing member an email with instructions on linking their account. This will happen automatically once SSO is successfully configured. Even if they don't click the link, the next time they try to hit any page within the organization we’ll require them to link their account (with the same auth flow you just went through). - -## [Default Membership](https://docs.sentry.io/organization/authentication/sso/\#default-membership) - -Every member who creates a new account via SSO will be given global organization access with a member role. This means that they can access events from any team, but they won’t be able to create new projects or administer current ones. - -## [Security](https://docs.sentry.io/organization/authentication/sso/\#security) - -Our SSO implementation prioritizes security. We aggressively monitor linked accounts and will disable them if there's any reasonable sign that the account’s access may have been revoked. Generally this will be transparent to you, but if the provider is functioning in an unexpected way you may experience more frequent re-authorization requests. - -Sessions last for [Django's default session length](https://docs.djangoproject.com/en/1.11/topics/http/sessions/#using-cookie-based-sessions), which is two weeks. For individual organizations with single sign-on, we expire organization access after one day (20 hours). - -## [Providers](https://docs.sentry.io/organization/authentication/sso/\#providers) - -### [Google Business App](https://docs.sentry.io/organization/authentication/sso/\#google-business-app) - -This feature is available only if your organization is on [a Trial, Team, or higher plan](https://sentry.io/pricing/). - -Enabling the Google integration will ask you to authenticate against a Google Apps account. Once done, membership will be restricted to only members of the given Apps domain (i.e. `sentry.io`). - -If you need to allow users across multiple domains to access your organization or change your Google domain, please contact our support team. - -### [GitHub Organizations](https://docs.sentry.io/organization/authentication/sso/\#github-organizations) - -This feature is available only if your organization is on [a Trial, Team, or higher plan](https://sentry.io/pricing/). - -The GitHub integration will authenticate against all organizations, and once complete prompt you for the organization which you wish to restrict access by. - -### [SAML2 Identity Providers](https://docs.sentry.io/organization/authentication/sso/\#saml2-identity-providers) - -This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. - -Sentry provides [SAML2 based authentication](https://en.wikipedia.org/wiki/SAML_2.0) which may be configured manually using the generic SAML2 provider, or a specific provider listed below that provides defaults specific to that identity provider: - -- [AuthO](https://docs.sentry.io/organization/authentication/sso/#auth0) -- [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/#azure-active-directory) -- [Okta](https://docs.sentry.io/organization/authentication/sso/#okta) -- [OneLogin](https://docs.sentry.io/organization/authentication/sso/#onelogin) -- [Rippling](https://docs.sentry.io/organization/authentication/sso/#rippling) -- [Jumpcloud](https://docs.sentry.io/organization/authentication/sso/#jumpcloud) - -Sentry supports the following SAML services: - -- Identity and Service Provider initiated SSO -- Identity Provider initiated SLO (Single Logout) - -Sentry’s Assertion Consumer Service uses the HTTP-POST bindings. - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SSO/SAML configuration values. - -Sentry’s SAML endpoints are as follows, where the `[organization_slug]` is substituted for your organization slug: - -| ACS: | `https://sentry.io/saml/acs/[organization_slug]/` | -| SLS: | `https://sentry.io/saml/sls/[organization_slug]/` | -| Metadata: | `https://sentry.io/saml/metadata/[organization_slug]/` | - -#### [Auth0](https://docs.sentry.io/organization/authentication/sso/\#auth0) - -In your Auth0 dashboard, locate the Sentry app under the SSO Integrations page and add it to your organization. - -As part of the Auth0 SSO configuration, you must provide the Auth0 Identity Provider metadata to Sentry. This URL is available under the Tutorial tab of the Sentry SSO integration. - -You may refer to the [Auth0 documentation](https://auth0.com/docs/integrations/sso/sentry) for more detailed setup instructions. - -#### [Azure Active Directory](https://docs.sentry.io/organization/authentication/sso/\#azure-active-directory) - -In your Azure AD dashboard, locate the Sentry app under Enterprise Applications and add it to your organization. - -You may refer to [our documentation](https://docs.sentry.io/organization/authentication/sso/azure-sso/) for more detailed setup instructions. - -#### [Okta](https://docs.sentry.io/organization/authentication/sso/\#okta) - -In your Okta admin dashboard, locate the Sentry app in the Okta Application Network and add it to your organization. - -As part of the Okta SSO configuration, you must provide the Okta Identity Provider metadata to Sentry. This URL can be located under the Sign-On Methods SAML2 settings panel, look for the ‘Identity Provider metadata’ link which can may right click and copy link address. - -You may refer to [our documentation](https://docs.sentry.io/organization/authentication/sso/okta-sso/) for more detailed setup instructions. - -#### [OneLogin](https://docs.sentry.io/organization/authentication/sso/\#onelogin) - -In your OneLogin dashboard, locate the Sentry app in the app catalog and add it to your organization. - -As part of OneLogin SSO configuration, you must to provide the OneLogin identity provider issuer URL to Sentry. This URL is specific to your OneLogin account and can be found under the "SSO" tab on the Sentry OneLogin application configuration page. - -You may refer to the [OneLogin documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=1d199dcfdbdc5700d5505eea4b96196a) for more detailed setup instructions. - -#### [Rippling](https://docs.sentry.io/organization/authentication/sso/\#rippling) - -In your Rippling admin dashboard, locate the Sentry app in the list of suggested apps and select it. - -When prompted with the Rippling Metadata URL, copy this into the Sentry Rippling provider configuration. You will have to complete the Rippling application configuration before completing the Sentry provider configuration. - -#### [Jumpcloud](https://docs.sentry.io/organization/authentication/sso/\#jumpcloud) - -In your Jumploud Admin portal: - -1. Navigate to **User Authentication > SSO**. -2. Add a new SSO application and search for Sentry. -3. Click "Configure". -4. Under the SSO menu, update the SP Entity ID and ACS URLs for your tenant. They should be in the format as described [here](https://docs.sentry.io/organization/authentication/sso/saml2/#register-sentry-with-idp). -5. Click "save". - -Be sure that you have assigned yourself to the Sentry app in Jumpcloud before attempting these next steps. - -1. In [sentry.io](https://sentry.io/), navigate to **Settings > Auth** in your organization. -2. Click "Configure" on the Jumpcloud provider. -3. Go to the "XML" within the register page. -4. Download your Jumpcloud metadata under the "SSO" tab in your Jumpcloud Sentry SSO app by clicking "Export Metadata". -5. Paste your XML metadata into the text field and click "Parse Metadata". -6. On the "Map Identity Provider" page, fill in 'uniqueID', 'email', 'firstname', and 'lastname' if you have left your Jumpcloud attributes as the defaults for the Sentry app. - -Now, Sentry should be configured for Jumpcloud SSO. - -#### [Custom SAML2 Integration](https://docs.sentry.io/organization/authentication/sso/\#custom-saml2-integration) - -For other SAML2 SSO providers not listed above, Sentry provides generic connectors for [SAML2 based authentication](https://docs.sentry.io/organization/authentication/sso/saml2/), which may be configured manually. - -## [SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/\#scim-provisioning) - -This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. - -If you change your organization slug, you'll need to make the same update in places where you enter the configuration values when setting up SCIM. - -System for Cross-Domain Identity Management ( [SCIM](http://www.simplecloud.info/)) is a standard implemented by Identity Providers and applications to facilitate automated identity management. Sentry supports a subset of the specification for provisioning organization members and teams. See the relevant documentation for your use case: - -- [Okta SCIM Setup](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) -- [Azure AD SCIM Setup](https://docs.sentry.io/organization/authentication/sso/azure-sso/#scim-integration) -- If your Provider is not listed here, SCIM may be supported as it is a common standard. If you are having issues please contact our support team. - -[Previous\\ -\\ -Authentication](https://docs.sentry.io/organization/authentication) - -[Next\\ -\\ -Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Images](https://docs.sentry.io/contributing/pages/images/) - -# Images - -If you want to add images to your docs, you can add them in a `./img` folder in the same directory as your `.mdx` files. You don't have to follow a rigid folder structure as long as the relative path (starts with `./`) to the image is correct. See [local images](https://docs.sentry.io/contributing/pages/images/#local-images). - -If an image is used in multiple places, it's best to put it in `includes/common-imgs/imgs` and reference it in a local [`include` file](https://docs.sentry.io/contributing/approach/product-docs/write-index/#includes) to be used in the target `mdx` file. See [common images](https://docs.sentry.io/contributing/pages/images/#common-images). - -Alternatively, images can also be added to the `public` folder and referenced using their relative or full path within the folder. See [public images](https://docs.sentry.io/contributing/pages/images/#public-images) - -Every image path that starts with `/` (instead of `./`) is considered to be in the `public` folder. - -### [Examples](https://docs.sentry.io/contributing/pages/images/\#examples) - -#### [Local Images](https://docs.sentry.io/contributing/pages/images/\#local-images) - -The file, `docs/product/alerts/alert-types.mdx`, can reference the local `docs/product/alerts/img/alert-details-example.png` image like so : - -Markdown - -`docs/product/alerts/alert-types.mdx` - -```markdown code-highlight -![Alert details ...](./img/alert-details-example.png) - -``` - -#### [Common Images](https://docs.sentry.io/contributing/pages/images/\#common-images) - -Images that are reused in multiple files should be single-sourced as an `include` file. For example, the common image, `includes/common-imgs/imgs/tags.png`, is referenced in the `include` file, `includes/common-imgs/tags.mdx`, like so: - -Markdown - -`includes/common-imgs/tags.mdx` - -```markdown code-highlight -![Tags](./img/tags.png) - -``` - -The image can then be used in multiple places (such as `docs/platforms/ruby/common/enriching-events/tags/index.mdx`) by referencing the `include` file with the following syntax: - -Markdown - -`docs/platforms/ruby/common/enriching-events/tags/index.mdx` - -```markdown code-highlight -<Include name="common-imgs/tags" /> - -``` - -#### [Public Images](https://docs.sentry.io/contributing/pages/images/\#public-images) - -While we recommend storing images locally with the files that reference them, you can also put them in the `public` folder. By default, the docs platform assumes images referenced with paths starting with `/` live in the `public` folder, so you don't need to include `public` in the image path. - -The folder structure of `public` mimics that of `docs` so that you can reference these images with relative paths. For example, the file, `docs/product/alerts/alert-types.mdx`, can reference the image, `public/product/alerts/issue-alert.png`, like so : - -Markdown - -`docs/product/alerts/alert-types.mdx` - -```markdown code-highlight -![Issue alert](issue-alert.png) - -``` - -Content files living elsewhere can also reference public images by using their full paths (excluding `public`). For example, the file, `docs/platform/apple/index.mdx`, can also reference the same image, `public/product/alerts/issue-alert.png`, like so: - -Markdown - -`docs/platform/apple/index.mdx` - -```markdown code-highlight -![Issue alert](/product/alerts/issue-alert.png) - -``` - -## [Image Optimization](https://docs.sentry.io/contributing/pages/images/\#image-optimization) - -To save space and ensure consistency, we ask that all image files be compressed and cropped to the dimensions listed below. When adding an image, please makes sure that it's high-resolution and crisp and that text is big enough to read. - -### [Recommended Dimensions](https://docs.sentry.io/contributing/pages/images/\#recommended-dimensions) - -- If you want the image to take up the full width of the page, make it **1484 pixels** wide. - -- If you want the image to be indented once (for example, if it's under a list item), make it **1400 pixels** wide. - - -### [Image Compression](https://docs.sentry.io/contributing/pages/images/\#image-compression) - -For performance reasons, images should be compressed. We recommend using ImageOptim. Here are the steps to follow: - -1. Download and install [https://imageoptim.com/](https://imageoptim.com/). -2. Drag and drop your image(s) into the tool. The files will be compressed in place. -3. Wait until a green checkmark appears, then add the compressed image to the appropriate path in the `public` folder of the docs repo. - -[Previous\\ -\\ -Frontmatter](https://docs.sentry.io/contributing/pages/frontmatter) - -[Next\\ -\\ -Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/images.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) - -# Concepts & Reference - -## Learn the basic concepts of Sentry such as searchable properties and data management settings. - -[Previous\\ -\\ -Security, Legal, & PII](https://docs.sentry.io/security-legal-pii) - -[Next\\ -\\ -Concepts](https://docs.sentry.io/concepts/key-terms) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Authentication](https://docs.sentry.io/api/auth/) - -# Authentication - -## [Auth Tokens](https://docs.sentry.io/api/auth/\#auth-tokens) - -Authentication tokens are passed using an auth header, and are used to authenticate as a user or organization account with the API. In our documentation, we have several placeholders that appear between curly braces or chevrons, such as `{API_KEY}` or `<auth_token>`, which you will need to replace with one of your authentication tokens in order to use the API call effectively. - -For example, when the documentation says: - -Bash - -`` - -```bash code-highlight -curl -H 'Authorization: Bearer {TOKEN}' https://sentry.io/api/0/organizations/{organization_slug}/projects/ - -``` - -If your authentication token is `1a2b3c`, and your organization slug is `acme` then the command should be: - -Bash - -`` - -```bash code-highlight -curl -H 'Authorization: Bearer 1a2b3c' https://sentry.io/api/0/organizations/acme/projects/ - -``` - -You can create authentication tokens within Sentry by [creating an internal integration](https://docs.sentry.io/organization/integrations/integration-platform/#internal-integrations). This is also available for self-hosted Sentry. - -### [User authentication tokens](https://docs.sentry.io/api/auth/\#user-authentication-tokens) - -Some API endpoints require an authentication token that's associated with your user account, rather than an authentication token from an internal integration. These auth tokens can be created within Sentry on the "User settings" page ( **User settings > User Auth Tokens**) and assigned specific scopes. - -The endpoints that require a user authentication token are specific to your user, such as [Retrieve an Organization](https://docs.sentry.io/api/organizations/retrieve-an-organization/). - -## [DSN Authentication](https://docs.sentry.io/api/auth/\#dsn-authentication) - -Some API endpoints may allow DSN-based authentication. This is generally very limited and an endpoint will describe if its supported. This works similar to Bearer token authentication, but uses your DSN (Client Key). - -Bash - -`` - -```bash code-highlight -curl -H 'Authorization: DSN {DSN}' https://sentry.io/api/0/{organization_slug}/{project_slug}/user-reports/ - -``` - -## [API Keys](https://docs.sentry.io/api/auth/\#api-keys) - -##### Note - -API keys are a legacy means of authenticating. They will still be supported but are disabled for new accounts. You should use **authentication tokens** wherever possible. - -API keys are passed using HTTP Basic auth where the username is your api key, and the password is an empty value. - -As an example, to get information about the project which your key is bound to, you might make a request like so: - -Bash - -`` - -```bash code-highlight -curl -u {API_KEY}: https://sentry.io/api/0/organizations/{organization_slug}/projects/ - -``` - -You **must** pass a value for the password, which is the reason the `:` is present in our example. - -[Previous\\ -\\ -API Reference](https://docs.sentry.io/api) - -[Next\\ -\\ -Paginating Results](https://docs.sentry.io/api/pagination) - -- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/) - -# Issue Properties - -## Learn more about searchable issue properties. - -[Issues](https://docs.sentry.io/product/issues/) are an aggregate of one or more error events. Searchable issues properties include status, assignment, aggregate counts, and age. If you have set up [evaluation tracking for feature flags](https://docs.sentry.io/product/issues/issue-details/feature-flags/#evaluation-tracking), you can search for issues that have error events where the feature flag evaluated value is `true` or `false`. You can search by issue properties in the **Issues** page and in **Dashboards** in the widget builder, depending on your dataset selection. - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the issues search. - -You'll only need to use query syntax for **datetime** and **relative time** searchable property types if you're using the Sentry [API](https://docs.sentry.io/api/). - -### [`age`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#age) - -Returns issues created since the time defined by the value. The syntax is similar to the Unix find command. Supported suffixes: `m - minutes`, `h - hours`, `d - days`, `w - weeks`. For example, `age:-24h` returns isssues that are new in the last 24 hours, while `age:+12h` returns ones that are older than 12 hours. Entering `age:+12h age:-24h` would return issues created between 12 and 24 hours ago. - -- **Type:** relative time - -### [`app.in_foreground`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#appin_foreground) - -Indicates if the app is in the foreground or background. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`assigned`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#assigned) - -Returns issues assigned to the defined user(s) or team(s). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee, `my_teams` or `#team-name` for teams you belong to. - -- **Type:** team or org user - -### [`assigned_or_suggested`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#assigned_or_suggested) - -Returns issues that are assigned to or suggested to be assigned to the defined user(s) or team(s). Suggested assignees are found by matching [ownership rules](https://docs.sentry.io/product/issues/ownership-rules/) and [suspect commits](https://docs.sentry.io/product/issues/suspect-commits/). Values can be a user ID (your email address), `me` for yourself, `none` for no assignee/suggestion, `my_teams` or `#team-name` for teams you belong to. - -- **Type:** team or org user - -### [`bookmarks`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#bookmarks) - -Returns issues bookmarked by the defined user. Values can be your user ID (your email address) or `me` for yourself. - -- **Type:** team or org user - -### [`device.arch`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicearch) - -CPU architecture - -- **Type:** string - -### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicebrand) - -Brand of the device - -- **Type:** string - -### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicefamily) - -Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. - -- **Type:** string - -### [`device.locale`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicelocale) - -Deprecated - -- **Type:** string - -### [`device.model_id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicemodel_id) - -Internal hardware revision to identify the device exactly. - -- **Type:** n/a - -### [`device.orientation`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#deviceorientation) - -Describes the orientation of the device and can be either `portrait` or `landscape`. - -- **Type:** string - -### [`device.screen_density`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_density) - -Device screen density in pixels. - -- **Type:** string - -### [`device.screen_dpi`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_dpi) - -Number of dots per inch of the device screen. - -- **Type:** string - -### [`device.screen_height_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_height_pixels) - -Device screen height in pixels. - -- **Type:** string - -### [`device.screen_width_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#devicescreen_width_pixels) - -Device screen width in pixels. - -- **Type:** string - -### [`device.uuid`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#deviceuuid) - -Deprecated - -- **Type:** UUID - -### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#dist) - -Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. - -- **Type:** string - -### [`error.handled`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorhandled) - -Indicates whether the user has handled the exception — for example, using try...catch. An error is considered handled if all stack traces handle the error. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`error.main_thread`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errormain_thread) - -Indicates if the error occurred on the main thread. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`error.mechanism`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errormechanism) - -An object describing the mechanism that created this exception. - -- **Type:** array - -### [`error.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errortype) - -The type of exception. For example, `ValueError`. - -- **Type:** array - -### [`error.unhandled`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorunhandled) - -The inversion of `error.handled`. - -- **Type:** boolean - -### [`error.value`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#errorvalue) - -Original value of a field that causes or exhibits the error. - -- **Type:** array - -### [`event.timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#eventtimestamp) - -Returns issues with matching datetime. - -- **Type:** datetime - -### [`event.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#eventtype) - -Type of the event (transaction, error, default, csp, and so on). The transaction type is unavailable in **Issues**. - -- **Type:** string - -### [`firstRelease`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#firstrelease) - -Returns issues first seen within the given release. Can be an exact match on the version of a release, or `first-release:latest` to pick the most recent release. - -- **Type:** datetime - -### [`firstSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#firstseen) - -Returns issues with a matching first time seen. Syntax is the same as `age`. - -- **Type:** datetime - -### [`flags`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#flags) - -For [feature flag evaluations](https://docs.sentry.io/product/issues/issue-details/feature-flags/#evaluation-tracking) set to `true` or `false`, the name of the feature flag. - -- **Type:** boolean - -### [`geo.city`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#geocity) - -Full name of the city - -- **Type:** string - -### [`geo.country_code`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#geocountry_code) - -ISO 3166-1 country code - -- **Type:** string - -### [`geo.region`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#georegion) - -Full name of the country - -- **Type:** string - -### [`has`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#has) - -Returns results with the defined tag or field, but not the value of that tag or field. For example, entering `has:user` would find events with the `user` tag. - -- **Type:** error - -### [`http.method`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpmethod) - -HTTP method of the [request](https://develop.sentry.dev/sdk/data-model/event-payloads/request/) that created the event. - -- **Type:** string - -### [`http.referer`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpreferer) - -Identifies the web page from which the resource was requested. - -- **Type:** string - -### [`http.status_code`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpstatus_code) - -HTTP status code, which indicates whether a response was successful. For example, `200` or `404`. - -- **Type:** string - -### [`http.url`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#httpurl) - -Full URL of the request that caused the error, but without any parameters - -- **Type:** string - -### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#id) - -The event or replay id. In **Issues**, use only the ID value without the `id` key. - -- **Type:** UUID - -### [`is`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#is) - -The properties of an issue. Values can be: `unresolved`, `resolved`, `archived`, `assigned`, `unassigned`, `for_review`, `linked`, or `unlinked`. The `for_review` value filters unresolved issues and only shows the recently unresolved or new issues that haven't been marked as "reviewed". The `linked` and `unlinked` values return issues based on whether they're linked to an external issue tracker or not. - -- **Type:** status - -### [`issue`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issue) - -The short issue code, for example `SENTRY-ABC`. - -- **Type:** string - -### [`issue.category`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issuecategory) - -The category of the issue. For example: `error`, `performance`, `replay` and `cron`. - -- **Type:** string - -### [`issue.type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#issuetype) - -The specific type of issue. For example `issue.type:performance_n_plus_one_db_queries ` returns the n plus one db query performance issues. - -- **Type:** string - -### [`lastSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#lastseen) - -Datetime when the event was last seen. For example, `lastSeen:+30d` returns issues last seen 30 days ago or more; `lastSeen:-2d` returns issues last seen within the past two days. This is similar to `age`. - -- **Type:** datetime - -### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#level) - -Severity of the event (such as: fatal, error, warning). Always set to info for transactions. - -- **Type:** string - -### [`location`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#location) - -Location where the error happened. - -- **Type:** string - -### [`message`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#message) - -Returns errors with the matching message or transactions with matching transaction name. Also matches on any message containing the supplied value.Searching `message:undefined` will match an event with a message of `undefined is not an object`. Raw text searches (searches without the `message` key) are also checked against this field. For errors, the message can be a concatenatenation of elements, so searches might include unexpected results. - -- **Type:** string - -### [`os.build`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osbuild) - -The internal build revision of the operating system. - -- **Type:** string - -### [`os.kernel_version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#oskernel_version) - -The independent kernel version string. This is typically the entire output of the `uname` syscall. - -- **Type:** string - -### [`os.distribution_name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osdistribution_name) - -The Linux distribution name. This maps to `ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). - -- **Type:** string - -### [`os.distribution_version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#osdistribution_version) - -The Linux distribution version. This maps to `VERSION_ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). - -- **Type:** string - -### [`platform.name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#platformname) - -Name of the platform - -- **Type:** string - -### [`project`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#project) - -The name of the project. In some pages of [sentry.io](https://sentry.io/), you can also filter on project using a dropdown. - -- **Type:** string - -### [`project.id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#projectid) - -The id of the project. - -- **Type:** number - -### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#release) - -A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). - -- **Type:** string - -### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasebuild) - -The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** number - -### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasepackage) - -The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releasestage) - -The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). - -- **Type:** string - -### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#releaseversion) - -A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#sdkname) - -Name of the Sentry SDK that sent the event. - -- **Type:** string - -### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#sdkversion) - -Version of the Sentry SDK that sent the event. - -- **Type:** string - -### [`stack.abs_path`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackabs_path) - -The absolute path to the source file. In events, this is an array; in issues, this is a single value. - -- **Type:** array, single value - -### [`stack.filename`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackfilename) - -The path to the source file relative to the project root directory. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.function`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackfunction) - -Name of the function being called. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.module`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackmodule) - -Platform-specific module path. For example, `sentry.interfaces.Stacktrace`. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.package`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#stackpackage) - -The "package" the frame was contained in. Depending on the platform, this can be different things. For C#, it can be the name of the assembly. For native code, it can be the path of the dynamic library or something else. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`timesSeen`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#timesseen) - -Returns results with a matching count. (Same as `count()` in events.) - -- **Type:** number - -### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#timestamp) - -The finish timestamp of the transaction. Returns events with matching datetime. - -- **Type:** datetime - -### [`title`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#title) - -Title of the error or the transaction name. - -- **Type:** string - -### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#trace) - -A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. - -- **Type:** UUID - -### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#transaction) - -For [transactions](https://docs.sentry.io/product/insights/overview/transaction-summary/#what-is-a-transaction), the name of the transaction. For errors, the name of the associated transaction. - -- **Type:** string - -### [`unreal.crash_type`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#unrealcrash_type) - -The [Unreal Crash Context Type](https://docs.unrealengine.com/4.27/en-US/API/Runtime/Core/GenericPlatform/ECrashContextType/) - -- **Type:** string - -### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#useremail) - -An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. - -- **Type:** string - -### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userid) - -Application-specific internal identifier for the user. - -- **Type:** string - -### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userip) - -User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. - -- **Type:** string - -### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/issues/\#userusername) - -Username, which is typically a better label than the `user.id`. - -- **Type:** string - -[Previous\\ -\\ -Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) - -[Next\\ -\\ -Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/issues.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) - -# Concepts - -## Learn about important concepts that are essential to using Sentry. - -[Previous\\ -\\ -Concepts & Reference](https://docs.sentry.io/concepts) - -[Next\\ -\\ -Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [MDX Components](https://docs.sentry.io/contributing/pages/components/) - -# MDX Components - -## [Alert](https://docs.sentry.io/contributing/pages/components/\#alert) - -Render an alert (sometimes called a callout) to highlight important information. - -##### Note - -This is an info alert. Use this to emphasize information that users should read. - -##### Important - -This is a warning alert. Use this to alert users to potential risks they should be aware of. - -##### Tip - -This is a success alert. Use this to provide optional information that can help users be more successful. - -This is an alert without a title. `warning` alerts should always have titles to emphasize their importance. - -This is a multi-line alert without a title. Keep information brief and to the point. If this is challenging, consider whether the topic needs documentation on another page or if using the [Expandable](https://docs.sentry.io/contributing/pages/components/#expandable) component would be a better fit. - -##### List - -- You can create lists -- and **format** _your_ `text` - -InfoWarningSuccessNo Title - -`` - -```markdown code-highlight -<Alert title="Note"> -This is an info alert. -</Alert> - -``` - -Attributes: - -- `title` (string) - optional -- `level` (string: `'info' | 'warning' | 'success'`) \- optional, defaults to `'info'` - -**Where to place alerts:** - -Make sure your alerts aren't breaking the flow of the content. For example, don't put an alert between two paragraphs that explain a single concept. Use alerts sparingly; too many alerts on a single page can be overwhelming. - -**When to use which alert level:** - -- **Info**: Use this to emphasize information that users should read. For example: - - - information needed for users to succeed - - information you'd typically wrap in a note callout -- **Warning**: Use this to alert users to potential risks they should be aware of. For example: - - - - warnings about potential errors, such as ones caused by common oversights in project configuration - - warnings regarding breaking changes - -Best practices: - - - always use a title with this alert level -- **Success**: Use this to provide optional information that can help users be more successful. For example: - - - information that helps improve an already successful task, such as a link to additional reading material - - tips for best practices - -## [Arcade embeds](https://docs.sentry.io/contributing/pages/components/\#arcade-embeds) - -Render an [Arcade](https://arcade.software/) embed. - -Create Internal Integration & Alert Rule - -Create Internal Integration & Alert Rule - -![Select "Internal Integration" then click "Next".](<Base64-Image-Removed>)![Enter a name for your integration.](<Base64-Image-Removed>)![Click to create a new integration.](https://cdn.arcade.software/cdn-cgi/image/fit=scale-down,format=auto,dpr=2,width=3840/extension-uploads/c16e1f56-ecbc-4abd-ad6f-9cf8d0299105.png) - -![](<Base64-Image-Removed>) - -Example - -`` - -```markdown code-highlight -<Arcade src="https://demo.arcade.software/v7uhzmdV6Q5PDzoVPAE6?embed&show_copy_link=true" /> - -``` - -Attributes: - -- `src` (string) - the URL of the Arcade embed - -## [Expandable](https://docs.sentry.io/contributing/pages/components/\#expandable) - -Render an expandable section to provide additional information to users on demand. - -##### Here's something worth noting - -##### [With permalink](https://docs.sentry.io/contributing/pages/components/\#with-permalink) - -##### This could be important to some users - -##### Want some tips to improve something? - -ExamplePermalinkWarningSuccess - -`` - -```markdown code-highlight -<Expandable title="Here's something worth noting"> - This is an expandable section in an `'info'` alert style. -</Expandable> - -``` - -Attributes: - -- `title` (string) -- `permalink` (boolean) - optional: wraps the title in a link and shows it in the table of contents. - -**When to use expandables:** - -Expandables help keep our documentation clutter-free, allowing users to focus on important information while providing them the option to explore additional relevant details. - -For example, use expandables to: - -- offer information that is useful to some users but not all, like troubleshooting tips -- provide background information or insights into related concepts - -**Best practices** - -- Write the expandable title as a question or statement to clarify what users can expect from the content within: - - Do you want to learn more about these features? - - Are you using Node.js version 15 or lower? - - Advanced configuration options for XY use case. -- When you need to share important information that users should read, consider using an [alert](https://docs.sentry.io/contributing/pages/components/#alert) instead since its content is visible by default. -- Avoid overusing this component and make sure to provide valuable information that is relevant to the current topic. - -## [Code Blocks](https://docs.sentry.io/contributing/pages/components/\#code-blocks) - -Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages: - -Example - -`` - -````markdown code-highlight -```javascript -function foo() { -return "bar"; -} -``` - -```python -def foo(): -return 'bar' -``` - -```` - -Sometimes you may not want this behavior. To solve this, you can either break up the code blocks with some additional text, or use the `<Break />` component. - -Additionally code blocks also support `tabTitle` and `filename` properties: - -Example - -`` - -````markdown code-highlight -```javascript {tabTitle: Hello} {filename: index.js} -var foo = "bar"; -``` - -```` - -You can bring attention to specific lines in a code block using the `{fromLineA-toLineB}` for ranges, or `{lineA,lineB}` for specific lines (or a combination of the two): - -ExampleSource - -`` - -```code-highlight javascript -function foo() { - let lookat = "me"; - return "bar"; -} - -``` - -You can also highlight diffs using the `diff` language: - -Example - -`` - -````markdown code-highlight -```diff -- minus one -+ plus one -``` - -```` - -If you want to preserve syntax highlighting, you can add `diff` metadata to any code block then annotate the diff with `+` and `-`: - -ExampleSource - -`` - -```code-highlight javascript code-diff -function foo() { -- return "bar"; -+ return "baz"; -} - -``` - -## [ConfigKey](https://docs.sentry.io/contributing/pages/components/\#configkey) - -Render a heading with a configuration key in the correctly cased format for a given platform. - -If content is specified, it will automatically hide the content when the given `platform` is not selected in context. - -Example - -`` - -```markdown code-highlight -<ConfigKey name="send-default-pii" notSupported={["javascript"]}> - -Description of send-default-pii - -</ConfigKey> - -``` - -Attributes: - -- `name` (string) -- `platform` (string) - defaults to the `platform` value from the page context -- `supported` (string\[\]) -- `notSupported` (string\[\]) - -## [PageGrid](https://docs.sentry.io/contributing/pages/components/\#pagegrid) - -Render all `next_steps` of this document or default child pages, including their `description` if available. - -You can specify `next_steps` in the frontmatter of a page to include them in the grid. It supports relative paths and will automatically resolve them. - -Example - -`` - -```markdown code-highlight ---- -# in the frontmatter of a page: -next_steps: - - ./child-one - - ./child-two - - ../parent/child-three ---- - -<PageGrid /> - -``` - -Attributes: - -- `header` (string) - optional header value to include, rendered as an H2 - -- `nextPages` (boolean) - only render pages which come next based on sidebar ordering - -- `exclude` (string\[\]) - an array of pages to exclude from the grid. Specify the file name of the page, for example, `"index"` for `index.mdx`. - - -## [PlatformContent](https://docs.sentry.io/contributing/pages/components/\#platformcontent) - -Render an include based on the currently selected `platform` in context. - -Example - -`` - -```markdown code-highlight -<PlatformContent includePath="sdk-init" /> - -``` - -Attributes: - -- `includePath` (string) - the subfolder within `/includes` to map to -- `platform` (string) - defaults to the `platform` value from the page context - -Some notes: - -- When the current platform comes from the page context and no matching include is found, the content will be hidden. - -- Similar to `PlatformSection`, you can embed content in the block which will render _before_ the given include, but only when an include is available. - -- A file named `_default` will be used if no other content matches. - - -Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it. - -## [PlatformIdentifier](https://docs.sentry.io/contributing/pages/components/\#platformidentifier) - -Render terms in the correct case within the body text of a page (not in code samples) based on the platform case\_style setting: - -Example - -`` - -```markdown code-highlight -<PlatformIdentifier name="before-send" /> - -``` - -For example, if you use `<PlatformIdentifier name="before-send" />`, it will render as: - -- `beforeSend` if case\_style=camelCase -- `before_send` if case\_style=snake\_case -- `BeforeSend` if case\_style=PascalCase - -This component only works properly in platform pages. - -## [PlatformLink](https://docs.sentry.io/contributing/pages/components/\#platformlink) - -Useful for linking to platform-specific content when there's not a specific platform already selected. - -Example - -`` - -```markdown code-highlight -<PlatformLink to="/enriching-events/" /> - -``` - -This will direct users to a page where they can choose the platform, and then to the appropriate link. If they're within a page that already has an active platform, it will simply link to the appropriate page and skip the redirect. - -## [PlatformSection](https://docs.sentry.io/contributing/pages/components/\#platformsection) - -Render a section based on the currently selected `platform` in context. When the platform is not valid, the content will be hidden. - -Example - -`` - -```markdown code-highlight -<PlatformSection notSupported={["javascript"]}> - -Something that applies to all platforms, but not javascript or node. - -</PlatformSection> - -``` - -Attributes: - -- `platform` (string) - defaults to the `platform` value from the page context -- `supported` (string\[\]) -- `notSupported` (string\[\]) -- `noGuides` (boolean) - hide this on all guides (takes precedence over `supported`/ `notSupported`) - -## [Onboarding Options](https://docs.sentry.io/contributing/pages/components/\#onboarding-options) - -If you're writing product feature specific docs, you can specify code block `onboardingOptions` metadata: - -Markdown - -`` - -````markdown code-highlight -```go {"onboardingOptions": {"performance": "13-17"}} -// your code here -``` - -```` - -the general syntax is `{"onboardingOptions": {"feature": "range"}}` where `feature` is the feature id and `range` is the corresponding line range (similar to the line highlighting syntax). - -You can specify multiple features by separating them with a comma: - -`{"onboardingOptions": {"performance": "13-17", "profiling": "5-6"}}` - -The range visibility will be controlled by the `OnboardingOptionButtons` component: - -JSX - -`` - -```code-highlight jsx code-diff -<OnboardingOptionButtons - options={["error-monitoring", "profiling", "performance"]} -/> - -``` - -- `options` can either be either an object of this shape: - -TypeScript - -`` - -```code-highlight typescript -{ - id: 'error-monitoring' | 'performance' | 'profiling' | 'session-replay', - disabled: boolean, - checked: boolean -} - -``` - -or a string (one of these `id` s 👆) for convenience when using defaults. - -##### Important - -The underlying implementation relies on the `onboardingOptions` metadata in the code blocks to be valid JSON syntax. - -- default values: `checked: false` and `disabled: false` ( `true` for `error-monitoring`). - -Example (output of the above): - -Error MonitoringTracingProfiling - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//contributing/pages/components/). - -Go - -`` - -```code-highlight go -import ( - "fmt" - "net/http" - - "github.com/getsentry/sentry-go" - sentrygin "github.com/getsentry/sentry-go/gin" - "github.com/gin-gonic/gin" -) - -// To initialize Sentry's handler, you need to initialize Sentry itself beforehand -if err := sentry.Init(sentry.ClientOptions{ - Dsn: "https://examplePublicKey@o0.ingest.sentry.io/0", - EnableTracing: true, - // Set TracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // We recommend adjusting this value in production, - TracesSampleRate: 1.0, -}); err != nil { - fmt.Printf("Sentry initialization failed: %v\n", err) -} - -// Then create your app -app := gin.Default() - -// Once it's done, you can attach the handler as one of your middleware -app.Use(sentrygin.New(sentrygin.Options{})) - -// Set up routes -app.GET("/", func(ctx *gin.Context) { - ctx.String(http.StatusOK, "Hello world!") -}) - -// And run it -app.Run(":3000") - -``` - -You can conditionally render content based on the selected onboarding options using the `OnboardingOption` component - -Or you can use the `hideForThisOption` prop to hide the content for the selected option. - -Markdown - -`` - -````markdown code-highlight -```jsx -<OnboardingOption optionId="profiling" hideForThisOption> -Hide this section for `profiling` option. -</OnboardingOption> -``` - -```` - -Example: - -- toggle the `performance` option above to see the effect: - -JSX - -`` - -```code-highlight jsx -<OnboardingOption optionId="performance"> - This code block is wrapped in a `OnboardingOption` component and will - only be rendered when the `performance` option is selected. -</OnboardingOption>; - -``` - -- toggle the `profiling` option above to see the effect: - -JSX - -`` - -```code-highlight jsx -<OnboardingOption optionId="profiling" hideForThisOption> - This code block is wrapped in a `OnboardingOption` component and will - only be rendered when the `profiling` option is NOT selected. -</OnboardingOption>; - -``` - - -[Previous\\ -\\ -Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams) - -[Next\\ -\\ -Markdown Variables](https://docs.sentry.io/contributing/pages/variables) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/components.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Saved Searches](https://docs.sentry.io/concepts/search/saved-searches/) - -# Saved Searches - -## Learn more about default, recommended, and saved searches. - -Saved Searches has been deprecated and will be removed soon. Your saved searches will still be available in the "Add View" menu on the **Issues** page. Any saved search can be converted to an Issue View. - -Sentry allows you to save searches you've made on the **Issues** page. At the top of the page, next to the search bar, click "Custom Search" to access the "Saved Searches" sidebar. - -[![UI walkthrough of the Saved Searches feature.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaved-searches-PE2VA6OM.gif%23800x391&w=1920&q=75)](https://docs.sentry.io/mdx-images/saved-searches-PE2VA6OM.gif) - -## [Recommended Searches](https://docs.sentry.io/concepts/search/saved-searches/\#recommended-searches) - -Recommended searches are common search terms that we think you're likely to use. These premade searches are listed under "Recommended Searches" in the "Saved Searches" sidebar. - -[![Recommended searches section in the saved searches sidebar.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsearch-recommended-QHFYWJYQ.png%23337x220&w=750&q=75)](https://docs.sentry.io/mdx-images/search-recommended-QHFYWJYQ.png) - -## [Custom Saved Searches](https://docs.sentry.io/concepts/search/saved-searches/\#custom-saved-searches) - -Organization users in all roles can create their own saved searches. These searches are only visible to the person who created them and apply to all their projects. If you're an organization owner or manager, you have the option to make your saved searches visible only to yourself or to your entire organization. Organization-wide saved searches are not associated with a specific project, but with all projects across the organization. - -1. In the "Saved Searches" sidebar, click "Add saved search" to create a new custom search. - -2. In the modal that opens, name the search and set your query filters and sort order. If you're an organization owner or manager, you'll also have the option to make the search visible to all users in your organization. Then click "Save". - -3. The new search will be added to the "Saved Searches" sidebar. Click the name of the search to apply it. - - -[![UI walkthrough of the Custom Saved Searches feature.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fcustom-saved-searches-3W6JBFST.gif%23800x391&w=1920&q=75)](https://docs.sentry.io/mdx-images/custom-saved-searches-3W6JBFST.gif) - -## [Edit or Delete a Saved Search](https://docs.sentry.io/concepts/search/saved-searches/\#edit-or-delete-a-saved-search) - -You can edit or delete any of your personal saved searches, as well as organization-wide searches if you're an organization owner or manager. To do so, hover over the search in the sidebar and click the more options icon ("...") to access the "Edit" and "Delete" buttons. - -[![A saved search with an open overflow menu with edit and delete options](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsearch-saved-search-edit-delete-5EADMAF4.png%23335x239&w=750&q=75)](https://docs.sentry.io/mdx-images/search-saved-search-edit-delete-5EADMAF4.png) - -## [Set a Default Search](https://docs.sentry.io/concepts/search/saved-searches/\#set-a-default-search) - -You can set a search query as the default view you see on the **Issues** page. The default search is only visible to you and is applied across your projects. - -1. Enter search terms into the search bar, or select a saved search from the sidebar. - -2. Click the "Set as Default" button located in the header. - -[![Cursor mousing over the "Set as Default" button.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fset_default_search-RSGUJYJJ.png%232159x368&w=3840&q=75)](https://docs.sentry.io/mdx-images/set_default_search-RSGUJYJJ.png) - - -Once defaulted, Sentry will name the search "My Default Search" and return to it whenever you navigate to the **Issues** page. - -[![Issues page with a default search set.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fmy_default_search-X2PKX2W4.png%232135x370&w=3840&q=75)](https://docs.sentry.io/mdx-images/my_default_search-X2PKX2W4.png) - -[Previous\\ -\\ -Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties) - -[Next\\ -\\ -Data Management](https://docs.sentry.io/concepts/data-management) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/saved-searches.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Performance](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/) - -# How to Write - Performance - -The Performance section of the content covers performance instrumentation for our SDKs. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/performance` \- feel free to peruse the files in that directory to help answer any questions. - -Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions or suggestions. - -## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#start-here) - -Determine if the page applies: - -- If the content **does not apply**, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. -- If the content **does apply**, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting that customers open an issue for the missing sample. - -### [Set Up](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#set-up) - -The set up page is where readers may start, though the note at the beginning directs into the instrumentation content, if applicable. The reader path depends on whether the SDK has already been instrumented for performance monitoring in the refreshed Getting Started page. For folks adopting this feature later, this page covers how to set up. - -We expect this content to apply to all SDKS, as supported. - -This file is `index.mdx`. It explains how to install or set up (if appropriate) as well as how to enable tracing. - -To develop content for this file: - -1. If the guide is still a work-in-progress and is exposed as an experimental or an early access feature, add the platform to the `<PlatformSection>` wrapping the appropriate alert located at the beginning of the content for the page. - -2. If the guide is expected to be used in a high-throughput environment, add the platform to the following `<PlatformSection>` which advises testing before deploying to production. - -3. If automatic instrumentation is still in preview/beta for the guide, add your platform to the next `<PlatformSection>` that wraps around text that discusses this. - -4. If automatic instrumentation is supported, add your platform to the `<PlatformSection>` immediately following **Verify** which advises users to either use auto or custom (or manual) instrumentation to verify the feature. Either omit the platform from the `supported` list or add the platform to the `notSupported` list if auto instrumentation is not available. - -5. Add a code sample to `/src/platform-includes/performance/configure-sample-rate/` that covers how to set sample rates. Make sure to update `/docs/platforms/<SDK>/common/configuration/sampling.mdx` and **Tracing Options** in `/docs/platforms/<SDK>/common/configuration/options.mdx`. - -6. Do one of the following based on whether automatic instrumentation is available for the guide or not: a. If automatic instrumentation is supported, add your platform to the `<PlatformSection>` immediately following **Verify** which advises users to either use auto or custom (a.k.a. manual) instrumentation to verify the feature. Either omit the platform from `supported` or the platform to `notSupported`. - -b. If automatic instrumentation is not supported, add your platform to the second `<PlatformSection>` after **Verify** which advises users to test out tracing using custom (manual) instrumentation. Omit the platform from the `supported` list or add it to the `notSupported` list if automatic instrumentation is available. - -7. Determine if the paragraph regarding pageload and navigation applies to the guide. If so, add the guide to the `Supported` list in the `<PlatformSection>`. If not, either omit the guide from the `supported` list or add the guide to the `notSupported` list, which will prevent the content from displaying for this guide. - - -### [Custom Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#custom-instrumentation) - -We expect this content to apply to all SDKS. - -This file is `performance/instrumentation/custom-instrumentation.mdx`. It explains how to manually instrument transactions. - -If custom instrumentation for the framework is exposed as an experimental or an early access feature, add the guide to the `<PlatformSection>` wrapping the appropriate alert located at the beginning of the content for the page. - -To develop content for this file, add code samples to these directories: - -- `/src/platform-includes/performance/enable-manual-instrumentation/` -- `/src/platform-includes/performance/add-spans-example/` -- `/src/platform-includes/performance/retrieve-transaction/` - -If any of the above files are not applicable to your framework, find the `<PlatformSection>` wrapping the `<PlatformContent>` pointing to the unsupported file, and add your guide to its `notSupported` list. If such a `<PlatformSection>` doesn't already exist, create one and add your guide to its `notSupported` list. - -Then, determine whether to provide a code sample illustrating how to connect errors and spans. If so, add the SDK to the `Supported` list in the appropriate `<PlatformSection>`, then add a code sample `/src/platform-includes/performance/connect-errors-spans/`. - -### [Automatic Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#automatic-instrumentation) - -Populate the `sdk_name/common/performance/instrumentation/` directory with the file `automatic-instrumentation.mdx`. - -### [Troubleshooting](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#troubleshooting) - -This file is `troubleshooting-performance.mdx`. It explains corner cases and how to solve known issues. - -1. Determine if the framework needs an illustration of how to group transactions. If so, add the framework to `Supported` list in the `<PlatformSection>`, then add a code sample to `performance/group-transaction-example/`. If not, add the framework to `notSupported` list, which will prevent the **Group Transactions** heading from displaying for this framework. - -2. Add an example to `src/platform-includes/performance/control-data-truncation/` - - -### [Sampling](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/\#sampling) - -Guidelines TBD. - -[Previous\\ -\\ -How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management) - -[Next\\ -\\ -How to Write - Usage](https://docs.sentry.io/contributing/approach/sdk-docs/write-usage) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-performance.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Sample Rates](https://docs.sentry.io/concepts/key-terms/sample-rates/) - -# Sample Rates - -## Learn how to manage the amount of data you send and are billed for in Sentry by adjusting the sample rates of various Sentry products including Traces and Session Replays. - -## [Overview](https://docs.sentry.io/concepts/key-terms/sample-rates/\#overview) - -### [What Is a Sample Rate?](https://docs.sentry.io/concepts/key-terms/sample-rates/\#what-is-a-sample-rate) - -Adding Sentry to your app gives you a lot of valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. You can use sample rates to capture only a specified percentage of events like errors and traces. - -### [Why Not Capture All Events?](https://docs.sentry.io/concepts/key-terms/sample-rates/\#why-not-capture-all-events) - -We recommend sampling your transactions for two reasons: - -1. Capturing a single trace involves minimal overhead, but capturing traces for every page load or API request may add an undesirable load to your system. - -2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs and budget. - - -Choose a sampling rate that balances data accuracy with performance and storage concerns. You should aim to collect enough data to get meaningful insights without overloading resources. If unsure, start with a low rate and gradually increase it as you understand your traffic patterns better. - -## [Sampling Rate Options](https://docs.sentry.io/concepts/key-terms/sample-rates/\#sampling-rate-options) - -Some of the options below aren't available in every SDK; check out our platform-specific docs for more info. - -### [Error Events](https://docs.sentry.io/concepts/key-terms/sample-rates/\#error-events) - -- **SampleRate** \- Configures the sample rate for error events, in the range of 0.0 to 1.0. The default is 1.0, which means that 100% of error events will be sent. If set to 0.1, only 10% of error events will be sent. Events are picked randomly. - -### [Tracing](https://docs.sentry.io/concepts/key-terms/sample-rates/\#tracing) - -- **tracesSampleRate** \- A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. ( `0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. Either this or `tracesSampler` must be defined to enable tracing. - -- **tracesSampler** \- A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between 0 (0% chance of being sent) and 1 (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or `tracesSampleRate` must be defined to enable tracing. - - -Learn more about [tracing](https://docs.sentry.io/product/tracing/) in Sentry. - -### [Session Replay](https://docs.sentry.io/concepts/key-terms/sample-rates/\#session-replay) - -- **replaysSessionSampleRate** \- The sample rate for replays that begin recording immediately and last the entirety of the user's session. 1.0 collects all replays, and 0 collects none. - -- **replaysOnErrorSampleRate** \- The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends. 1.0 captures all sessions with an error, and 0 captures none. - - -Learn more about [session replay](https://docs.sentry.io/product/explore/session-replay/) in Sentry. - -[Previous\\ -\\ -Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer) - -[Next\\ -\\ -Environments](https://docs.sentry.io/concepts/key-terms/environments) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/sample-rates.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) -- [Custom SAML Provider](https://docs.sentry.io/organization/authentication/sso/saml2/) - -# Custom SAML Provider - -## Learn about how to integrate the Custom SAML Provider. - -This feature is available only if your organization is on a [Business or Enterprise plan](https://sentry.io/pricing/). This feature is not available on Trial plans. - -Sentry provides a generic auth provider for [SAML2 based authentication](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language), which allows Owners of a Sentry organization to manually configure any SAML2-enabled IdP system. Documented below are the general steps for integration. - -# [Setup](https://docs.sentry.io/organization/authentication/sso/saml2/\#setup) - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. - -Sentry supports the following SAML services: - -- Identity and Service Provider initiated SSO -- Identity Provider initiated SLO (Single Logout) - -## [Register Sentry with IdP](https://docs.sentry.io/organization/authentication/sso/saml2/\#register-sentry-with-idp) - -Before connecting Sentry to the Identity Provider (IdP), it’s important to first register Sentry as an application on the IdP’s side. Sentry’s SAML endpoints are as follows, where `YOUR_ORG_SLUG` is substituted for your organization slug: - -| ACS: | `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` | -| SLS: | `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` | -| Metadata: | `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` | - -**What are these three things?** - -- `ACS` means _Assertion Consumer Service_. It is used for establishing a session based on rules made between your IdP and the service provider with which it is integrating. Please note that Sentry’s ACS endpoint uses HTTP-POST bindings. -- `SLS` stands for _Single Logout Service_, and is used to address logout requests from the IdP. -- `Metadata`, alternatively referred to as the `entityID` in some systems, refers to the configuration data for an IdP or an SP. In this case, the metadata endpoint in Sentry refers to your Sentry organization’s metadata on the Service Provider end. - -When setting these values up on the IdP end, it’s important to remember that Sentry does not need to provide a signing certificate for the integration to work. - -## [Register IdP with Sentry](https://docs.sentry.io/organization/authentication/sso/saml2/\#register-idp-with-sentry) - -There are three distinct methods for registering your IdP with Sentry: Metadata, XML, and data fields. Each method is broken down below, and will produce the same end result. - -### [Using Metadata URL](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-metadata-url) - -This method only requires a Metadata URL provided by the IdP platform. After it has been supplied, Sentry will automatically fetch the metadata it needs. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-metadata-url-T7USEQX5.png%231372x672&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-metadata-url-T7USEQX5.png) - -### [Using Provider XML](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-provider-xml) - -For this method to work, an administrator needs to provide the contents of the IdP’s generated metadata file. Once the contents are pasted directly into the text field, Sentry will do the rest. Please note that Sentry does not require a signing certificate. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-provider-xml-IMRZOZ22.png%231366x894&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-provider-xml-IMRZOZ22.png) - -Here’s an example of what the Metadata XML contents look like. - -Xml - -`` - -```xml code-highlight -<?xml version="1.0" encoding="UTF-8" ?> -<md:EntityDescriptor - xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" - entityID="http://www.okta.com/SENTRY_APP_ID" -> - <md:IDPSSODescriptor - WantAuthnRequestsSigned="false" - protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" - > - <md:KeyDescriptor use="signing"> - <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> - <ds:X509Data> - <ds:X509Certificate>...</ds:X509Certificate> - </ds:X509Data> - </ds:KeyInfo> - </md:KeyDescriptor> - <md:NameIDFormat - >urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> - <md:NameIDFormat - >urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> - <md:SingleSignOnService - Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" - Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" - /> - <md:SingleSignOnService - Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" - Location="https://YOUR_OKTA_ORG.okta.com/app/sentry/SENTRY_APP_ID/sso/saml" - /> - </md:IDPSSODescriptor> -</md:EntityDescriptor> - -``` - -### [Using Provider Data](https://docs.sentry.io/organization/authentication/sso/saml2/\#using-provider-data) - -This registration method is the most involved, and requires matching up the data fields from an IdP. The easiest way to accomplish this is to look for the values in a metadata file such as the one provided above. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-provider-data-ODNIXIX2.png%231356x1374&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-provider-data-ODNIXIX2.png) - -Based on the XML file example above, the field values to plug in are as follows: - -- `EntityID` -- `X509Certificate` -- `SingleSignOnService` - -In this example, the `SingleLogoutService` isn’t provided by the IdP, and is treated as an optional value within Sentry. - -## [Map IdP Attributes](https://docs.sentry.io/organization/authentication/sso/saml2/\#map-idp-attributes) - -##### Note on field names - -Metadata field names can vary from one provider to another. For example, Microsoft Azure AD refers to these very metadata fields as **Claims**, while Okta refers to them as **Attributes**. Similarly, one platform might use **user.email**, while another vendor uses **emailaddress**. - -Here, the field values of Sentry members need to be matched up with the corresponding values for members in the IdP. The basic required fields are the IdP's User ID and email address, but Sentry can also optionally pull first and last name values from there as well. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-map-attributes-WT26H7MA.png%23687x652&w=1920&q=75)](https://docs.sentry.io/mdx-images/saml2-map-attributes-WT26H7MA.png) - -## [Confirm successful registration](https://docs.sentry.io/organization/authentication/sso/saml2/\#confirm-successful-registration) - -Once the SAML integration flow is complete, the related Auth page will reflect the status of a successful integration. From here, you can send reminders to any existing members who existed prior to the integration, and they will receive an email prompt to link their accounts. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsaml2-success-JNXCPXPG.png%231600x742&w=3840&q=75)](https://docs.sentry.io/mdx-images/saml2-success-JNXCPXPG.png) - -Because Sentry uses Just-In-Time (JIT) provisioning, new members are registered with Sentry automatically during their first login attempt with SAML SSO. These accounts will have their membership types delegated based on what the default membership role is in your Organization Settings in Sentry. - -## [SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/saml2/\#scim-provisioning) - -SCIM is available for automatic user provisioning, deprovisioning, and team assignment for SAML2 IdPs. [Configure Sentry for SCIM](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/#sentry-configuration), and then follow your IdP's documentation for further setup. Learn more about the Sentry SCIM API endpoints in the [SCIM API documentation](https://docs.sentry.io/api/scim/). - -## [FAQ](https://docs.sentry.io/organization/authentication/sso/saml2/\#faq) - -#### [What is the process for adding new members to a SAML2-enabled Sentry organization?](https://docs.sentry.io/organization/authentication/sso/saml2/\#what-is-the-process-for-adding-new-members-to-a-saml2-enabled-sentry-organization) - -Sentry makes use of Just-In-Time provisioning for member accounts; any new member created within an Identity Provider will have an account automatically created in Sentry when that member attempts to sign into Sentry for the first time. - -#### [What happens to Sentry accounts that exist prior to SAML being enabled/enforced?](https://docs.sentry.io/organization/authentication/sso/saml2/\#what-happens-to-sentry-accounts-that-exist-prior-to-saml-being-enabledenforced) - -Existing members will receive an email notifying them of the new SAML authentication option once it is turned on (regardless of enforcement) and they'll be able to link the accounts in the IdP system with their Sentry memberships. - -#### [Does Sentry deprovision members if they are no longer present in the Identity Provider?](https://docs.sentry.io/organization/authentication/sso/saml2/\#does-sentry-deprovision-members-if-they-are-no-longer-present-in-the-identity-provider) - -At this time, Sentry's SAML2 integration does not automatically deprovision inactive user accounts. Instead, the member remains inside of Sentry without any means to log in, as they can no longer access the IdP platform for sign-on. For now, inactive member accounts will need to be removed manually by a Manager or an Owner in Sentry. - -#### [Attempting to set up SAML2 SSO with an IdP results in a failure with the message “The provider did not return a valid user identity.” What is happening here?](https://docs.sentry.io/organization/authentication/sso/saml2/\#attempting-to-set-up-saml2-sso-with-an-idp-results-in-a-failure-with-the-message-the-provider-did-not-return-a-valid-user-identity-what-is-happening-here) - -The crux of the problem here is that different IdP platforms (Okta, Azure AD, etc) use different terms and conventions for the fields necessary for the integration to work. As a result, it’s possible to map up incorrect values into Sentry, causing SSO to fail with this error message. - -[Previous\\ -\\ -Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso) - -[Next\\ -\\ -Two-Factor Authentication (2FA)](https://docs.sentry.io/organization/authentication/two-factor-authentication) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/saml2.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) -- [Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/) - -# Google Cloud Run - -## Learn more about how you can use Sentry with your Google Cloud Run applications. - -Cloud Run helps developers save time in building and deploying their applications. Sentry helps save time in resolving production issues by providing detailed debugging capabilities. - -## [Install and Configure](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/\#install-and-configure) - -Sentry owner, manager, or admin permissions are required to install this integration. - -1. [Create an account](https://sentry.io/signup/) (or [Login](https://sentry.io/auth/login/)) on Sentry - -2. Choose your application platform - -[![Sentry Choose Platform](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsentry-choose-platform-6HFWB2RY.png%231195x400&w=3840&q=75)](https://docs.sentry.io/mdx-images/sentry-choose-platform-6HFWB2RY.png) - -3. Follow instructions to instrument your Cloud Run application. Detailed platform docs [here](https://docs.sentry.io/platforms/). - -4. Deploy your Cloud Run application with GCP. - - -[Previous\\ -\\ -Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers) - -[Next\\ -\\ -Troubleshooting Integrations](https://docs.sentry.io/organization/integrations/troubleshooting) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/gcp-cloud-run/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) - -# Data Management - -## Learn more about managing data using the Settings for your project and organization. Server-side data management options include issue grouping, data forwarding, and inbound filters. - -Please refer to [the SDK documentation for a general introduction to managing sensitive data](https://docs.sentry.io/platform-redirect/?next=%2Fdata-management%2Fsensitive-data%2F). This page documents only the server-side options. - -[Previous\\ -\\ -Search](https://docs.sentry.io/concepts/search) - -[Next\\ -\\ -Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) - -# SDK Documentation Structure - -Our structure for SDK content focuses on getting a user up and running quickly, then learning about all the features that can be configured or enabled in subpages. These subpages provide reference material, with code examples specific to the SDK. - -## [Content Sections](https://docs.sentry.io/contributing/approach/sdk-docs/\#content-sections) - -SDKs provide content that focus on 10 sections (two of which are auto-generated) that rely on common content. Each section is explained in detail on its own page. A quick overview: - -1. **Getting Started** - -A single, critical page. - -**[How to Write - Getting Started](https://docs.sentry.io/contributing/approach/write-getting-started/)** - -This content is used in two different areas for Sentry customers: - -1. [docs.sentry.io](https://docs.sentry.io/) -2. In-app wizard for customers creating or adding a project - -2. **Configuration** - -Covers all the ways customers can manage their implementation of the SDK. It consists of subpages (all of which can be turned on or off, as appropriate to the SDK). - -**[How to Update: Configuration](https://docs.sentry.io/contributing/approach/write-configuration/)** - -3. **Usage** - -Covers how to capture errors and messages, with a subpage to set the Level. - -**[How to Update: Usage](https://docs.sentry.io/contributing/approach/write-usage/)** - -4. **Troubleshooting** - -Covers corner and edge cases we know of. This content is developed at the primary SDK level, so is shared by the primary SDK and its associated guides. It is not common to all SDKs/platforms. - -The content resides in this directory `/docs/platforms/<SDK>/common/troubleshooting/` - -5. (Optional) **Migration Guide** - -Provided for customers who need to upgrade from the Raven version of the SDK. Not needed for newer SDKs. - -6. **Tracing** section - -Covers how to enable tracing (for customers who previously only used error monitoring) as enabled by each SDK, as well as subpages on Sampling and Transactions. - -_This section is a WIP._ - -7. **Enriching Events** section - -Covers the data sent to Sentry, as well as how to customize it. - -**[How to Update: Enriching Events](https://docs.sentry.io/contributing/approach/write-enriching-events/)** - -8. **Data Management** section - -Covers our algorithm for grouping and how it can be modified, as well as how to scrub sensitive data using the SDK. - -**[How to Update: Data Management](https://docs.sentry.io/contributing/approach/write-data-management/)** - -9. (Auto-generated) **Other Guides** - -Lists the other related platforms/integrations/SDKs for this SDK. - -10. (Auto-generated) **Other Platforms** - -Lists the other primary SDK/platforms. - - -This model is quite flexible - some SDKs will incorporate more information- others will require less information. - -We have several goals to using this format: - -- Ensure customers have a single page that gets them started quickly. -- Update the SDK content so that it is both **technically accurate** and **complete**. -- Ensure we've architected to support the structure of our docs, which separates Platform/SDK content from Product content. Think of this as "Platform/SDK docs help a customer send data to Sentry" and "Product docs help a customer understand what's in [sentry.io](http://sentry.io/), then determine an appropriate response" - -## [Where to Start](https://docs.sentry.io/contributing/approach/sdk-docs/\#where-to-start) - -1. Read the [contributor guidelines](https://docs.sentry.io/contributing/). The guidelines will help you set up your docs environment (the move to our new tooling is significant) and provide key technical details about SDK content, search, redirects, and the Wizard pages. If you need help, ask for help by opening an issue in GitHub. -2. Use the "How to" pages to understand what content is covered where. -3. Use the files and folder structure in JavaScript as a model. -4. Create a PR and please request getsentry/docs as reviewers. - -## [What Not To Do](https://docs.sentry.io/contributing/approach/sdk-docs/\#what-not-to-do) - -- Wonder and ponder. The model is not meant to work 100% of the time. It's anticipated that some of the content won't work neatly. If you're not sure where content should display, ask a question by opening an issue in GitHub. -- Don't forget to update the Wizard Pages that use the Getting Started content to help direct customers on sentry.io -- Don't forget to update the listing of SDKs that support performance monitoring, as appropriate. - -## [SDK Documentation Guides](https://docs.sentry.io/contributing/approach/sdk-docs/\#sdk-documentation-guides) - -[Previous\\ -\\ -Our Approach](https://docs.sentry.io/contributing/approach) - -[Next\\ -\\ -Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [How to Write - Enriching Events](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/) - -# How to Write - Enriching Events - -The Enriching Events section of the content covers how customers can add context to the data sent to Sentry. A new framework can adopt the common content, which is stored in `/docs/platforms/<SDK>/common/enriching-events` \- feel free to peruse the files in that directory to answer any questions. - -Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions/suggestions. - -Most of these pages are pretty self-evident, so only basic information is provided. But please ask questions by opening an issue on GitHub. - -## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#start-here) - -Determine if the page applies: - -- If the content _does not apply_, add the guide to `notSupported` list in the frontmatter of the file. This will turn off the display of the content for this guide. -- If the content _does apply_, add the `include` file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting customers open an issue for the missing sample. -- The JS family of content needs to import the SDK for the code samples to make sense on each page. Add the import statement to `/src/platform-includes/enriching-events/enriching-events/import`. - -### [Add Context](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#add-context) - -This file is `context.mdx`. It explains how to enable custom contexts. Add the code sample to this directory: - -- `/src/platform-includes/enriching-events/set-context/` - -If the guide can pass context directly, add it to the list of supported guides immediately above "Passing Context Directly". - -### [Identify Users](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#identify-users) - -This file is `identify-user.mdx`. It explains how to capture the user. Add the code samples to these directories: - -- `/src/platform-includes/enriching-events/set-user/` -- `/src/platform-includes/enriching-events/unset-user/` - -### [Set Transaction Name](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#set-transaction-name) - -This file is `transaction-name.mdx`. It explains how to override the transaction name. Add the code sample to this directory: - -- `/src/platform-includes/enriching-events/set-transaction-name/` - -If the guide can control the starting and stopping of transactions, add it to the list of supported guides that refers customers to our tracing docs. - -### [Customize Tags](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#customize-tags) - -This file is `tags.mdx`. It explains how to customize tags for an event. Add the code sample to this directory: - -- `/src/platform-includes/enriching-events/set-tag/` - -If the guide doesn't bind tags to the current scope, add it to the list of guides that don't support this option. - -### [Attachments](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#attachments) - -This file is `/attachments/index.mdx`. It explains attaching files along with the event. Add the code sample to this directory: - -- `/src/platform-includes/enriching-events/add-attachment/` - -If the guide is part of the native family, add it to the list of guides that support the native content regarding: - -- Debug information files and built-in support for native crashes -- Large crash reports -- The section on "Crash Reports and Privacy" -- The paragraph regarding limiting crash reports per issue - -This file is `breadcrumbs.mdx`. It explains manual breadcrumbs. Add the code sample to manually add record a breadcrumb to this directory: - -- `/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/` -- `/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/` - -One nuance: - -- Update, as appropriate, the supported guide list in the `PlatformSection supported` that precedes "The available breadcrumb keys..." - -### [User Feedback](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#user-feedback) - -This file is `user-feedback.mdx`. It explains how to use the embeddable JS widget or the API. - -- Update, as appropriate, the supported SDK list in the `PlatformSection supported` that precedes "User Feedback API". Then add the code sample to the `src/platform-includes/user-feedback/sdk-api-example` directory -- For the .NET family, if the User Feedback API has a specific integration, add it to the `PlatformSection supported` that precedes the "Use the .NET SDK", and add the appropriate link. -- Update, as appropriate, the SDKs that don't support the JS widget in the listed `PlatformSection notSupported` that precedes "Embeddeable JavaScript Widget". -- For the SDKs that use the JS widget, add the code sample to `/src/platform-includes/user-feedback/user-feedback-example-widget/` - -### [Scopes](https://docs.sentry.io/contributing/approach/sdk-docs/write-enriching-events/\#scopes) - -This file is `scopes.mdx`. It explains managing scopes. Add the code samples to these directories: - -- `/src/platform-includes/enriching-events/scopes/configure-scope/` -- `/src/platform-includes/enriching-events/unset-user/` -- `/src/platform-includes/enriching-events/scopes/with-scope/` - -[Previous\\ -\\ -How to Write - Configuration](https://docs.sentry.io/contributing/approach/sdk-docs/write-configuration) - -[Next\\ -\\ -How to Write - Data Management](https://docs.sentry.io/contributing/approach/sdk-docs/write-data-management) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/write-enriching-events.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Moving to SaaS](https://docs.sentry.io/concepts/migration/) - -# Moving to SaaS - -## Learn more about the reasons to move to Sentry's SaaS solution, which for many customers is less expensive to maintain, and easier to scale and support. - -Sentry offers a cloud-hosted, software-as-a-service (SaaS) solution in addition to a self-hosted solution, which are both functionally the same. However, many customers find that self-hosted Sentry can quickly become expensive to maintain, scale, and support, making our SaaS product the better and less costly option. To facilitate moving from self-hosted to SaaS, we provide a self-serve process known as "relocation". - -Check out this video on [**Migrating to Sentry SaaS**](https://sentry.io/resources/migrate-to-sentry-saas-workshop/) to learn about our relocation tooling. - -For additional reading on considering SaaS, take a look at: - -- [Self Hosted or Cloud Sentry?](https://sentry.io/_/resources/about-sentry/self-hosted-vs-cloud/) -- [XS:Code > Open Source is Free - But Expensive](https://dev.to/helad11/open-source-is-free-but-expensive-3h8a) -- [Frequently asked migration questions](https://sentry.io/from/self-hosted/) - -## [Relocating to Cloud](https://docs.sentry.io/concepts/migration/\#relocating-to-cloud) - -If your organization started with self-hosted Sentry, you've invested time and effort in configuring and customizing your Sentry org. Your work won't be wasted if you decide to move to a SaaS account because you won't have to start from scratch. You'll be able to relocate a lot of what you've configured into your new account. - -To make this relocation as seamless as possible, Sentry has a workflow that allows you to retain most of your account's settings and configurations as you move to SaaS. All you'll need is owner access to your self-hosted install, and a way to access it via the terminal. - -### [What you'll keep](https://docs.sentry.io/concepts/migration/\#what-youll-keep) - -All of the configurations, team and project structure, and most metadata will be relocated. Specifically, for every organization you [choose to relocate](https://docs.sentry.io/concepts/migration/#2-choose-which-organizations-to-relocate) this includes: - -- All organization settings -- User accounts and options for all organization members -- Projects and their settings -- Teams and their settings -- Alert rules -- Crons -- Dashboards -- Enabled data scrubbers -- Repositories -- Recent and saved searches - -### [What gets left behind](https://docs.sentry.io/concepts/migration/\#what-gets-left-behind) - -Any data related to specific issues, events, stack traces, or files like replays and source maps won't be transferred. Additionally, for security reasons, you'll need to reconnect and re-authenticate all of your integrations, and your users will need to re-connect their 2FA and create new API tokens after relocating. - -Below is a non-exhaustive list of some items that will not be relocated: - -- Integrations, including parts of relocated items that depend on them (ex: if an Alert Rule triggers Slack notifications, that trigger will be omitted) -- Webhooks -- Issues -- Events -- Replays and/or other [Event Attachments](https://docs.sentry.io/platforms/javascript/enriching-events/attachments/) -- Source Maps, [Debug Information Files](https://docs.sentry.io/cli/dif/) and/or [Artifact Bundles](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/artifact-bundles/) -- Release information, including any references to external repositories via specific Pull Requests -- Deployment information -- Custom Avatars - -One thing to note is that while we won't be able to transfer over historical event data, new incoming events will populate the projects in your relocated organization as soon as you [update your DSNs](https://docs.sentry.io/concepts/migration/#5-update-your-dsns). All relocated organization members will be automatically notified and re-invited via email once the relocation completes. - -### [Version support window](https://docs.sentry.io/concepts/migration/\#version-support-window) - -Self-serve relocation is only possible from the two most up-to-date minor self-hosted releases. That is, if the latest self-hosted release is version 24.2.3, your self-hosted install must be on at least version 24.1.0 to be successfully relocated. - -If you'd like to relocate from an earlier release, we ask that you [update](https://develop.sentry.dev/self-hosted/releases/) your self-hosted install to the latest version first. If there is some reason that this is not possible, please [contact support](https://sentry.io/contact/enterprise/) for more guidance. - -### [Data security](https://docs.sentry.io/concepts/migration/\#data-security) - -Your data will be encrypted end-to-end during the relocation process. The only file that will pass over the network will be an encrypted tarball that we'll never store in plaintext, and will delete within 30 days of the start of your relocation. - -## [How to Relocate](https://docs.sentry.io/concepts/migration/\#how-to-relocate) - -### [1\. Sign up with a promo code](https://docs.sentry.io/concepts/migration/\#1-sign-up-with-a-promo-code) - -Before you begin the relocation process, [sign up](https://sentry.io/signup/relocate/) for a new account on Sentry. If you already have a Sentry account, login and navigate to the [relocation landing page](https://sentry.io/relocation/). In either case, you should see a page like this: - -[![Relocation getting started page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Frelocation-landing-page-UPZS4K4S.png%231122x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/relocation-landing-page-UPZS4K4S.png) - -**To receive a $100 credit, make sure to use the promo code `relocate100` on this page.** - -### [2\. Choose which organizations to relocate](https://docs.sentry.io/concepts/migration/\#2-choose-which-organizations-to-relocate) - -Your self-hosted installation may have multiple organizations, each identified by a unique slug. You'll need to decide which org slugs to keep. You can always change them post-relocation by going to the **Organization Settings** page. - -[![Changing the org slug on the settings page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Forg-slug-B74S4C2M.png%231484x485&w=3840&q=75)](https://docs.sentry.io/mdx-images/org-slug-B74S4C2M.png) - -### [3\. Follow the in-app relocation instructions](https://docs.sentry.io/concepts/migration/\#3-follow-the-in-app-relocation-instructions) - -The rest of the in-app relocation instructions will walk you through the specific details of how to export your self-hosted instance's relocatable data. This will require terminal access to the machine running your self-hosted instance. Here's a quick overview: - -- You'll be asked to save a public key that we generate on the SaaS backend to your self-hosted machine -- You'll then use this key to execute a command which will generate an encrypted tarball with all your data -- Lastly, you'll be prompted to upload this tarball - -Most relocations complete in under an hour, though certain large or complex cases can take a bit longer. If you don't get an update from us within 24 hours, please [contact support](https://sentry.io/contact/enterprise/) for further assistance. - -### [4\. Choose a plan](https://docs.sentry.io/concepts/migration/\#4-choose-a-plan) - -Once your relocation is complete, you can choose the [pricing plan](https://sentry.io/pricing/) that best suits your needs. Note that plan pricing varies based on your [Event Volume](https://docs.sentry.io/product/accounts/quotas/). - -If you're expecting higher volumes or you're interested in our Enterprise capabilities (priority support and SLAs, and single-tenant options, for example), please [contact us](https://sentry.io/contact/enterprise/) regarding our **Enterprise Plan**. - -### [5\. Update your DSNs](https://docs.sentry.io/concepts/migration/\#5-update-your-dsns) - -Though your project data has been fully relocated, the DSNs for all of your projects will have changed, as they are now located at [https://sentry.io](https://sentry.io/) rather than your prior self-hosted domain name. This means that you'll need to update the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) you use in each of your SDKs for each relevant project. Once you complete this step, you'll should start to see issues and events (though hopefully not too many!) appearing as before. - -[Previous\\ -\\ -Data Management](https://docs.sentry.io/concepts/data-management) - -[Next\\ -\\ -Contributing to Docs](https://docs.sentry.io/contributing) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/migration/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) -- [AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) -- [Lambda Layer Modifications](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/) - -# Lambda Layer Modifications - -## Understand how the Sentry AWS Lambda integration works under the hood. - -## [Node](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/\#node) - -When Sentry is added to a Lambda function, the following modifications are made to your Lambda functions: - -- The layer for Sentry is added to your Lambdas. Any existing layers are honored and the Sentry layer is appended to the end. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Flayer-EQWHRKHV.png%23978x192&w=2048&q=75)](https://docs.sentry.io/mdx-images/layer-EQWHRKHV.png) - -- Sentry adds the following environment variables - - - - `NODE_OPTIONS`: This is to preload the `awslambda-auto` module which will automatically initialize Sentry - - `SENTRY_DSN`: This is set to the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) of your project - - `SENTRY_TRACES_SAMPLE_RATE`: This sets the [sampling rate](https://docs.sentry.io/platforms/javascript/guides/node/configuration/sampling/#sampling-transaction-events) for transactions. You can manually edit your environment variables if you want a different sampling rate. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenv_variables-55VGYFH7.png%23846x269&w=1920&q=75)](https://docs.sentry.io/mdx-images/env_variables-55VGYFH7.png) - -## [Python](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/how-it-works/\#python) - -When Sentry is added to a Lambda function, the following modifications are made to your Lambda functions: - -- The layer for Sentry is added to your Lambdas. Any existing layers are honored and the Sentry layer is appended to the end. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Flayer_python-TKZ367LO.png%233102x680&w=3840&q=75)](https://docs.sentry.io/mdx-images/layer_python-TKZ367LO.png) - -And your Runtime handler will point to Sentry's handler that will initialize the SDK for you, and then call your Runtime handler to invoke your function - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fhandler_python-PYDDZUIW.png%233108x626&w=3840&q=75)](https://docs.sentry.io/mdx-images/handler_python-PYDDZUIW.png) - -- Sentry adds the following environment variables - - - - `SENTRY_INITIAL_HANDLER`: This stores the value of your Runtime handler. If you choose to disable the Sentry layer, this value will be used to set the Runtime handler. - - `SENTRY_DSN`: This is set to the [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) of your project - - `SENTRY_TRACES_SAMPLE_RATE`: This sets the [sampling rate](https://docs.sentry.io/platforms/python/configuration/sampling/#sampling-transaction-events) for transactions. You can manually edit your environment variables if you want a different sampling rate. - -[![](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fenv_variables_python-J3OPUPVZ.png%233190x1270&w=3840&q=75)](https://docs.sentry.io/mdx-images/env_variables_python-J3OPUPVZ.png) - -[Previous\\ -\\ -AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) - -[Next\\ -\\ -Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/aws-lambda/how-it-works.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features/) - -# Early Adopter Features - -## Learn which features are currently in the early adopter phase. - -If you’re interested in being an Early Adopter, you can turn your organization’s Early Adopter status on/off in **Settings > General Settings**. This will affect all users in your organization and can be turned back off just as easily. - -[![The Early Adopter toggle enabled in settings.](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fearly-adopter-toggle-EWVOK5PQ.png%231484x364&w=3840&q=75)](https://docs.sentry.io/mdx-images/early-adopter-toggle-EWVOK5PQ.png) - -This page lists the features that you'll have access to when you opt-in as "Early Adopter". Note that features are sometimes released to early adopters in waves, so you may not see a feature immediately upon enabling the "Early Adopter" setting. - -Limitations: - -- This list does not include new features that aren't controlled by the "Early Adopter" setting, such as alphas, closed betas, or limited availability features that require manual opt-in. -- This list is not guaranteed to be 100% up-to-date, but it is monitored and updated frequently. - -## [Current Early Adopter Features](https://docs.sentry.io/organization/early-adopter-features/\#current-early-adopter-features) - -- [Issue Views](https://docs.sentry.io/product/issues/issue-views/) -- [Issue Status](https://docs.sentry.io/product/issues/states-triage/) tags -- [Span Summary](https://docs.sentry.io/product/insights/overview/transaction-summary/#span-summary) -- [Dynamic Alerts](https://docs.sentry.io/product/alerts/create-alerts/metric-alert-config/#dynamic-alerts) -- [New Trace Explorer With Span Metrics](https://docs.sentry.io/product/explore/new-trace-explorer/) - -[Previous\\ -\\ -Dynamic Sampling](https://docs.sentry.io/organization/dynamic-sampling) - -[Next\\ -\\ -Integrations](https://docs.sentry.io/organization/integrations) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/early-adopter-features/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/) - -# Span Properties - -## Learn more about searchable span properties. - -Spans are the underlying data element captured in Sentry SDKs that together make up a trace. - -You can search by span properties in the following [Sentry](https://sentry.io/) pages: - -- [Traces](https://docs.sentry.io/product/explore/traces/) \- when searching for a trace containing spans with matching properties - -When you search for span properties within the **Traces** page, the search will return any trace that contains _one or more spans_ that match your span properties filter. - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the span search: - -### [`action`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#action) - -The type of span action, for example, `SELECT` for a SQL span or `POST` for an HTTP span. - -- **Type:** string - -### [`browser.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#browsername) - -The name of the browser that generated the span. - -- **Type:** string - -### [`cache.hit`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#cachehit) - -Whether a cache read has hit or missed the queried cache key. Values are `'true'` or `'false'`. - -- **Type:** string - -### [`description`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#description) - -Parameterized and scrubbed description of the span. - -- **Type:** string - -### [`device.class`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#deviceclass) - -Device class is a synthesized field that's calculated by using device info found in context such as model (for iOS devices), and device specs like `processor_frequency` (for Android devices). - -- **Type:** string - -### [`domain`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#domain) - -General scope of the span’s action, for example, the tables involved in a `db` span or the host name in an `http` span. - -- **Type:** string - -### [`duration`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#duration) - -The total time taken by the span. - -- **Type:** duration - -### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#environment) - -Refers to your code deployment naming convention. For example, `development`, `testing`, `staging` and so on. [Learn more](https://docs.sentry.io/product/sentry-basics/environments/). In some pages of [Sentry](https://sentry.io/), you filter on environment using a dropdown. - -- **Type:** string - -### [`file_extension`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#file_extension) - -The file extension of a resource span. - -- **Type:** string - -### [`group`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#group) - -Unique hash of the span’s description. - -- **Type:** string - -### [`http.decoded_response_content_length`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpdecoded_response_content_length) - -The [decoded body size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/decodedBodySize) of the resource. - -- **Type:** string - -### [`http.response_content_length`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpresponse_content_length) - -The [encoded body size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/encodedBodySize) of the resource. - -- **Type:** string - -### [`http.response_transfer_size`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#httpresponse_transfer_size) - -The [total transfer size](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/transferSize) of the resource. - -- **Type:** string - -### [`messaging.destination.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#messagingdestinationname) - -The queue name or topic that the message is written or published to. The consumer also reads from this queue. - -- **Type:** string - -### [`messaging.message.id`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#messagingmessageid) - -The unique ID of a message from the queue or messaging system. - -- **Type:** string - -### [`module`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#module) - -The Insights module that the span is associated with, for example, `cache`, `db`, `http`, and so on. - -- **Type:** string - -### [`op`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#op) - -The operation of the span, for example, `http.client`, `middleware`. - -- **Type:** string - -### [`os.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#osname) - -Name of the operating system. - -- **Type:** string - -### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#platform) - -Name of the platform. This defaults to `other` and is only a property for platforms from this list: `as3`, `c`, `cfml`, `cocoa`, `csharp`, `elixir`, `go`, `groovy`, `haskell`, `java`, `javascript`, `native`, `node`, `objc`, `other`, `perl`, `php`, `python`, `ruby` - -- **Type:** string - -### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#release) - -A release is a version of your code deployed to an environment. You can create a token that matches a release exactly, or pick the most recent release by using `release:latest`. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). - -- **Type:** string - -### [`resource.render_blocking_status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#resourcerender_blocking_status) - -The [render blocking status](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/renderBlockingStatus) of the resource. - -- **Type:** string - -### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#sdkname) - -Name of the Sentry SDK that sent the event. - -- **Type:** string - -### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#sdkversion) - -Version of the Sentry SDK that sent the event. - -- **Type:** string - -### [`self_time`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#self_time) - -The duration of the span excluding the duration of its child spans. - -- **Type:** string - -### [`status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#status) - -Status of the operation the span represents. - -### [`status_code`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#status_code) - -The HTTP response status code. - -- **Type:** string - -### [`system`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#system) - -Database system (e.g., `postgresql` or `mysql`). - -- **Type:** string - -### [`trace.status`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#tracestatus) - -The span trace's success or failure status. - -- **Type:** string - -### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transaction) - -Name of the containing transaction. - -- **Type:** string - -### [`transaction.method`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transactionmethod) - -HTTP method of the containing transaction. - -- **Type:** string - -### [`transaction.op`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#transactionop) - -Operation of the containing transaction. - -- **Type:** string - -### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#useremail) - -An alternative or addition to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. - -- **Type:** string - -### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#userid) - -Application-specific internal identifier for the user. - -- **Type:** string - -### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/spans/\#userusername) - -Username, which is typically a better label than `user.id`. - -- **Type:** string - -[Previous\\ -\\ -Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events) - -[Next\\ -\\ -Session Replay Properties](https://docs.sentry.io/concepts/search/searchable-properties/session-replay) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/spans.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) - -# Our Approach - -Sentry uses a minimalist approach to documentation. Our docs have one goal: help customers gain mastery _quickly_. Minimalism in documentation puts the reader at the center of the content. Our audience is reading the documentation to solve a problem or finalize a setup or to understand. Thus, think **very critically** about the content that is provided, especially on a primary page. - -## [Use This Test](https://docs.sentry.io/contributing/approach/\#use-this-test) - -Ask these questions as you're developing content: - -- Is this information critical to helping a developer get up and running? If not, consider moving it to a subpage with a link to it from the primary page (or, as suggested by one of our engineering managers, "cool, I can bookmark this for later"). - -- Is this obvious from the UI? Our UI is largely self-documenting, so we don't need to explain what's already evident. - - -## [What Goes Where?](https://docs.sentry.io/contributing/approach/\#what-goes-where) - -Our content has some pretty clear divisions: - -- Platform/SDK content - instrument and configure your SDK -- Product content - look at all the data ingested into Sentry - -And within those primary categories: - -- Reference: What customers need to know -- Action: What customers can do (modify, filter, and so forth) - -If you're uncertain, [ask](https://github.com/getsentry/sentry-docs/issues). - -## [Writing for Sentry](https://docs.sentry.io/contributing/approach/\#writing-for-sentry) - -Keep these concepts in mind when contributing to docs: - -1. Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code. -2. Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/getting-started/inclusive-language/). -3. Feedback is a gift - share your PR so we can improve our content. - -[Previous\\ -\\ -Development Environment](https://docs.sentry.io/contributing/environment) - -[Next\\ -\\ -SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Tutorial: Create and List Teams with the Sentry API](https://docs.sentry.io/api/guides/teams-tutorial/) - -# Tutorial: Create and List Teams with the Sentry API - -This guide walks you through the basics of using Sentry's API to list the teams in an organization and create a new team. - -APIs used in this tutorial: - -- [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) -- [Create a New Team](https://docs.sentry.io/api/teams/create-a-new-team/) - -## [Prerequisites](https://docs.sentry.io/api/guides/teams-tutorial/\#prerequisites) - -- A Sentry authentication token with team:write scopes or higher and project:read scopes or higher. - - -> If you don't have an authentication token, follow the [Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token/) tutorial to create an organization auth token with the following permissions, or higher: -> -> - Organization: Read -> - Team: Write - - -We recommend using a free [Sentry developer account](https://sentry.io/pricing/) for this tutorial. - -## [List an Organization's Teams](https://docs.sentry.io/api/guides/teams-tutorial/\#list-an-organizations-teams) - -First, you will use the [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) API to list all the teams in your organization. - -### [Find your organization ID](https://docs.sentry.io/api/guides/teams-tutorial/\#find-your-organization-id) - -The list teams API requires you to pass in the an organization id to list teams for. - -You can find your organization ID in the browser URL of your Sentry instance. For example, [https://test-org.sentry.io/](https://test-org.sentry.io/). - -### [Make the cURL call](https://docs.sentry.io/api/guides/teams-tutorial/\#make-the-curl-call) - -1. Open your terminal. - -2. Save your auth token and organization ID as environment variables for ease of use. Paste the following commands into your terminal, replacing `<organization_id>` with your organization ID and `<auth_token>` with the auth token you copied previously:Bash - -`` - -```bash code-highlight -export SENTRY_ORG_ID=<organization_id> -export SENTRY_AUTH_TOKEN=<auth_token> - -``` - -3. Paste the following cURL command into your terminal:Bash - -`` - -```bash code-highlight -curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \ - -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' - -``` - -4. Here's an example of what the output of the command should be, for an organization that has a team called "test-team":JSON - -`` - -```code-highlight json -[\ - {\ - "id": "4505449964175360",\ - "slug": "test-team",\ - "name": "test-team",\ - "dateCreated": "2023-06-30T18:44:59.196618Z",\ - "isMember": false,\ - "teamRole": null,\ - "flags": {\ - "idp:provisioned": false\ - },\ - "access": [\ - "alerts:read",\ - "team:read",\ - "member:read",\ - "org:read",\ - "project:releases",\ - "project:read",\ - "event:write",\ - "event:read"\ - ],\ - "hasAccess": true,\ - "isPending": false,\ - "memberCount": 1,\ - "avatar": {\ - "avatarType": "letter_avatar",\ - "avatarUuid": null\ - },\ - "orgRole": null\ - }\ -] - -```The output gives you details about the teams within the specified organization. - -If your organization has enough teams, the API will return paginated results. See Sentry's docs on [Pagination](https://docs.sentry.io/api/pagination/) to learn how to handle paginated results. - -5. \[Optional\] To list information about the projects associated with each team you can set the `detailed` query parameter to `1`:Bash - -`` - -```bash code-highlight -curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=1" \ - -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' - -```Here's an example of what that output might look like if "test-team" has one associated project named "test-project":JSON - -`` - -```code-highlight json -[\ - {\ - ...\ - "orgRole": null,\ - "externalTeams": [],\ - "projects": [\ - {\ - "id": "4505506997403648",\ - "slug": "test-project",\ - "name": "test-project",\ - "platform": "javascript-react",\ - "dateCreated": "2023-07-10T20:29:17.426792Z",\ - "isBookmarked": false,\ - "isMember": false,\ - "features": [\ - "alert-filters",\ - "minidump",\ - "race-free-group-creation",\ - "similarity-indexing",\ - "similarity-view",\ - "releases"\ - ],\ - "firstEvent": "2023-07-10T20:39:35.811000Z",\ - "firstTransactionEvent": true,\ - "access": [],\ - "hasAccess": true,\ - "hasMinifiedStackTrace": true,\ - "hasMonitors": false,\ - "hasProfiles": false,\ - "hasReplays": true,\ - "hasSessions": true,\ - "isInternal": false,\ - "isPublic": false,\ - "avatar": {\ - "avatarType": "letter_avatar",\ - "avatarUuid": null\ - },\ - "color": "#bf853f",\ - "status": "active"\ - }\ - ]\ - }\ -] - -``` - - -## [Create a Team](https://docs.sentry.io/api/guides/teams-tutorial/\#create-a-team) - -Now that you know what teams already exist in your org, use the [Create a New Team](https://docs.sentry.io/api/teams/create-a-new-team/) API to create another. - -1. Make sure your auth token and organization ID are both still stored as environment variables in your shell. - -2. Paste the following cURL command into your terminal:Bash - -`` - -```bash code-highlight -curl -d "name=tutorial-team" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \ - -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' - -```The `name` query parameter means the name of the created team should be "tutorial-team". - -3. Here's an example of what the output of the command should be:JSON - -`` - -```code-highlight json -{ - "id": "4505524553711616", - "slug": "tutorial-team", - "name": "tutorial-team", - "dateCreated": "2023-07-13T22:54:05.074990Z", - "isMember": false, - "teamRole": null, - "flags": { - "idp:provisioned": false - }, - "access": [\ - "event:write",\ - "member:read",\ - "alerts:read",\ - "project:releases",\ - "project:read",\ - "event:read",\ - "team:read",\ - "org:read"\ - ], - "hasAccess": true, - "isPending": false, - "memberCount": 0, - "avatar": { - "avatarType": "letter_avatar", - "avatarUuid": null - }, - "orgRole": null -} - -``` - -4. \[Optional\] To create a team where the `slug` value is different than the `name` value, you can specify both in your POST call, like so:Bash - -`` - -```bash code-highlight -curl -d "name=tutorial-team&slug=tutorial-team-slug" -X POST "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/" \ - -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' - -``` - - -## [List an Organization's Teams](https://docs.sentry.io/api/guides/teams-tutorial/\#list-an-organizations-teams-1) - -Finally, call the [List an Organization's Teams](https://docs.sentry.io/api/teams/list-an-organizations-teams/) API one more time to make sure your new team is returned. - -1. Make sure your auth token and organization ID are both still stored as environment variables in your shell. - -2. Paste the following cURL command into your terminal:Bash - -`` - -```bash code-highlight -curl "https://sentry.io/api/0/organizations/$SENTRY_ORG_ID/teams/?detailed=0" \ - -H 'Authorization: Bearer $SENTRY_AUTH_TOKEN' - -``` - -3. Your response should contain an entry for your new "tutorial-team" and look something like this:JSON - -`` - -```code-highlight json -[\ - {\ - "id": "4505524236910592",\ - "slug": "test-team",\ - "name": "test-team",\ - "dateCreated": "2023-07-13T21:33:31.686812Z",\ - "isMember": false,\ - "teamRole": null,\ - "flags": {\ - "idp:provisioned": false\ - },\ - "access": [\ - "member:read",\ - "alerts:read",\ - "org:read",\ - "project:read",\ - "team:read",\ - "project:releases",\ - "event:read",\ - "event:write"\ - ],\ - "hasAccess": true,\ - "isPending": false,\ - "memberCount": 1,\ - "avatar": {\ - "avatarType": "letter_avatar",\ - "avatarUuid": null\ - },\ - "orgRole": null\ - },\ - {\ - "id": "4505524616167424",\ - "slug": "tutorial-team",\ - "name": "tutorial-team",\ - "dateCreated": "2023-07-13T23:09:58.243168Z",\ - "isMember": false,\ - "teamRole": null,\ - "flags": {\ - "idp:provisioned": false\ - },\ - "access": [\ - "member:read",\ - "alerts:read",\ - "org:read",\ - "project:read",\ - "team:read",\ - "project:releases",\ - "event:read",\ - "event:write"\ - ],\ - "hasAccess": true,\ - "isPending": false,\ - "memberCount": 0,\ - "avatar": {\ - "avatarType": "letter_avatar",\ - "avatarUuid": null\ - },\ - "orgRole": null\ - }\ -] - -``` - - -[Previous](https://docs.sentry.io/api/guides) - -[Next\\ -\\ -Tutorial: Create a Sentry Authentication Token](https://docs.sentry.io/api/guides/create-auth-token) - -- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Concepts](https://docs.sentry.io/concepts/key-terms/) -- [Key Terms & Features](https://docs.sentry.io/concepts/key-terms/key-terms/) - -# Key Terms & Features - -## A few key terms and features to help you get a better understanding of Sentry. - -Some of the below terms have corresponding features with the same name (in upper case) in the [Key Features](https://docs.sentry.io/concepts/key-terms/key-terms/#key-features) section. - -## [Key Terms](https://docs.sentry.io/concepts/key-terms/key-terms/\#key-terms) - -- **alerts** \- Alerts let you know about problems with your code in real-time by sending you notifications when certain alert rule conditions are met. There are several types of alerts available with customizable thresholds and integrations. - -- **attachments** \- Stored additional files, such as config or log files that are related to an error event. - -- **data** \- Anything you send to Sentry. This includes, events (errors or transactions), attachments, and event metadata. - -- **distributed trace** \- When a trace includes work in multiple services, it's called a [distributed trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/), because the trace is distributed across those services. - -- **DSN** \- Data Source Name. A DSN tells the Sentry SDK where to send events so the events are associated with the correct project. Sentry automatically assigns you a DSN when you create a project. Learn more in our full [DSN documentation](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). - -- **environment** \- `environment` is a Sentry-supported tag that you can add to your SDK that's intended to refer to your code deployments' naming convention, such as _development_, _testing_, _staging_, or _production_. Environments help you better filter issues and transactions among other uses. Learn more in our full [Environments documentation](https://docs.sentry.io/product/sentry-basics/environments/). - -- **error** \- What counts as an error varies by platform, but in general, if there's something that looks like an exception, it can be captured as an error in Sentry. Sentry automatically captures errors, uncaught exceptions, and unhandled rejections, as well as other types of errors, depending on platform. - -- **event** \- An error or a transaction. - -- **issues** \- An issue is a grouping of similar errors or performance problems. Every event has a set of characteristics called its fingerprint, which is what Sentry uses to group them. For example, Sentry groups error events together when they are triggered by the same part of your code. This grouping of events into issues allows you to see how frequently a problem is happening and how many users it's affecting. - -- **performance monitoring** \- Performance monitoring is the act of tracking application performance and measuring metrics such as how many transactions are being sent and the average response time for all occurrences of a given transaction. To do this, Sentry captures [distributed traces](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/) consisting of transactions and [spans](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/#traces-transactions-and-spans) to measure individual services, as well as operations within those services. - -- **project** \- A project represents your service or application in Sentry. You can create a project for a particular language or framework used in your application. For example, you might have separate projects for your API server and frontend client. For more information, check out our [best practices for creating projects](https://docs.sentry.io/organization/getting-started/#4-create-projects). Projects allow you to associate events with a distinct application in your organization and assign responsibility and ownership to specific users and teams within your organization. - -- **release** \- A release is a version of your code deployed to an environment. When you notify Sentry about a release, you can identify new issues and regressions associated with it, confirm whether an issue is resolved in the next release, and apply source maps. Learn more in the full [Releases documentation](https://docs.sentry.io/product/releases/). - -- **release health** \- Release health data provides insight into the impact of crashes and bugs as it relates to your user's experience and reveals trends with each new issue. Learn more in the full [release health documentation](https://docs.sentry.io/product/releases/health/). - -- **sentry.io** \- Sentry's user interface for SaaS customers, where event data captured by our SDK is visualized. (For self-hosted users, the user interface is on an internal domain for your company.) - -- **Sentry SDKs** \- Sentry's programming language/framework-specific libraries for application monitoring. When you add one of our SDKs to your application, event data from your application is captured and sent to Sentry, so we can provide you with error and performance reports. - -- **span** \- A [span](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans) is the basic unit that traces are composed of. Multiple groups of parent-child spans make up a trace in Sentry and share a trace\_id, which can help you get to the root cause of a problem faster. - -- **team** \- Teams are associated with your Sentry projects, and their members receive issue notifications as a group. Learn more about [setting up teams](https://docs.sentry.io/organization/getting-started/#2-set-up-teams). - -- **trace** \- A [trace](https://docs.sentry.io/concepts/key-terms/tracing/) is the record of the entire operation you want to measure or track - like page load, an instance of a user completing some action in your application, or a cron job in your backend. - -- **transaction** \- A transaction represents a single instance of a service being called to support an operation you want to measure or track, like a page load, page navigation, or asynchronous task. Transaction events are grouped by the transaction name. - - -## [Key Features](https://docs.sentry.io/concepts/key-terms/key-terms/\#key-features) - -Each of these key features have their own page (or set of pages) in the [sentry.io](https://sentry.io/) application. - -- **Issues** \- Displays information about grouped problems in your application. From here, you can go to the **Issue Details** page for a more granular view of any issue. Learn more in the full [Issues documentation](https://docs.sentry.io/product/issues/). - -- **Projects** \- Lists the projects of which you're a member, by team, and provides you with a high-level overview of your projects. From here, you can go to the **Project Details** page of each project for a more granular view. Learn more in the full [Projects documentation](https://docs.sentry.io/product/projects/). - -- **Explore** \- Sentry offers multiple ways to search and investigate your application's data — including your app's traces, metrics, profiles, replays, and events — to get the information you need to debug issues more quickly and easily. Use the Discover page to query events across environments, visualize the results, and unlock insights into the health of your entire system. Learn more in the full [Explore documentation](https://docs.sentry.io/product/explore/). - -- **Insights** \- Sentry surfaces insights that can help you identify opportunities at the service-level to improve various parts of your app's performance, including requests, assets, caches, queues, and more. Modules living under the Insights heading provide an overview of how your project is performing in that category, as well as the ability to review sample events and their traces to help you diagnose potential problems. - -- **Insights Overview** \- The main view in [sentry.io](http://sentry.io/) where you can search or browse for transaction data. The page displays graphs that visualize transactions or trends, as well as a table where you can view relevant transactions and drill down to more information about them. Learn more in the full [performance monitoring documentation](https://docs.sentry.io/product/insights/overview/). - -- **Alerts** \- Where you can create new alert rules and manage existing ones. Learn more in the full [Alerts documentation](https://docs.sentry.io/product/alerts/). - -- **Dashboards** \- Provide you with a broad overview of your application’s health by allowing you to navigate through error and performance data across multiple projects. Dashboards are made up of one or more widgets, and each widget visualizes one or more **Discover** or **Issues** queries. Learn more in the full [Dashboards documentation](https://docs.sentry.io/product/dashboards/). - -- **Releases** \- Provides a high-level view of each release version, the associated project, the adoption stage of each release, the authors of each commit, as well as release health data including the percentage of crash-free users, and the percentage of crash-free sessions. You can navigate directly to the **Releases** page or from the **Issue Details** page, by selecting release ID listed under "Last Seen". Learn more in the full [Releases documentation](https://docs.sentry.io/product/releases/). - - -[Previous\\ -\\ -Concepts](https://docs.sentry.io/concepts/key-terms) - -[Next\\ -\\ -Data Source Name (DSN)](https://docs.sentry.io/concepts/key-terms/dsn-explainer) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/key-terms/key-terms.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Pages](https://docs.sentry.io/contributing/pages/) -- [Charts & Diagrams](https://docs.sentry.io/contributing/pages/charts-diagrams/) - -# Charts & Diagrams - -You can render charts and diagrams in you MDX files using [Mermaid](https://mermaid.js.org/): - -Example - -`` - -````code-highlight txt -```mermaid -flowchart TD -Start --> Stop -``` - -```` - -Will turn into this: - -Mermaid - -`` - -```code-highlight mermaid -flowchart TD - Start --> Stop - -``` - -See the [Mermaid documentation](https://mermaid.js.org/intro/) to learn what types of charts and diagrams can be rendered. - -[Previous\\ -\\ -Images](https://docs.sentry.io/contributing/pages/images) - -[Next\\ -\\ -MDX Components](https://docs.sentry.io/contributing/pages/components) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/pages/charts-diagrams.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) -- [Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso/) -- [Okta SCIM Provisioning](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/) - -# Okta SCIM Provisioning - -## Set up Okta's SCIM Integration for Member and Team Provisioning - -This feature is only available if your organization is on a Business or Enterprise plan. - -If you change your organization slug, you'll also need to update it in the "Auth" section of your "Organization Settings" in Sentry. - -### [Supported Features](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#supported-features) - -- Create users -- Deactivate users -- Push groups -- Import groups -- Configure organization-level roles -- Update user attributes (organization-level roles only) - -### [Requirements](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#requirements) - -Okta SCIM provisioning requires: - -- A subscription to Sentry Business Plan or higher. -- Configuration of SAML SSO for Okta [as documented here](https://docs.sentry.io/organization/authentication/sso/okta-sso/), or use the Okta sign-on tab in your Sentry Okta application to configure SAML. -- **Selection of Email for the Application username format** in the Sign On application tab in Okta. [![Okta username configuration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-username-config-FIAOC3YE.png%231332x710&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-username-config-FIAOC3YE.png) - -### [Sentry Configuration](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#sentry-configuration) - -1. Sign in to [sentry.io](https://sentry.io/). Select **Settings > Auth** [![Sentry Okta SCIM Auth Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-settings-auth-I7AT2EWD.png%232688x1428&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-settings-auth-I7AT2EWD.png) -2. Under General Settings select "Enable SCIM", then "Save Settings" [![Sentry Enable SCIM Instruction](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-enable-sentry-7WE3LMJ5.png%231542x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-enable-sentry-7WE3LMJ5.png) Sentry will display "SCIM Information" that contains your Auth Token and SCIM Base URL. [![SCIM Credentials Fields](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-sentry-fields-Q4U5PUUE.png%231504x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-sentry-fields-Q4U5PUUE.png) - -### [Okta Configuration](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#okta-configuration) - -1. Sign in to your Okta organization with your administrator account. From the admin console's sidebar, select Applications > Applications, then select the existing Sentry application. - -2. Select the "Provisioning" tab, then "Configure API integration". [![Okta configure SCIM API](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-okta-configure-B4HRRJ2R.png%231852x1022&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-okta-configure-B4HRRJ2R.png) - -3. Select "Enable API Integration", then enter the SCIM URL from the auth settings page as the Base URL field. - -4. For the API Token, copy the Auth Token value from the auth settings page. - -5. Select "Test API Credentials". You should see a "the app was verified successfully" message appear. - -6. Select "Save" to be directed to SCIM App settings. - -7. On the Provisioning page, select "To App", then "edit": [![Okta Save SCIM Settings](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-okta-edit-KBKRWCR4.png%231864x686&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-okta-edit-KBKRWCR4.png) - -8. Enable both "Create Users" and "Deactivate Users", then click the "Save" button. [![Okta Create and Deactivate Users](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-user-sync-3RMBVCM6.png%232100x1366&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-user-sync-3RMBVCM6.png) - - -Once these changes have been made, newly assigned users will be sent an invitation email. If a user gets un-assigned, they'll be removed from their organization in Sentry. - -You can use "Push Groups" to sync and assign groups in Okta; they'll be mirrored in Sentry teams. - -If you use Okta to assign organization membership, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. To remove these users, deprovision them in Okta. - -[![Okta Provisioned User Unable to Leave](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-provisioned-unable-to-leave-IOB6CFSL.png%232444x250&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-provisioned-unable-to-leave-IOB6CFSL.png) - -### [Configuring Organization-level Roles](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#configuring-organization-level-roles) - -Here's how to assign an organization-level role to an Okta group: - -1. Add a new custom attribute to your Okta application profile - -1. Navigate to your application settings in Okta - -2. Under the "Provisioning" tab, select "Go to Profile Editor" [![Okta Provisioning Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-go-to-profile-ANIFPKTO.png%233398x2540&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-go-to-profile-ANIFPKTO.png) - -3. Select "+ Add Attribute" [![Okta Add Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-add-attribute-ORRVTSLT.png%232100x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-add-attribute-ORRVTSLT.png) - -4. Fill out the form with the following settings (You can set whatever value you want for any setting not listed below.): - - - - Data Type: `string` - - Display Name: `Org Role` - - Variable Name: `sentryOrgRole` - - External name: `sentryOrgRole` - - External namespace: `urn:ietf:params:scim:schemas:core:2.0:User` - - Attribute type: `Group` - -[![Okta Custom Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-custom-attribute-values-4FONBHNY.png%233400x2546&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-custom-attribute-values-4FONBHNY.png) -2. Assign a group to your okta application [![Okta Assign Group](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-assign-group-77ZIXYR4.png%232220x884&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-assign-group-77ZIXYR4.png) - -3. In the form, enter the string for the org-level role [![Okta Set Role](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-set-group-attribute-XTTLAXCA.png%233400x1668&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-set-group-attribute-XTTLAXCA.png) - - -- If the `sentryOrgField` field is left blank, group members will be provisioned with the default organization-level role. This default role can be configured in Sentry, under Settings -> Organization -> Auth. Otherwise, the role must be one of the following: - - Admin - - Manager - - Billing - - Member -- Invalid role names will prevent group members from being provisioned. To try again, you'll need to remove the group first. -- For security reasons, the "Owner" role cannot be provisioned through SCIM. However, you _can_ deprovision users who have the "Owner" role in Sentry, but aren't provisioned through SCIM. - - For self-hosted users with custom roles, this extends to any role with the `org:admin` permission - -If a user is a member of multiple Okta groups, only the attributes set by the first group will be used. - -If you use Okta to assign organization-level roles, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. To change a user's organization-level role, you will need to deprovision and then reprovision them with the new role. - -Users who've had their roles assigned via Okta will only be able to make membership changes via Okta. - -[![Okta Role Restricted Role Select](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-role-restricted-sentry-role-select-QCW7B66W.png%232350x1020&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-role-restricted-sentry-role-select-QCW7B66W.png) - -### [Updating User Attributes](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#updating-user-attributes) - -Currently, Sentry only supports the ability to update user attributes for organization-level roles. You'll be able to edit the attribute for users assigned to your application once you've added the `sentryOrgRole` attribute to your Okta application profile. - -[![Okta Edit Attribute](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fokta-edit-sentryOrgRole-attribute-BSHZOCG4.png%231362x692&w=3840&q=75)](https://docs.sentry.io/mdx-images/okta-edit-sentryOrgRole-attribute-BSHZOCG4.png) - -The user's role in Sentry will reflect their organization role in your Auth settings. This means that if you change a user's attribute to blank, their organization-level role will be removed from Sentry. - -## [Troubleshooting](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#troubleshooting) - -### [I get a "Matching user not found" error in Okta when provisioning a user.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-get-a-matching-user-not-found-error-in-okta-when-provisioning-a-user) - -Make sure that `Create User` and `Deactivate User` are enabled in the "Provisioning" tab of your Sentry application in Okta [(see Okta Configuration step 7)](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/#okta-configuration). - -### [I assigned Sentry to a group but no team was created.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-assigned-sentry-to-a-group-but-no-team-was-created) - -Assigning Sentry to a group in Okta is the same as assigning Sentry to every member of that group. Functionally, this provisions every group member within Sentry, but doesn't create a team. To create a team, push the group to Sentry from the `Push Groups` tab of your Sentry application in Okta. - -### [I pushed a group to Sentry but the team is empty.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-pushed-a-group-to-sentry-but-the-team-is-empty) - -Pushing a group via Okta tells Sentry to create a new team with the same name as the Okta group. Only those users who've already been provisioned as members of that group will be added to the Sentry team. Make sure that your group in Okta contains the appropriate users and that they've already been provisioned. - -### [I pushed a group to Sentry but am receiving a "User not found" error.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-pushed-a-group-to-sentry-but-am-receiving-a-user-not-found-error) - -If possible, isolate the user(s) that are causing the error. Then remove the user(s) from Sentry and provision them again with Okta. - -### [I’m unable to use the Sentry application to remove a member whose membership is managed by an identity provider.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#im-unable-to-use-the-sentry-application-to-remove-a-member-whose-membership-is-managed-by-an-identity-provider) - -When team membership is managed by an identity provider (such as Okta), it can only be updated or revoked via that identity provider. - -### [I’m unable to use the Sentry application to add or remove members from my team.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#im-unable-to-use-the-sentry-application-to-add-or-remove-members-from-my-team) - -If you use Okta to assign members to a team, you’ll be unable to make membership changes through Sentry and will need to continue using Okta. - -### [I used Okta to remove a user from Sentry, but they’re still showing up in my Sentry organization.](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#i-used-okta-to-remove-a-user-from-sentry-but-theyre-still-showing-up-in-my-sentry-organization) - -Make sure that `Deactivate User` is enabled in the "Provisioning" tab of your Sentry application in Okta. Re-provision the user, then remove them again. - -### [How do I remove the organization-level role for a user that I set via Okta?](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#how-do-i-remove-the-organization-level-role-for-a-user-that-i-set-via-okta) - -Change the user's role attribute to blank. - -## [Known Issues](https://docs.sentry.io/organization/authentication/sso/okta-sso/okta-scim/\#known-issues) - -- The Import Users feature isn't currently supported because Sentry's SCIM API doesn't support the user `name` attribute fields: `firstName` and `lastName` at this time. For compatibility purposes, they're returned as `N/A` values. -- If the `active` field is set to `false` for any given user, their organization member record gets deleted. -- The only filter operation supported for resources is `eq`. -- When provisioning a new team, Sentry will both normalize and convert the team `displayName` uppercase to lowercase, and convert spaces to dashes. -- The GET /Groups endpoint cannot return more than 10000 members in a group, see [SCIM API documentation](https://docs.sentry.io/api/scim/) for more information. - -[Previous\\ -\\ -Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) - -[Next\\ -\\ -Ping Identity SSO](https://docs.sentry.io/organization/authentication/sso/ping-sso) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/okta-sso/okta-scim.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs/) -- [Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/) - -# Common Content - -Our docs strive for a contributor-friendly balance of duplication vs. complexity. That means we generally don't try to share content between SDKs in our docs, even when they have similar information architecture, sections, and even wording. Instead of enforcing consistency through shared content, we encourage contributors to reference other SDK docs to keep things consistent wherever possible. - -For SDKs that have framework-specific docs (which we call guides or children), common content for that SDK's frameworks lives in `/docs/platforms/<platform_name>/common/`. - -## [Hierarchy](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/\#hierarchy) - -What displays for the user relies upon the hierarchy of content as detailed in our content discussing [Platforms & Guides](https://docs.sentry.io/contributing/platforms/). In short, a guide's content displays if provided. If not provided, then the platform content displays. - -## [Tuning Common Content](https://docs.sentry.io/contributing/approach/sdk-docs/common_content/\#tuning-common-content) - -To ensure that common content can scale as we support more platforms and frameworks, we use `include` files. These files can range from, most typically, a code sample specific to a platform or framework to information that augments the core content for a specific platform or framework. These platform-specific `include` files live in [`plaftorm-includes/`](https://github.com/getsentry/sentry-docs/tree/master/platform-includes). We also have [platform-agnostic `include` files](https://docs.sentry.io/contributing/approach/product-docs/write-index/#includes) which are discussed in our product docs. - -[Previous\\ -\\ -SDK Documentation Structure](https://docs.sentry.io/contributing/approach/sdk-docs) - -[Next\\ -\\ -How to Write - Getting Started](https://docs.sentry.io/contributing/approach/sdk-docs/write-getting-started) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/sdk-docs/common_content.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Installation](https://docs.sentry.io/cli/installation/) - -# Installation - -## Learn about the different methods available to install \`sentry-cli\`. - -Depending on your platform, there are different methods available to install `sentry-cli`. - -## [Manual Download](https://docs.sentry.io/cli/installation/\#manual-download) - -You can find the list of releases on [the GitHub release page](https://github.com/getsentry/sentry-cli/releases/). We provide executables for Linux, OS X and Windows. It’s a single file download and upon receiving the file you can rename it to just `sentry-cli` or `sentry-cli.exe` to use it. - -## [Automatic Installation](https://docs.sentry.io/cli/installation/\#automatic-installation) - -If you are on OS X or Linux, you can use the automated downloader which will fetch the latest release version for you and install it: - -Bash - -`` - -```bash code-highlight -curl -sL https://sentry.io/get-cli/ | sh - -``` - -We do however, encourage you to pin the specific version of the CLI, so your builds are always reproducible. To do that, you can use the exact same method, with an additional version specifier: - -Bash - -`` - -```bash code-highlight -curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION="2.42.2" sh - -``` - -This will automatically download the correct version of `sentry-cli` for your operating system and install it. If necessary, it will prompt for your admin password for `sudo`. For a different installation location or for systems without `sudo` (like Windows), you can `export INSTALL_DIR=/custom/installation/path` before running this command. - -To verify it's installed correctly you can bring up the help: - -Bash - -`` - -```bash code-highlight -sentry-cli --help - -``` - -## [Installation via NPM](https://docs.sentry.io/cli/installation/\#installation-via-npm) - -There is also the option to install `sentry-cli` via npm for specialized use cases. This, for instance, is useful for build servers. The package is called `@sentry/cli` and in the post installation it will download the appropriate release binary: - -npmyarnpnpm - -`` - -```bash code-highlight -npm install @sentry/cli - -``` - -You can then find it in the `.bin` folder: - -Bash - -`` - -```bash code-highlight -./node_modules/.bin/sentry-cli --help - -``` - -In case you want to install this with npm system wide with sudo you will need to pass `--unsafe-perm` to it: - -Bash - -`` - -```bash code-highlight -sudo npm install -g @sentry/cli --unsafe-perm - -``` - -This installation is not recommended however. - -### [Downloading From a Custom Source](https://docs.sentry.io/cli/installation/\#downloading-from-a-custom-source) - -By default, this package will download sentry-cli from the CDN managed by [Fastly](https://www.fastly.com/). To use a custom CDN, set the npm config property `sentrycli_cdnurl`. The downloader will append `"/<version>/sentry-cli-<dist>"`. - -Bash - -`` - -```bash code-highlight -npm install @sentry/cli --sentrycli_cdnurl=https://mymirror.local/path - -``` - -Or add property into your `.npmrc` file ( [https://docs.npmjs.com/files/npmrc](https://docs.npmjs.com/files/npmrc)) - -Bash - -`` - -```bash code-highlight -sentrycli_cdnurl=https://mymirror.local/path - -``` - -Another option is to use the environment variable `SENTRYCLI_CDNURL`. - -Bash - -`` - -```bash code-highlight -SENTRYCLI_CDNURL=https://mymirror.local/path npm install @sentry/cli - -``` - -### [Available Installation Options](https://docs.sentry.io/cli/installation/\#available-installation-options) - -Options listed below control how `sentry-cli` install script behaves, when installed through `npm`. - -`SENTRYCLI_CDNURL`: - -If set, the script will use given URL for fetching the binary. Defaults to `https://downloads.sentry-cdn.com/sentry-cli`. - -`SENTRYCLI_USE_LOCAL`: - -If set to `1`, `sentry-cli` binary will be discovered from your `$PATH` and copied locally instead of being downloaded from external servers. It will still verify the version number, which has to match. - -`SENTRYCLI_SKIP_DOWNLOAD`: - -If set to `1`, the script will skip downloading the binary completely. - -`SENTRYCLI_SKIP_CHECKSUM_VALIDATION`: - -If set to `1`, the script will skip the checksum validation phase. You can manually verify the checksums by visiting [Build Checksums](https://docs.sentry.io/cli/installation/#build-checksums) page. - -`SENTRYCLI_NO_PROGRESS_BAR`: - -If set to `1`, the script will not display download progress bars. This is a default behavior for CI environments. - -`SENTRYCLI_LOG_STREAM`: - -If set, the script will change where it writes its output. Possible values are `stdout` and `stderr`. Defaults to `stdout`. - -## [Installation via Homebrew](https://docs.sentry.io/cli/installation/\#installation-via-homebrew) - -If you are on OS X, you can install `sentry-cli` via homebrew: - -Bash - -`` - -```bash code-highlight -brew install getsentry/tools/sentry-cli - -``` - -## [Installation via Scoop](https://docs.sentry.io/cli/installation/\#installation-via-scoop) - -If you are on Windows, you can install `sentry-cli` via [Scoop](https://scoop.sh/): - -PowerShell - -`` - -```code-highlight powershell -> scoop install sentry-cli - -``` - -## [Docker Image](https://docs.sentry.io/cli/installation/\#docker-image) - -For unsupported distributions and CI systems, we offer a Docker image that comes with `sentry-cli` preinstalled. It is recommended to use the `latest` tag, but you can also pin to a specific version. By default, the command runs inside the `/work` directory. Mount relevant project folders and build outputs there to allow `sentry-cli` to scan for resources: - -Bash - -`` - -```bash code-highlight -docker pull getsentry/sentry-cli -docker run --rm -v $(pwd):/work getsentry/sentry-cli --help - -``` - -## [Updating and Uninstalling](https://docs.sentry.io/cli/installation/\#updating-and-uninstalling) - -You can use `sentry-cli update` and `sentry-cli uninstall` to update or uninstall the `sentry-cli` binary. These commands may be unavailable in certain situations, generally when `sentry-cli` has been installed by a tool like homebrew or yarn, either directly or as a dependency of another package. In those cases, the same tool will need to be used for updating and removal. If you find that `sentry-cli update` and `sentry-cli uninstall` aren't working and you don't know how the package was installed, running `which sentry-cli` will often provide a clue as to which tool to use. - -## [Build Checksums](https://docs.sentry.io/cli/installation/\#build-checksums) - -When downloading an executable from a remote server, it's often a good practice to verify, that what has been downloaded, is in fact what we expect it to be. To make sure that this is the case, we can use checksum validation. A checksum is the value calculated from the contents of a file, in a form of hash, in our case SHA256, and it acts as the data integrity check, as it's always producing the same output, for a given input. - -Below is the table of SHA256 checksums for all available build targets that our CLI supports. To calculate the hash of a downloaded file, you can use `sha256sum` utility, which is preinstalled in OSX and most Linux distributions. - -| Filename (v2.42.2) | Integrity Checksum | -| --- | --- | -| sentry-cli-Darwin-arm64 | `sha384-0443a228db1b8fddd4cade3c9b7d8ac4ea46c9872fcbaa46014f95f6c25f7d97` | -| sentry-cli-Darwin-universal | `sha384-957bb8224e5d1304e97793ad674e5c42426fe0023dcdd937cfc2a5f8ce2e0b6a` | -| sentry-cli-Darwin-x86\_64 | `sha384-f95c7a2b7555bf41d54904cedd1be6c1b7b2765eff4e2a8a5911fda2af7fa761` | -| sentry-cli-Linux-aarch64 | `sha384-5b0eae7991817bb58ec9a039fdec38cace47c40f5133e11f553985968dc74af6` | -| sentry-cli-Linux-armv7 | `sha384-1d06e01e7e8bc42def337469626bdcc9693eba4950f225a24b6d4204c7e0a060` | -| sentry-cli-Linux-i686 | `sha384-345926403c9e3c58d39b4938eee43299966e6984fc1ba3030ad21932d498b8bf` | -| sentry-cli-Linux-x86\_64 | `sha384-7d5e69080cac84468547796a1123a2db05133dc4da5b4b042f5f1b5f32050cc5` | -| sentry-cli-Windows-i686.exe | `sha384-8a9d33e406563f497df418b3c98094b7c0534d393349fd0e94feba7f8e85c006` | -| sentry-cli-Windows-x86\_64.exe | `sha384-ef9c552f17fdd7d0043981aecf72906ddedee5d07d4699f8ee5a23103d6a2a05` | -| sentry\_cli-2.42.2-py3-none-macosx\_10\_15\_x86\_64.whl | `sha384-d8b13bd4ce2bb9a1134a9704ef29ebcee2e958977507c4e88d16873b4396a263` | -| sentry\_cli-2.42.2-py3-none-macosx\_11\_0\_arm64.whl | `sha384-144000522c7c5c45fc9d407eff0f0db9c6c03cc2bfe75e138c973834be2c9be8` | -| sentry\_cli-2.42.2-py3-none-macosx\_11\_0\_universal2.whl | `sha384-d8748fb3c594a7f0a5f1eda715170ec83043fd40296165ae88af57d10d6de9c4` | -| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_aarch64.manylinux2014\_aarch64.musllinux\_1\_2\_aarch64.whl | `sha384-aec4bd20178932721131ed6c498074bd95381fe800b8b3b6c7248a369eed1c6f` | -| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_armv7l.manylinux2014\_armv7l.musllinux\_1\_2\_armv7l.whl | `sha384-3cec8ef42a12b62e266821a25530937066647bddc0c7a18d06a12cc8a2d65b31` | -| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_i686.manylinux2014\_i686.musllinux\_1\_2\_i686.whl | `sha384-b529127ddb96105a458aa552d95b59312eb206fca69223528a98a408af4dbf2e` | -| sentry\_cli-2.42.2-py3-none-manylinux\_2\_17\_x86\_64.manylinux2014\_x86\_64.musllinux\_1\_2\_x86\_64.whl | `sha384-e4f2e81f73813035f95fd93af3d83878c9ed00461fdbf6759548996fbcf6ed23` | -| sentry\_cli-2.42.2-py3-none-win32.whl | `sha384-7b038e5463a35803cfb41dd96d29b9f441a12530df133a5a496297783b7d2c38` | -| sentry\_cli-2.42.2-py3-none-win\_amd64.whl | `sha384-f6135bb3adb50208bc083b577cdefc55b0c42cc03a1a3c234f190baba6ad22d9` | -| sentry\_cli-2.42.2.tar.gz | `sha384-c08b78fee424fec550d43795b2295140dc528ba120a3fec4301753f7b7c7aa41` | - -If you would like to verify checksums for historic versions of the `sentry-cli`, please refer to our release registry directly, which can be found at [https://release-registry.services.sentry.io/apps/sentry-cli/{version}](https://release-registry.services.sentry.io/apps/sentry-cli/latest). For example, [https://release-registry.services.sentry.io/apps/sentry-cli/1.74.4](https://release-registry.services.sentry.io/apps/sentry-cli/1.74.4). - -[Previous\\ -\\ -Sentry CLI](https://docs.sentry.io/cli) - -[Next\\ -\\ -Configuration and Authentication](https://docs.sentry.io/cli/configuration) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/installation.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Debug Information Files](https://docs.sentry.io/cli/dif/) - -# Debug Information Files - -## Debug information files allow Sentry to extract stack traces and provide more information about crash reports for most compiled platforms. Sentry's CLI can be used to validate and upload debug information files. - -Debug information files allow Sentry to extract stack traces and provide more information about crash reports for most compiled platforms. `sentry-cli` can be used to validate and upload debug information files. For more general information, refer to [_Debug Information Files_](https://docs.sentry.io/platforms/native/data-management/debug-files/). - -## [Permissions](https://docs.sentry.io/cli/dif/\#permissions) - -The `sentry-cli` requires an [Organization Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) so that Debug Information Files can be uploaded. - -Source maps, while also being debug information files, are handled differently in Sentry. For more information see [Source Maps in sentry-cli](https://docs.sentry.io/cli/releases/#sentry-cli-sourcemaps). - -## [Checking Files](https://docs.sentry.io/cli/dif/\#checking-files) - -Not all debug information files can be used by Sentry. To see if they are usable or not, you can use the `sentry-cli debug-files check` command: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files check mylibrary.so.debug - -Debug Info File Check - Type: elf debug companion - Contained debug identifiers: - > 924e148f-3bb7-06a0-74c1-36f42f08b40e (x86_64) - Contained debug information: - > symtab, debug - Usable: yes - -``` - -This will report the debug identifiers of the debug information file as well as if it passes basic requirements for Sentry. - -## [Finding Files](https://docs.sentry.io/cli/dif/\#finding-files) - -If you see in Sentry's UI that debug information files are missing, but you are not sure how to locate them, you can use the `sentry-cli debug-files find` command to look for them: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files find <identifier> - -``` - -Additionally, `sentry-cli debug-files upload` can automatically search for files in a folder or ZIP archive. - -## [Creating Source Bundles](https://docs.sentry.io/cli/dif/\#creating-source-bundles) - -To get inline source context in stack traces in the Sentry UI, `sentry-cli` can scan debug files for references to source code files, resolve them in the local file system and bundle them up. The resulting source bundle is an archive containing all source files referenced by a specific debug information file. - -This is particularly useful when building and uploading debug information files are detached. In this case, a source bundle can be created when building and can be uploaded at any later point in time with `sentry-cli debug-files upload`. - -To create a source bundle, use the `debug-files bundle-sources` command on a list of debug information files: - -Bash - -`` - -```bash code-highlight -# on the build machine: -sentry-cli debug-files bundle-sources /path/to/files... - -# at any later time: -sentry-cli debug-files upload --type sourcebundle /path/to/bundles... - -``` - -To create multiple source bundles for all debug information files, use the command on each file individually. - -Alternatively, add the `--include-sources` option to the `debug-files upload` command, which generates source bundles on the fly during the upload. This requires that the upload is performed on the same machine as the application build: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload --include-sources /path/to/files... - -``` - -This feature is supported by build tools that produce debug information files supported by Sentry such as DWARF and PDB. This applies to languages such as C/C++/C#/Swift/Rust/Zig/etc. For Java/Kotlin and other JVM languages, use one of the plugins: [Maven](https://docs.sentry.io/platforms/java/maven/) or [Gradle](https://docs.sentry.io/platforms/java/gradle/). - -## [Uploading Files](https://docs.sentry.io/cli/dif/\#uploading-files) - -Use the `sentry-cli debug-files upload` command to upload debug information files to Sentry. The command will recursively scan the provided folders or ZIP archives. Files that have already been uploaded are skipped automatically. - -We recommend uploading debug information files when publishing or releasing your application. Alternatively, files can be uploaded during the build process. See [_Debug Information Files_](https://docs.sentry.io/platforms/native/data-management/debug-files/) for more information. - -You need to specify the organization and project you are working with because debug information files work on projects. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). - -A basic debug file upload can be started with: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload -o <org> -p <project> /path/to/files... - -> Found 2 debug information files -> Prepared debug information files for upload -> Uploaded 2 missing debug information files -> File processing complete: - - PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable) - PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion) - -``` - -After the upload, Sentry analyzes the files to symbolicate future events. If you want to send a native crash to Sentry to verify correct operation, ensure that the debug files are listed in _Project Settings > Debug Files_. Alternatively, specify `--wait` in the CLI, which will block until server-side analysis is complete: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload -o <org> -p <project> --wait /path/to/files... - -> Found 2 debug information files -> Prepared debug information files for upload -> Uploaded 2 missing debug information files -> File processing complete: - - OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable) - OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion) - -``` - -### [Upload Options](https://docs.sentry.io/cli/dif/\#upload-options) - -The command's `--help` output lists and explains all options: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload --help - -``` - -### [Symbol Maps](https://docs.sentry.io/cli/dif/\#symbol-maps) - -If you are hiding debug symbols from Apple, the debug files will not contain many useful symbols. In that case, the sentry-cli upload will warn you that it needs BCSymbolMaps: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload ... -> Found 34 debug information files -> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps) - -``` - -In this case, you need the BCSymbolMaps that match your files. Typically, these are generated by the Xcode build process. Supply the `--symbol-maps` parameter and point it to the folder containing the symbol maps: - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload --symbol-maps path/to/symbolmaps path/to/debug/symbols - -``` - -### [Breakpad Files](https://docs.sentry.io/cli/dif/\#breakpad-files) - -In contrast to native debug files, Breakpad symbols discard a lot of information that is not required to process minidumps. Most notably, inline functions are not declared, such that Sentry is not able to display inline frames in stack traces. - -If possible, upload native debug files such as dSYMs, PDBs or ELF files instead of Breakpad symbols. - -## [ProGuard Mapping Upload](https://docs.sentry.io/cli/dif/\#proguard-mapping-upload) - -`sentry-cli` can be used to upload ProGuard files to Sentry; however, in most situations, you would use the [Gradle plugin](https://github.com/getsentry/sentry-android-gradle-plugin) to do that. Nevertheless, there may be situations where you would upload ProGuard files manually. For instance, when you only release some of the builds you're creating. - -You need to specify the organization and project you are working with because ProGuard files work on projects. For more information about this refer to [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects). - -The `upload-proguard` command is the one to use for uploading ProGuard files. It takes the path to one or more ProGuard mapping files and will upload them to Sentry. - -Bash - -`` - -```bash code-highlight -sentry-cli upload-proguard \ - app/build/outputs/mapping/{BuildVariant}/mapping.txt - -``` - -Since the Android Sentry SDK needs to know the UUID of the mapping file, you need to associate it with the upload. However, you first have to place that UUID into the `AndroidManifest.xml` file: - -Xml - -`` - -```code-highlight xml -<application> - <meta-data - android:name="io.sentry.proguard-uuid" - android:value="A_VALID_UUID" - /> -</application> - -``` - -The same UUID needs to be used to upload the mapping file: - -Bash - -`` - -```bash code-highlight -sentry-cli upload-proguard \ - --uuid A_VALID_UUID \ - app/build/outputs/mapping/{BuildVariant}/mapping.txt - -``` - -Additionally, you can associate the proguard mapping file to a specific release: - -Bash - -`` - -```bash code-highlight -# Additionally create an association to the release my.app.id@1.0.0+1 -sentry-cli upload-proguard \ - --uuid A_VALID_UUID \ - app/build/outputs/mapping/{BuildVariant}/mapping.txt \ - --app-id my.app.id \ - --version 1.0.0 \ - --version-code 1 - -``` - -After the upload, Sentry deobfuscates future events. To make sure that it worked, you can check _Project Settings > ProGuard_ and see if the upload mapping files are listed. - -### [Upload Options](https://docs.sentry.io/cli/dif/\#upload-options-1) - -The command's `--help` output lists and explains all options: - -Bash - -`` - -```bash code-highlight -sentry-cli upload-proguard --help - -``` - -## [JVM Source Bundles](https://docs.sentry.io/cli/dif/\#jvm-source-bundles) - -If you're using a build tool we don't support, or you prefer not to use Sentry's build tool plugins, you'll need to upload source bundle files manually. - -See the build tool plugins we currently support here: - -- [Android](https://docs.sentry.io/platforms/android/enhance-errors/source-context/) -- [Java](https://docs.sentry.io/platforms/java/source-context/) - -You can also upload ProGuard files manually with `sentry-cli` for any JVM-based language like Java or Kotlin. - -Before you can upload source files, you must configure the Sentry CLI with the organization and project you are uploading bundle files for. See the CLI docs on [Working with Projects](https://docs.sentry.io/cli/configuration/#sentry-cli-working-with-projects) to learn how to do this. - -### [Creating a Source Bundle](https://docs.sentry.io/cli/dif/\#creating-a-source-bundle) - -Run the `debug-files bundle-jvm` command to create a source bundle for a source directory. - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files bundle-jvm \ - --output some/dir \ - --debug-id A_VALID_UUID \ - path/to/source/dir - -``` - -You must provide the UUID of the source bundle for the Java/Android SDK to send. More details can be found in the [Source Context](https://docs.sentry.io/platforms/java/source-context/#manually-uploading-source-context) docs for Java and the [Source Context](https://docs.sentry.io/platforms/android/enhance-errors/source-context/#manually-uploading-source-context) docs for Android. - -### [Uploading a Source Bundle](https://docs.sentry.io/cli/dif/\#uploading-a-source-bundle) - -The `debug-files upload` command allows you to upload the source bundle you created to Sentry. - -Bash - -`` - -```bash code-highlight -sentry-cli debug-files upload \ - --type jvm \ - output/path/of/bundle-jvm/command - -``` - -After the upload, Sentry will attach Source Context to future events. - -To make sure these steps worked, check **Project Settings > Debug Files** in Sentry.io to see if the uploaded source bundle files are listed. - -[Previous\\ -\\ -Release Management](https://docs.sentry.io/cli/releases) - -[Next\\ -\\ -Sending Events](https://docs.sentry.io/cli/send-event) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/dif.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Search](https://docs.sentry.io/concepts/search/) -- [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) -- [Event Properties](https://docs.sentry.io/concepts/search/searchable-properties/events/) - -# Event Properties - -## Learn more about searchable event properties. - -Events are the underlying event data captured using Sentry SDKs — that is, errors and transactions. - -You can search by event properties in the following [sentry.io](https://sentry.io/) pages: - -- Discover - in the query builder (depending on the dataset selection) -- Dashboards - within the widget builder (depending on dataset selection) -- Performance - only in transaction summaries -- Issues - as indicated in the list below -- Alerts - when creating a metric alert - -Please note that in Alerts only a limited number of properties are available for [filtering transaction events](https://docs.sentry.io/product/alerts/create-alerts/metric-alert-config/#tags--properties). - -When searching on event properties within the **Issues** page, the search will return any issue that has _one or more events_ matching the supplied event properties filter. - -## [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/events/\#searchable-properties) - -Below is a list of keys and tokens that can be used in the event search. - -### [`apdex(threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#apdexthreshold) - -Returns results with the [Apdex score](https://docs.sentry.io/product/insights/overview/metrics/#apdex) that you entered. Values must be between `0` and `1`. Higher apdex values indicate higher user satisfaction. - -- **Type:** number - -### [`app.in_foreground`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#appin_foreground) - -Indicates if the app is in the foreground or background. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`avg(field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#avgfield) - -Returns results with matching averages for the field selected. The field can be either a number or a duration. Typically used with a comparison operator. - -- **Type:** matches field - -### [`count_if(column,operator,value)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_ifcolumnoperatorvalue) - -Returns results with a matching count that satisfy the condition passed to the parameters of the function. - -- **Type:** number - -### [`count_miserable(field,threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_miserablefieldthreshold) - -Returns results with a matching count of unique instances of the field that fall above the miserable threshold. - -- **Type:** number - -### [`count_unique(field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_uniquefield) - -Returns results with a matching count of the unique instances of the field entered. - -- **Type:** number - -### [`count_web_vitals(vital,threshold)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count_web_vitalsvitalthreshold) - -Returns results with a matching count that meet a Web Vitals quality threshold ( `poor`, `meh`, `good`, or `any`). - -- **Type:** number - -### [`count()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#count) - -Returns results with a matching count. (Same as `timesSeen` in issue search.) Doesn't take a parameter. - -- **Type:** number - -### [`culprit`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#culprit) - -Deprecated - -- **Type:** string - -### [`device.arch`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicearch) - -CPU architecture - -- **Type:** string - -### [`device.battery_level`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicebattery_level) - -If the device has a battery, this can be a floating point value defining the battery level (in the range 0-100). - -- **Type:** string - -### [`device.brand`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicebrand) - -Brand of the device - -- **Type:** string - -### [`device.charging`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicecharging) - -Whether the device was charging or not. Not a boolean. - -- **Type:** string - -### [`device.class`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceclass) - -The estimated performance class of the client device, estimated `high`, `medium`, or `low`. For more details, see the [Device Classification](https://docs.sentry.io/concepts/search/searchable-properties/events/#device-classification) section below. - -- **Type:** string - -### [`device.family`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicefamily) - -Family of the device. Typically, the common part of a model name across generations. For example, iPhone, Samsung Galaxy. - -- **Type:** string - -### [`device.locale`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicelocale) - -Deprecated - -- **Type:** string - -### [`device.name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicename) - -Details of the device - -- **Type:** string - -### [`device.online`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceonline) - -Whether the device was online or not. A string that is either `True` or `False`. - -- **Type:** string - -### [`device.orientation`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceorientation) - -Describes the orientation of the device and can be either `portrait` or `landscape`. - -- **Type:** string - -### [`device.screen_density`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_density) - -Device screen density in pixels. - -- **Type:** string - -### [`device.screen_dpi`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_dpi) - -Number of dots per inch of the device screen. - -- **Type:** string - -### [`device.screen_height_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_height_pixels) - -Device screen height in pixels. - -- **Type:** string - -### [`device.screen_width_pixels`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicescreen_width_pixels) - -Device screen width in pixels. - -- **Type:** string - -### [`device.simulator`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#devicesimulator) - -Indicates whether this device is a simulator or a real device. A string that is either `True` or `False`. - -- **Type:** string - -### [`device.uuid`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#deviceuuid) - -Deprecated - -- **Type:** UUID - -### [`dist`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#dist) - -Distinguishes build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. - -- **Type:** string - -### [`environment`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#environment) - -Refers to your code deployment naming convention. For example, _development_, _testing_, _staging_ and so on. [Learn more](https://docs.sentry.io/product/sentry-basics/environments/).In some pages of [sentry.io](https://sentry.io/), you filter on environment using a dropdown. - -- **Type:** string - -### [`epm()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#epm) - -Returns results with a matching events-per-minute count. Doesn't take a parameter. - -- **Type:** number - -### [`eps()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#eps) - -Returns results with a matching events-per-second count. Doesn't take a parameter. - -- **Type:** number - -### [`error.handled`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorhandled) - -Indicates whether the user has handled the exception — for example, using try...catch. An error is considered handled if all stack traces handle the error. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`error.main_thread`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errormain_thread) - -Indicates if the error occurred on the main thread. Values are `1/0` or `true/false` - -- **Type:** boolean - -### [`error.mechanism`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errormechanism) - -An object describing the mechanism that created this exception. - -- **Type:** array - -### [`error.type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errortype) - -The type of exception. For example, `ValueError`. - -- **Type:** array - -### [`error.unhandled`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorunhandled) - -The inversion of `error.handled`. - -- **Type:** boolean - -### [`error.value`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#errorvalue) - -Original value of a field that causes or exhibits the error. - -- **Type:** array - -### [`event.type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#eventtype) - -Type of the event (transaction, error, default, csp, and so on). The transaction type is unavailable in **Issues**. - -- **Type:** string - -### [`failure_count()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#failure_count) - -Returns results with a matching count of events with a `transaction.status` value that's in the list of failing ones. Values can be: `ok`, `cancelled`, `unknown`. Doesn't take a parameter. - -- **Type:** number - -### [`failure_rate()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#failure_rate) - -Returns results with a matching rate of failing transactions — that is, `failure_count()` divided by the `count()` (total count). Doesn't take a parameter. - -- **Type:** number - -### [`geo.city`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#geocity) - -Full name of the city - -- **Type:** string - -### [`geo.country_code`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#geocountry_code) - -ISO 3166-1 country code - -- **Type:** string - -### [`geo.region`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#georegion) - -Full name of the country - -- **Type:** string - -### [`has`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#has) - -Returns results with the defined tag or field, but not the value of that tag or field. For example, entering `has:user` would find events with the `user` tag. - -- **Type:** error - -### [`http.method`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpmethod) - -HTTP method of the [request](https://develop.sentry.dev/sdk/data-model/event-payloads/request/) that created the event. - -- **Type:** string - -### [`http.referer`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpreferer) - -Identifies the web page from which the resource was requested. - -- **Type:** string - -### [`http.status_code`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpstatus_code) - -HTTP status code, which indicates whether a response was successful. For example, `200` or `404`. - -- **Type:** string - -### [`http.url`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#httpurl) - -Full URL of the request that caused the error, but without any parameters - -- **Type:** string - -### [`id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#id) - -The event id. In **Issues**, use only the ID value without the `id` key. - -- **Type:** UUID - -### [`issue`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#issue) - -The short issue code, for example `SENTRY-ABC`. - -- **Type:** string - -### [`last_seen()`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#last_seen) - -Datetime when the event was last seen. Equivalent to `max(timestamp)`. Doesn't take a parameter. - -- **Type:** datetime - -### [`level`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#level) - -Severity of the event (such as: fatal, error, warning). Always set to info for transactions. - -- **Type:** string - -### [`location`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#location) - -Location where the error happened. - -- **Type:** string - -### [`max(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#maxnumeric-field) - -Returns results with a matching maximum value for the field entered. - -- **Type:** matches field - -### [`measurements.app_start_cold`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsapp_start_cold) - -A [cold start](https://docs.sentry.io/product/insights/mobile/mobile-vitals/app-starts/) refers to when the app launches for the first time after a reboot or update. The app is not in memory and no process exists. - -- **Type:** duration - -### [`measurements.app_start_warm`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsapp_start_warm) - -A [warm start](https://docs.sentry.io/product/insights/mobile/mobile-vitals/app-starts/) refers to when the app has already launched at least once and is partially in memory. For instance, the user backs out of your app, but then re-launches it. The process may have continued to run, but the app must recreate the activity from scratch. - -- **Type:** duration - -### [`measurements.cls`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementscls) - -[Cumulative Layout Shift (CLS)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#cumulative-layout-shift-cls) is the sum of individual layout shift scores for every unexpected element shift during the rendering process. - -- **Type:** number - -### [`measurements.fcp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfcp) - -[First Contentful Paint (FCP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-contentful-paint-fcp) measures the time for the first content to render in the viewport. - -- **Type:** duration - -### [`measurements.fid`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfid) - -[First Input Delay (FID)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-input-delay-fid) measures the response time when the user tries to interact with the viewport. - -- **Type:** duration - -### [`measurements.fp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsfp) - -[First Paint (FP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#first-paint-fp) measures the amount of time the first pixel takes to appear in the viewport, rendering any visual change from what was previously displayed. - -- **Type:** duration - -### [`measurements.frames_frozen`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_frozen) - -[Slow and frozen frames](https://docs.sentry.io/product/insights/mobile/mobile-vitals/#slow-and-frozen-frames) measure the responsiveness of your app. - -- **Type:** number - -### [`measurements.frames_frozen_rate`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_frozen_rate) - -Returns results with a matching rate of frozen frames. That is, `measurements.frames_frozen` divided by the `measurements.frames_total`. - -- **Type:** number - -### [`measurements.frames_slow`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_slow) - -[Slow and frozen frames](https://docs.sentry.io/product/insights/mobile/mobile-vitals/#slow-and-frozen-frames) measure the responsiveness of your app. - -- **Type:** number - -### [`measurements.frames_slow_rate`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_slow_rate) - -Returns results with a matching rate of slow frames. That is, `measurements.frames_slow` divided by the `measurements.frames_total`. - -- **Type:** number - -### [`measurements.frames_total`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsframes_total) - -Returns results with a matching total number of frames. - -- **Type:** number - -### [`measurements.lcp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementslcp) - -[Largest Contentful Paint (LCP)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#largest-contentful-paint-lcp) measures the render time for the largest content to appear in the viewport. - -- **Type:** duration - -### [`measurements.stall_count`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_count) - -A [stall](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is when the JavaScript event loop takes longer than expected to complete. Only applies to React Native. - -- **Type:** number - -### [`measurements.stall_longest_time`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_longest_time) - -The [longest stall time](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is the time, in milliseconds, of the longest event loop stall. Only applies to React Native. - -- **Type:** duration - -### [`measurements.stall_percentage`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_percentage) - -Stall percentage is equal to the `stall_total_time` divided by the `transaction.duration`. Only applies to React Native. - -- **Type:** number - -### [`measurements.stall_total_time`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsstall_total_time) - -The [total stall time](https://docs.sentry.io/platforms/react-native/tracing/instrumentation/automatic-instrumentation/#stall-tracking) is the total combined time, in milliseconds, of all stalls. Only applies to React Native. - -- **Type:** duration - -### [`measurements.ttfb`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsttfb) - -[Time To First Byte (TTFB)](https://docs.sentry.io/product/insights/web-vitals/web-vitals-concepts/#time-to-first-byte-ttfb) measures the time that it takes for a user's browser to receive the first byte of page content. - -- **Type:** duration - -### [`measurements.ttfb.requesttime`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#measurementsttfbrequesttime) - -The time between start of the request and start of the response (see [diagram](https://web.dev/ttfb/#what-is-ttfb)). - -- **Type:** duration - -### [`message`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#message) - -Returns errors with the matching message or transactions with matching transaction name. Also matches on any message containing the supplied value.Searching `message:undefined` will match an event with a message of `undefined is not an object`. Raw text searches (searches without the `message` key) are also checked against this field. For errors, the message can be a concatenatenation of elements, so searches might include unexpected results. - -- **Type:** string - -### [`min(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#minnumeric-field) - -Returns results with a matching minimum value for the field entered. - -- **Type:** matches field - -### [`os.build`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osbuild) - -The internal build revision of the operating system. - -- **Type:** string - -### [`os.kernel_version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#oskernel_version) - -The independent kernel version string. This is typically the entire output of the `uname` syscall. - -- **Type:** string - -### [`os.distribution_name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osdistribution_name) - -The Linux distribution name. This maps to `ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). - -- **Type:** string - -### [`os.distribution_version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#osdistribution_version) - -The Linux distribution version. This maps to `VERSION_ID` in [`/etc/os-release/`](https://www.freedesktop.org/software/systemd/man/latest/os-release.html). - -- **Type:** string - -### [`percentile(field,level)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#percentilefieldlevel) - -Returns results with an approximate percentile of the field to the level. The level can be between `0` and `1`. For example, if you wanted to find the 50th percentile of transaction durations, you would enter `percentile(transaction.duration, 0.5)`. - -- **Type:** number - -### [`platform`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#platform) - -Name of the platform. This defaults to `other` and is only a property for platforms from this list: `as3`, `c`, `cfml`, `cocoa`, `csharp`, `elixir`, `go`, `groovy`, `haskell`, `java`, `javascript`, `native`, `node`, `objc`, `other`, `perl`, `php`, `python`, `ruby` - -- **Type:** string - -### [`project`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#project) - -The name of the project. In some pages of [sentry.io](https://sentry.io/), you can also filter on project using a dropdown. - -- **Type:** string - -### [`project.id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#projectid) - -The id of the project. - -- **Type:** number - -### [`pXY(duration field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#pxyduration-field) - -Returns results with an approximate percentile of the field. Replace "XY" with 50, 75, 95, 99, or 100. For example, if you wanted to find the 50th percentile of transaction durations, you would enter `p50(transaction.duration)`. - -- **Type:** number - -### [`release`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#release) - -A release is a version of your code deployed to an environment. You can create a token with an exact match of the version of a release, or `release:latest` to pick the most recent release. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/#latest-release). - -- **Type:** string - -### [`release.build`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasebuild) - -The number that identifies an iteration of your app. For example, `CFBundleVersion` on iOS or `versionCode` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** number - -### [`release.package`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasepackage) - -The unique identifier of the project/app. For example, `CFBundleIdentifier` on iOS or `packageName` on Android. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -### [`release.stage`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releasestage) - -The usage your release is seeing relative to other releases. Values can be `adopted`, `low`, or `replaced`. [Learn more](https://docs.sentry.io/product/releases/health/#adoption-stages). - -- **Type:** string - -### [`release.version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#releaseversion) - -A shorter version of the name; name without the package or short version of the hash. [Learn more](https://docs.sentry.io/product/releases/usage/sorting-filtering/). - -- **Type:** string - -### [`sdk.name`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sdkname) - -Name of the Sentry SDK that sent the event. - -- **Type:** string - -### [`sdk.version`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sdkversion) - -Version of the Sentry SDK that sent the event. - -- **Type:** string - -### [`spans.browser`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansbrowser) - -Cumulative browser time for a transaction, based on the span operations. - -- **Type:** duration - -### [`spans.db`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansdb) - -Cumulative db time for a transaction, based on span operations. - -- **Type:** duration - -### [`spans.http`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spanshttp) - -Cumulative http time for a transaction, based on span operations. - -- **Type:** duration - -### [`spans.resource`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansresource) - -Cumulative resource time for a transaction, based on span operations. - -- **Type:** duration - -### [`spans.ui`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#spansui) - -Cumulative UI time for a transaction, based on span operations. - -- **Type:** duration - -### [`stack.abs_path`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackabs_path) - -The absolute path to the source file. In events, this is an array; in issues, this is a single value. - -- **Type:** array, single value - -### [`stack.colno`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackcolno) - -Column number of the call, starting at 1. - -- **Type:** array - -### [`stack.filename`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackfilename) - -The path to the source file relative to the project root directory. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.function`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackfunction) - -Name of the function being called. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.in_app`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackin_app) - -Indicates whether a frame is related to the execution of the relevant code in the stack trace. For example, the frames that might power the framework’s web server of your app are probably not relevant. However, calls to the framework’s library once you start handling code likely are relevant. Values can be `1` (true) or `0` (false). - -- **Type:** array - -### [`stack.lineno`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stacklineno) - -Line number of the call, starting at 1. - -- **Type:** array - -### [`stack.module`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackmodule) - -Platform-specific module path. For example, `sentry.interfaces.Stacktrace`. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`stack.package`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#stackpackage) - -The "package" the frame was contained in. Depending on the platform, this can be different things. For C#, it can be the name of the assembly. For native code, it can be the path of the dynamic library or something else. In events, this is an array. In issues, this is a single value. - -- **Type:** array, single value - -### [`sum(numeric field)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#sumnumeric-field) - -Returns results with a matching total value for the the field entered. - -- **Type:** matches field - -### [`timestamp`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestamp) - -The finish timestamp of the transaction. Returns events with matching datetime. - -- **Type:** datetime - -### [`timestamp.to_day`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestampto_day) - -Timestamp rounded down to the nearest day. - -- **Type:** datetime - -### [`timestamp.to_hour`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#timestampto_hour) - -Timestamp rounded down to the nearest hour. - -- **Type:** datetime - -### [`title`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#title) - -Title of the error or the transaction name. - -- **Type:** string - -### [`trace`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#trace) - -A trace represents the record of the entire operation you want to measure or track — like page load, searched using the UUID generated by Sentry’s SDK. - -- **Type:** UUID - -### [`trace.parent_span`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#traceparent_span) - -Span ID of the parent to the current transaction. This is null if the transaction is root. - -- **Type:** UUID - -### [`trace.span`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#tracespan) - -Span ID of the root span of the root transaction in the event. - -- **Type:** UUID - -### [`transaction`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transaction) - -For [transactions](https://docs.sentry.io/product/insights/overview/transaction-summary/#what-is-a-transaction), the name of the transaction. For errors, the name of the associated transaction. - -- **Type:** string - -### [`transaction.duration`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionduration) - -Duration, in milliseconds, of the transaction. - -- **Type:** duration - -### [`transaction.op`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionop) - -Short code identifying the [type of operation](https://develop.sentry.dev/sdk/performance/span-operations/) the span is measuring. - -- **Type:** string - -### [`transaction.status`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#transactionstatus) - -Describes the status of the span/transaction. Check out our [Transaction Payloads documentation](https://develop.sentry.dev/sdk/data-model/event-payloads/transaction/) for all possible statuses. - -- **Type:** string - -### [`unreal.crash_type`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#unrealcrash_type) - -The [Unreal Crash Context Type](https://docs.unrealengine.com/4.27/en-US/API/Runtime/Core/GenericPlatform/ECrashContextType/) - -- **Type:** string - -### [`user_misery(number)`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#user_miserynumber) - -Returns transactions with the defined user misery value. [User Misery](https://docs.sentry.io/product/insights/overview/metrics/#user-misery) is a user-weighted performance metric that counts the number of unique users who were frustrated; "frustration" is measured as a response time four times the satisfactory response time threshold (in milliseconds). It highlights transactions that have the highest impact on users. - -- **Type:** number - -### [`user.display`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userdisplay) - -In order, the first available user field available: email, then username, ID, and then IP address. - -- **Type:** string - -### [`user.email`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#useremail) - -An alternative, or addition, to the username. Sentry is aware of email addresses and can therefore display things such as Gravatars and unlock messaging capabilities. - -- **Type:** string - -### [`user.id`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userid) - -Application-specific internal identifier for the user. - -- **Type:** string - -### [`user.ip`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userip) - -User's IP address. Sentry uses the IP address as a unique identifier for unauthenticated users. - -- **Type:** string - -### [`user.username`](https://docs.sentry.io/concepts/search/searchable-properties/events/\#userusername) - -Username, which is typically a better label than the `user.id`. - -- **Type:** string - -[Previous\\ -\\ -Issue Properties](https://docs.sentry.io/concepts/search/searchable-properties/issues) - -[Next\\ -\\ -Span Properties](https://docs.sentry.io/concepts/search/searchable-properties/spans) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/search/searchable-properties/events.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Authentication](https://docs.sentry.io/organization/authentication/) -- [Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso/) -- [Azure Active Directory SSO](https://docs.sentry.io/organization/authentication/sso/azure-sso/) - -# Azure Active Directory SSO - -## Set up Azure Active Directory single sign-on (SSO) on Sentry. - -## [Installation](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#installation) - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SAML configuration values. - -01. Log in to the [Azure portal](https://portal.azure.com/). - -02. Under "Manage Azure Active Directory" (the picture of the shield), click "View". This takes you to the **Organization Overview** page. - -03. If you don't require a permission group for Sentry, skip to Step 5. - -04. In the search bar, search for "Groups" then navigate to it. From there, create a new group, add an owner and members to the group. Set "Group type" to Office 365. For more details about group creation, see the [Azure docs](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-groups-create-azure-portal). - -05. Return to the **Overview** page. In the search bar, enter `Enterprise Applications`, then navigate to it. Click "+ New application". Search for `Sentry` to create the application. - - [![Sentry in Azure Gallery](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-search-sentry-3NIHTCLW.png%232356x1102&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-search-sentry-3NIHTCLW.png) - -06. Once the application is created, you'll be directed to **Sentry - Overview**. - - [![Sentry Overview](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-sentry-overview-GRUHFUC4.png%231500x741&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-sentry-overview-GRUHFUC4.png) - -07. Click on "1. Assign users and groups", then "+ Add user". Add yourself and the group you've created to the Sentry app. Click "Assign". - -08. Navigate back to **Overview**, click on "2. Set up single sign-on" and then select SAML as your single sign-on method. - -09. For Section (1), labeled "Basic SAML Configuration", enter the following data in each line and save your changes. - - - - Identifier (Entity ID): `https://sentry.io/saml/metadata/YOUR_ORG_SLUG/` Ensure that the URL includes a trailing slash to prevent Azure from throwing a misconfiguration error (AADSTS650056). - - - Reply URL (Assertion Consumer Service URL): `https://sentry.io/saml/acs/YOUR_ORG_SLUG/` - - - Sign on URL: `https://sentry.io/auth/login/YOUR_ORG_SLUG/` - - - Relay State: `https://sentry.io/organizations/YOUR_ORG_SLUG/` - - - Logout URL: `https://sentry.io/saml/sls/YOUR_ORG_SLUG/` - - -[![SAML Configuration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-basic-saml-configuration-MXFOQTUE.png%231500x369&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-basic-saml-configuration-MXFOQTUE.png) - -10. In Section (3), labeled "SAML Signing Certificate", copy the "App Federation Metadata URL". - - [![SAML Signing Certificate](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-saml-signing-certificate-SLHMLERE.png%232788x889&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-saml-signing-certificate-SLHMLERE.png) - -11. Navigate to your **Org Settings > Auth** (or go to `https://sentry.io/settings/YOUR_ORG_SLUG/auth/`) and click on "Configure" for Active Directory. - -12. Paste the App Federation Metadata URL from above and click "Get Metadata". - -13. In the next page, enter the following keys in their respective fields to map the attributes from AzureAD to Sentry, and then save them. - - - - IdP User ID: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` - - - User Email: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` - - - First Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` - - - Last Name: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` - - -For more details about mappings for custom configs, see [The Role of Claims](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/technical-reference/the-role-of-claims). - -[![Map Identity with provider attributes](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-map-identity-provider-attributes-UPSWPTFR.png%231500x1414&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-map-identity-provider-attributes-UPSWPTFR.png) - -14. Sentry will attempt to authenticate and link your account with Azure. After successful authentication, you'll be redirected to Sentry's SSO configuration page, where you can take the following actions: - - - You can share the "Login URL" value, which will be used for SP-initiated SSO, with the users in your organization. - - - Scroll down to the bottom and ensure that "Require SSO" is checked if you want to enforce logging in with Azure Active Directory. - - - Set a "Default Role" for new SSO users. Selecting "Member" should cover most use cases. - - - If you made changes, click "Save Settings" to complete your setup. - -## [SCIM Integration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#scim-integration) - -This feature is only available if your organization is on a Business or Enterprise plan; it is not available on Trial plans. - -If you change your organization slug, you'll need to make the same update in the steps where you enter the SCIM configuration values. - -Sentry users can manage provisioning using Azure with SCIM. You'll need to have Azure SSO set up and configured for your organization already. Sentry supports User and Group provisioning with Azure. - -### [Sentry Configuration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#sentry-configuration) - -1. Sign in to [sentry.io](https://sentry.io/). Select **Settings > Auth** - -[![Sentry Okta SCIM Auth Page](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-settings-auth-I7AT2EWD.png%232688x1428&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-settings-auth-I7AT2EWD.png) - -2. Under General Settings select "Enable SCIM", then "Save Settings" - -[![Sentry Enable SCIM Instruction](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-enable-sentry-7WE3LMJ5.png%231542x796&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-enable-sentry-7WE3LMJ5.png) - - - Sentry will display "SCIM Information" that contains your Auth Token and SCIM Base URL. - - [![SCIM Credentials Fields](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fscim-sentry-fields-Q4U5PUUE.png%231504x598&w=3840&q=75)](https://docs.sentry.io/mdx-images/scim-sentry-fields-Q4U5PUUE.png) - -### [Azure Configuration](https://docs.sentry.io/organization/authentication/sso/azure-sso/\#azure-configuration) - -1. Log in to the [Azure portal](https://portal.azure.com/). - -2. In your Azure portal, navigate to **Enterprise applications** in the sidebar. - -3. Select the existing Sentry application. - -4. Select "Provisioning" from the "Manage" menu. [![Azure Provisioning Selection](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-scim-provisioning-5EP5PCMZ.png%23400x422&w=828&q=75)](https://docs.sentry.io/mdx-images/azure-scim-provisioning-5EP5PCMZ.png) - -5. Set "Provisioning Mode" to "Automatic". - -6. Use the values from your Sentry SCIM configuration to enter your SCIM URL in the "Tenant URL" field and your SCIM Auth token in the "Secret Token" field. - -7. Select "Test Connection" and wait for the message that confirms that the credentials are authorized to enable provisioning. - -[![Azure Test SCIM Connection](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fazure-scim-test-connection-MGBJPVJF.png%231484x1078&w=3840&q=75)](https://docs.sentry.io/mdx-images/azure-scim-test-connection-MGBJPVJF.png) - - -We recommend that you select the option to "Send an email notification when a failure occurs". - -As a result of these changes, users who are assigned will be sent an invitation email. When a user is un-assigned, their membership object in Sentry will be deleted. - -You can use Use Group Provisioning to sync and assign groups in Azure; they will be reflected in Sentry teams. - -Please see the [Microsoft AD tutorial](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/sentry-provisioning-tutorial) for further documentation on Azure provisioning setup. If you are using a custom enterprise application, you **must** follow the instructions for only enabling attribute mappings that Sentry supports (Step 5). - -[Previous\\ -\\ -Single Sign-On (SSO)](https://docs.sentry.io/organization/authentication/sso) - -[Next\\ -\\ -Okta SSO](https://docs.sentry.io/organization/authentication/sso/okta-sso) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/authentication/sso/azure-sso.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Issue Grouping](https://docs.sentry.io/concepts/data-management/event-grouping/) -- [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/) - -# Stack Trace Rules - -## Learn how to use stack trace rules to group incoming events based on matchers. - -This feature is only applicable for [error issues](https://docs.sentry.io/product/issues/issue-details/error-issues/) with debug information files, excluding source maps. Other categories of issues (such as [performance issues](https://docs.sentry.io/product/issues/issue-details/performance-issues/) or [replay issues](https://docs.sentry.io/product/issues/issue-details/replay-issues/)) do not support this feature. - -Stack trace rules improve issue tracking by ensuring accurate grouping and better classification of stack frames as in-app or system. This helps focus on relevant code, reduces noise, and minimizes false positives. By tailoring rules to your project, you can streamline debugging and maintain consistency across teams or multiple applications. - -When you set stack trace rules (previously known as _grouping enhancements_) for grouping in Sentry, they influence the data that's fed into the grouping algorithm. These rules can be configured on a per-project basis by going to your project settings and then clicking on "Issue Grouping". - -Here are a few things to note about stack trace rules: - -- Each rule is written on a single line. -- Rules consist of one or more match expressions followed by one or more actions triggered when all expressions match. -- Rules are applied sequentially, from top to bottom, across all frames in the stack trace. - -In addition, the stack trace rules using the below matchers and actions can also be applied to incoming profiles to improve frame classification (in-app vs system, for example). - -Allowed Matchers: - -- `stack.abs_path` -- `stack.module` -- `stack.function` -- `stack.package` - -Allowed Actions: - -- `+app` -- `-app` - -The syntax for stack trace rules is similar to: - -Enhancement Rules - -`` - -```bash code-highlight -matcher-name:expression other-matcher:expression ... action1 action2 ... - -``` - -If you want to negate the match, prefix the expression with an exclamation mark ( `!`). If a line is prefixed with a hash ( `#`), it's ignored and treated as a comment. - -The following is a practical example of how this looks: - -Enhancement Rules - -`` - -```bash code-highlight -# mark all functions in the std namespace to be outside the app -family:native stack.function:std::* -app - -# mark all code in node modules not to be in app -stack.abs_path:**/node_modules/** -app - -# remove all generated javascript code from all grouping -stack.abs_path:**/generated/**.js -group - -``` - -## [Matchers](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#matchers) - -Multiple matchers can be defined in a line. The following matchers are available: - -### [`family`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#family) - -Matches on the general platform family, which currently includes `javascript`, `native` and `other`. Comma separate rules to apply them to multiple platforms. - -Match multipleMatch only JavaScriptMatch only native - -`` - -```bash code-highlight -family:javascript,native stack.abs_path:**/generated/** -group - -``` - -### [`stack.abs_path`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackabs_path) - -alias: `path` - -This matcher is case insensitive with Unix glob behavior on a path in a stack trace. The path separators are normalized to `/`. As a special rule, if the filename is relative, it still matches on `**/`. - -Enhancement Rules - -`` - -```bash code-highlight -# match on all files under `project` with a `.c` extension -stack.abs_path:**/project/**.c +app - -# matches on vendor/foo without sub folders -stack.abs_path:**/vendor/foo/*.c -app - -# matches on `foo.gen.c` as well as `foo/bar.gen.c`. -stack.abs_path:**/*.gen.c -group - -``` - -### [`stack.module`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackmodule) - -alias: `module` - -Module is similar to `path` but matches on the `module`. This is not used for Native but it is used for JavaScript, Python, and similar platforms. Matches are case-sensitive, and normal globbing is available. Note that modules are not packages, which can be confusing for Native environments. - -### [`stack.function`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackfunction) - -alias: `function` - -Matches on a function in a stack trace, and is case-sensitive with normal globbing. - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:myproject_* +app -stack.function:malloc -group - -``` - -### [`stack.package`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stackpackage) - -alias: `package` - -Matches on a package in a stack trace. The package is the container that contains a function or module. This is a `.jar`, a `.dylib` or similar. The same matching rules as for `path` apply. For example, this is typically an absolute path. - -Enhancement Rules - -`` - -```bash code-highlight -stack.package:**/libcurl.dylib -group - -``` - -### [`app`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#app) - -Matches on the current state of the in-app flag of a stack trace frame. `yes` means the frame is in-app, `no` means it's not. - -### [`category`](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#category) - -Matches on a [built-in](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/#built-in-categories) or a user-defined frame category. See [variable actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/#variable-actions) on how to set a category. - -Category Match - -`` - -```bash code-highlight -category:telemetry -group - -``` - -#### [Built-in Categories](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#built-in-categories) - -Frame categorization is heavily used by our newest grouping algorithm. You can match on a variety of categories, including: - -- `system` \- detected system libraries -- `std` \- detected standard libraries -- `ui` \- UI frameworks -- `driver` \- graphics drivers, and so on -- `telemetry` \- crash reporting and analytics frameworks - -See [our source code](https://github.com/getsentry/sentry/blob/master/src/sentry/grouping/enhancer/enhancement-configs/mobile%402021-04-02.txt) for a full list of built-in categories. - -### [Matching Sibling Frames](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#matching-sibling-frames) - -If information about the surrounding frames is necessary to apply a rule to a frame, use caller/callee matching syntax. For example: - -Sibling matches - -`` - -```bash code-highlight -# Ignore in-app frames if they are called by telemetry -[ category:telemetry ] | app:yes -group - -# Ignore system frames if they call app frames -category:system | [ app:yes ] -group - -``` - -## [Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#actions) - -There are two types of **actions**: flag and variables setting. - -### [Flag Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#flag-actions) - -A _flag_ identifies the action to be taken if all matchers match, and it uses these prefixes: - -- `+` sets the flag -- `-` unsets the flag -- `^` applies to frames above the matching frame (toward the crash) -- `v` applies to frames below the matching frame (away from the crash) - -As an example, `-group ^-group` removes the matching frame and all frames above it from the grouping. - -- `app`: marks or unmarks a frame in-app -- `group`: adds or removes a frame from grouping - -### [Variable Actions](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#variable-actions) - -A limited set of _variables_ can be defined ( `variable=value`): - -- `max-frames`: Sets the total number of frames to be considered for grouping. The default is `0`, which means "all frames". If set to `3`, only the top three frames are considered. - -### [Example](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#example) - -Enhancement Rules - -`` - -```bash code-highlight -stack.abs_path:**/node_modules/** -group -stack.abs_path:**/app/utils/requestError.jsx -group -stack.abs_path:**src/getsentry/src/getsentry/** +app - -family:native max-frames=3 - -stack.function:fetchSavedSearches v-group -stack.abs_path:**/app/views/**.jsx stack.function:fetchData ^-group - -family:native stack.function:SpawnThread v-app -app -family:native stack.function:_NSRaiseError ^-group -app -family:native stack.function:std::* -app -family:native stack.function:core::* -app - -``` - -## [Recommendations](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#recommendations) - -These recommendations will greatly improve your out-of-the-box grouping experience. - -### [Mark in-app Frames](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#mark-in-app-frames) - -To proactively improve your experience, help Sentry determine which frames in your stack trace are "in-app" (part of your own application) and which are not. The SDK defines the default rules, but in many cases, this can be improved on the server as well. In particular, for languages where server-side processing is necessary (for example, Native C, C++, or JavaScript), it's better to override this on the server. - -For instance, the following marks all frames that are below a specific C++ namespace are in-app: - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:myapplication::* +app - -``` - -See [in-app frames for Apple](https://docs.sentry.io/platforms/apple/usage/in-app-frames/) to find out how the `sentry-cocoa` SDK marks frames as in-app. - -#### [Stack Trace Rules](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stack-trace-rules) - -The following marks frames from libdispatch starting with `_dispatch_` as `inApp`. - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:_dispatch_* +app - -``` - -You can also achieve the same result by marking other frames "not in-app." However, if that's the case, you should ensure that first all frames are set to "in-app" to override the defaults: - -Enhancement Rules - -`` - -```bash code-highlight -app:no +app -stack.function:std::* -app -stack.function:boost::* -app - -``` - -You need to force all frames to be in-app first because there might already have been some defaults set by the client SDK or earlier processing. - -If you're using the `sentry-cocoa` SDK, you can also achieve the same result by marking other frames `not inApp`. The following sample marks functions from the classes `DataRequest` and `DownloadRequest` as `not inApp`. - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:DataRequest* -app -stack.function:DownloadRequest* -app - -``` - -### [Cut Stack Traces](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#cut-stack-traces) - -In many cases, you want to remove the top or bottom of the stack trace. For instance, many code bases use a common function to generate an error. In this case, the error machinery will appear as part of the stack trace. - -For example, if you use Rust, you likely want to remove some frames that are related to panic handling: - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:std::panicking::begin_panic ^-app -app ^-group -group -stack.function:core::panicking::begin_panic ^-app -app ^-group -group - -``` - -Here we tell the system that all frames from `begin-panic` to the crash location are not part of the application (including the panic frame itself). All frames above are, in all cases, irrelevant for grouping. - -Likewise, you can also remove the base of a stack trace. This is particularly useful if you have different main loops that drive an application: - -Enhancement Rules - -`` - -```bash code-highlight -stack.function:myapp::LinuxMainLoop v-group -group -stack.function:myapp::MacMainLoop v-group -group -stack.function:myapp::WinMainLoop v-group -group - -``` - -### [Stack Trace Frame Limits](https://docs.sentry.io/concepts/data-management/event-grouping/stack-trace-rules/\#stack-trace-frame-limits) - -This isn't useful for _all_ projects, but it can work well for large applications with many crashes. The default strategy is to consider most of the stack trace relevant for grouping. This means that every different stack trace that leads to a crashing function will cause a different group to be created. If you do not want that, you can force the groups to be much larger by limiting how many frames should be considered. - -For instance, if any of the frames in the stack trace refer to a common external library, you could tell the system only to consider the top N frames: - -Enhancement Rules - -`` - -```bash code-highlight -# always only consider the top 1 frame for all native events -family:native max-frames=1 - -# if the bug is in proprietarymodule.so, only consider top 2 frames -family:native stack.package:**/proprietarymodule.so max-frames=2 - -# these are functions we want to consider much more of the stack trace for -family:native stack.function:KnownBadFunction1 max-frames=5 -family:native stack.function:KnownBadFunction2 max-frames=5 - -``` - -[Previous\\ -\\ -Fingerprint Rules](https://docs.sentry.io/concepts/data-management/event-grouping/fingerprint-rules) - -[Next\\ -\\ -Data Forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/event-grouping/stack-trace-rules.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Sentry CLI](https://docs.sentry.io/cli/) -- [Crons (CLI)](https://docs.sentry.io/cli/crons/) - -# Crons (CLI) - -## Follow this guide to set up and manage monitors using the Sentry CLI. - -##### Deprecation Notice - -Starting with v2.16.1 of the Sentry CLI, the ability to monitor check-ins using an auth token for authorization has been deprecated. Read on to learn how to update your CLI and use your project's DSN instead. - -Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service. - -## [Requirements](https://docs.sentry.io/cli/crons/\#requirements) - -To begin monitoring your recurring, scheduled job: - -- [Install](https://docs.sentry.io/cli/installation/) the Sentry CLI (min v2.16.1). -- Create and configure your first Monitor in [Sentry](https://sentry.io/crons/create/) or [via the CLI](https://docs.sentry.io/cli/crons/#creating-or-updating-a-monitor-through-a-check-in-optional). - -## [Configuration](https://docs.sentry.io/cli/crons/\#configuration) - -The Sentry CLI uses your Monitor's project DSN to authorize check-ins. To set it up, export the `SENTRY_DSN` environment variable: - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/crons/). - -Bash - -`` - -```bash code-highlight -export SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 - -``` - -Alternatively, you can add it to your `~/.sentryclirc` config: - -The following code sample will let you choose your personal config from the dropdown, once you're [logged in](https://sentry.io/auth/login/?next=https://sentry-docs-next.sentry.dev//cli/crons/). - -Ini - -`~/.sentryclirc` - -```code-highlight ini -[auth] -dsn = https://examplePublicKey@o0.ingest.sentry.io/0 - -``` - -Learn more about the CLI's [configuration file](https://docs.sentry.io/cli/configuration/#configuration-file). - -## [Job Monitoring](https://docs.sentry.io/cli/crons/\#job-monitoring) - -Use the Sentry CLI to run your job and notify you if it doesn't start when expected (missed) or if it exceeded its maximum runtime (failed). - -CLI - -`` - -```bash code-highlight -sentry-cli monitors run <monitor_slug> -- <command> <args> - -``` - -Usage examples: - -PythonNode.JS - -`` - -```bash code-highlight -sentry-cli monitors run my-monitor-slug -- python path/to/file.py - -``` - -### [Creating or Updating a Monitor Through a Check-In (Optional)](https://docs.sentry.io/cli/crons/\#creating-or-updating-a-monitor-through-a-check-in-optional) - -You can also use the Sentry CLI to create or update your cron monitor when you run your job. This way, you can avoid having to first set up the monitor through the Sentry web interface. - -Configure the cron monitor by providing the cron schdule in crontab format using the `--schedule` or the equivalent `-s` argument when executing the `sentry cli monitors run` command. Please make sure to enclose the schedule in quotes, so that your shell parses the argument correctly, like so: - -Bash - -`` - -```bash code-highlight -sentry-cli monitors run --schedule "<expected schedule>" <monitor-slug> -- <command> <args> - -``` - -When providing the `--schedule` argument, we also support the following optional arguments to provide additional configuration: - -- `--check-in-margin`: The allowed margin of minutes after the expected check-in time that the monitor will not be considered missed for. -- `--max-runtime`: The allowed duration in minutes that the monitor may be in progress for before being considered failed due to timeout. -- `--timezone`: A valid [tz database identifier string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) (e.g. "Europe/Vienna") representing the monitor's execution schedule's timezone. - -Below are some usage examples: - -Every MinuteEvery Hour (+ Optional Arguments) - -`` - -```bash code-highlight -sentry-cli monitors run -s "* * * * *" -- my-command - -``` - -### [Specifying Monitor Environments (Optional)](https://docs.sentry.io/cli/crons/\#specifying-monitor-environments-optional) - -If your cron monitor runs in multiple environments you can use the `-e` flag to specify which [Monitor Environment](https://docs.sentry.io/product/crons/job-monitoring/#multiple-environments) to send check-ins to. - -Node.JS - -`` - -```bash code-highlight -sentry-cli monitors run -e dev my-monitor-slug -- node path/to/file.js - -``` - -[Previous\\ -\\ -Sending Events](https://docs.sentry.io/cli/send-event) - -[Next\\ -\\ -API Reference](https://docs.sentry.io/api) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/cli/crons.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [API Reference](https://docs.sentry.io/api/) -- [Paginating Results](https://docs.sentry.io/api/pagination/) - -# Paginating Results - -Pagination in the API is handled via the Link header standard: - -BashHttp - -`` - -```bash code-highlight -curl -i https://sentry.io/api/0/organizations/acme/projects/1/groups/ - -``` - -When supported, cursors will **always** be returned for both a previous and a next page, even if there are no results on these pages. This allows you to make a query against the API for yet-undiscovered results. An example where this would be used is when you're implementing polling behavior and you want to see if there is any new data. We return a `results="[true|false]"` indicator to determine if you actually need to paginate. - -## [Pagination Example](https://docs.sentry.io/api/pagination/\#pagination-example) - -Here is a pagination example using this API endpoint: - -[https://docs.sentry.io/api/events/list-an-issues-events/](https://docs.sentry.io/api/events/list-an-issues-events/) - -The HTTP request in this example returns 100 events for the issue and has the following link header in the response: - -Http - -`` - -```bash code-highlight -<https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="false"; cursor="0:0:1", <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:100:0>; rel="next"; results="true"; cursor="0:100:0" - -``` - -One of the URLs in the link response has `rel=next`, which indicates the next results page. It also has `results=true`, which means that there are more results. - -Based on this, the next request is `GET <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:100:0>`. - -This request will return the next 100 events for that issue, again, with the following link header: - -Http - -`` - -```bash code-highlight -<https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:0:1>; rel="previous"; results="true"; cursor="0:0:1", <https://sentry.io/api/0/organizations/acme/issues/123456/events/?&cursor=0:200:0>; rel="next"; results="true"; cursor="0:200:0" - -``` - -The process is repeated until the URL with `rel=next` has the flag `results=false` to indicate the last page. - -The three values from cursor are: cursor identifier (integer, usually 0), row offset, and is\_prev (1 or 0). - -[Previous\\ -\\ -Authentication](https://docs.sentry.io/api/auth) - -[Next\\ -\\ -Permissions & Scopes](https://docs.sentry.io/api/permissions) - -- [Home](https://docs.sentry.io/) -- [Concepts & Reference](https://docs.sentry.io/concepts/) -- [Data Management](https://docs.sentry.io/concepts/data-management/) -- [Size Limits](https://docs.sentry.io/concepts/data-management/size-limits/) - -# Size Limits - -## Learn about the size limits for events and attachments, and how to avoid exceeding them. - -Sentry imposes size limits on events, attachments, requests, and various event fields. - -## [Behavior](https://docs.sentry.io/concepts/data-management/size-limits/\#behavior) - -The following describes how Sentry treats size limits: - -- Events, attachments, and requests exceeding payload size limits are immediately dropped with a `413 Payload Too Large` error. -- Sentry allows compressed content encoding, and applies separate limits before and after decompression. -- Events that exceed 200KB compressed or 1MB decompressed will be rejected. -- Minidump uploads that exceeed 20MB compressed or 100MB decompressed (for all files combined) will also be rejected. -- Event fields exceeding the individual size limits are trimmed and truncated afterwards. -- The number of events rejected due to size limits is counted towards the _Dropped_ category in [usage stats](https://docs.sentry.io/product/stats/#usage-stats). - -## [Recommendations](https://docs.sentry.io/concepts/data-management/size-limits/\#recommendations) - -To avoid using up your attachments quota — which is based on size and not number of instances of attachments data sent — or having the event dropped entirely, consider limiting the size of values passed into Sentry's APIs. For example, if your application attaches application state or request bodies to Sentry events, truncate them first. - -## [Size Limit References](https://docs.sentry.io/concepts/data-management/size-limits/\#size-limit-references) - -Sentry's exact size limits may change over time. For more information, please refer to the following resources: - -- [Envelope Size Limits](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) -- [Store Endpoint Size Limits](https://develop.sentry.dev/sdk/miscellaneous/store/#size-limits) -- [Minidump Size Limits](https://docs.sentry.io/platforms/native/guides/minidumps/#size-limits) -- [Variable Size Limits](https://develop.sentry.dev/sdk/expected-features/data-handling/#variable-size) - -[Previous\\ -\\ -Inbound Filters](https://docs.sentry.io/concepts/data-management/filtering) - -[Next\\ -\\ -Moving to SaaS](https://docs.sentry.io/concepts/migration) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/concepts/data-management/size-limits.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Cloud Monitoring](https://docs.sentry.io/organization/integrations/cloud-monitoring/) - -# Cloud Monitoring - -## Learn more about Sentry's cloud monitoring integrations. - -- [Cloudflare Workers](https://docs.sentry.io/organization/integrations/cloud-monitoring/cloudflare-workers/) -- [Google Cloud Run](https://docs.sentry.io/organization/integrations/cloud-monitoring/gcp-cloud-run/) -- [Google Cloud Functions - Python](https://docs.sentry.io/platforms/python/integrations/gcp-functions/) -- [Google Cloud Functions - Node](https://docs.sentry.io/platforms/javascript/guides/gcp-functions/) -- [AWS Lambda - Python (Automatic)](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) -- [AWS Lambda - Python (Manual)](https://docs.sentry.io/platforms/python/integrations/aws-lambda/) -- [AWS Lambda - Node (Automatic)](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda/) -- [AWS Lambda - Node (Manual)](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/) - -[Previous\\ -\\ -Compliance](https://docs.sentry.io/organization/integrations/compliance) - -[Next\\ -\\ -AWS Lambda](https://docs.sentry.io/organization/integrations/cloud-monitoring/aws-lambda) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/cloud-monitoring/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Organization Settings](https://docs.sentry.io/organization/) -- [Integrations](https://docs.sentry.io/organization/integrations/) -- [Data & Visualization](https://docs.sentry.io/organization/integrations/data-visualization/) -- [Segment](https://docs.sentry.io/organization/integrations/data-visualization/segment/) - -# Segment - -## Learn about Sentry's Segment integration, which allows you to collect all your client-side data for Sentry automatically. - -If you make changes to your organization slug, you'll need to update your configuration for this integration. Learn more in our [troubleshooting guide](https://docs.sentry.io/organization/integrations/troubleshooting/). - -Segment is useful for collecting, responsibly managing, and integrating your customer data with many other applications, including Sentry. - -This integration needs to be set up in each project for which you wish to use it. It is maintained and supported by the [Sentry community](https://open.sentry.io/). - -## [Install and Configure](https://docs.sentry.io/organization/integrations/data-visualization/segment/\#install-and-configure) - -Sentry owner, manager, or admin permissions are required to install this integration. - -Navigate to **Settings > Integrations > Segment** - -[![Install Segment integration](https://docs.sentry.io/_next/image/?url=%2Fmdx-images%2Fsegment-WF5U76QW.png%231944x718&w=3840&q=75)](https://docs.sentry.io/mdx-images/segment-WF5U76QW.png) - -### [Data Forwarding](https://docs.sentry.io/organization/integrations/data-visualization/segment/\#data-forwarding) - -Configure [data forwarding](https://docs.sentry.io/concepts/data-management/data-forwarding/) in **\[Project\] > Settings > Data Forwarding**, and provide the required information for the given integration. - -[Previous\\ -\\ -Grafana](https://docs.sentry.io/organization/integrations/data-visualization/grafana) - -[Next\\ -\\ -Splunk](https://docs.sentry.io/organization/integrations/data-visualization/splunk) - - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/organization/integrations/data-visualization/segment/index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/)- [Home](https://docs.sentry.io/) -- [Contributing to Docs](https://docs.sentry.io/contributing/) -- [Our Approach](https://docs.sentry.io/contributing/approach/) -- [Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs/) -- [How to Write - Index Pages](https://docs.sentry.io/contributing/approach/product-docs/write-index/) - -# How to Write - Index Pages - -This guide to writing index pages is just that—a guide. It won’t answer every question you have about how to write a good index page, but it will help you make a good start. - -While we use the term “index page” to refer to the top-level page about a feature in Docs, we don’t use this terminology in the actual Docs. Learn more in [Other Guidelines](https://docs.sentry.io/contributing/approach/product-docs/write-index/#other-guidelines). - -The index page: - -- Explains WHAT the feature is -- Describes WHY the feature benefits the customer, without veering too far into marketing language -- Describes HOW the mechanisms of the feature help the customer achieve these benefits -- Provides easy-to-find LINKS to child pages describing the subpages of the primary feature and/or how to do things with the feature - -The index page does not: - -- Describe HOW TO do anything that can’t be described in one or two sentences; that information should be on child pages in Docs. - -## [What and Why](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#what-and-why) - -- The elevator pitch of this feature - - What the feature is and what problem it’s solving for the customer -- Two-to-five sentences - - This can be longer if you need to explain the feature as a concept before you can explain what the feature provides (for example, [Releases as a feature/concept vs the Releases page of application](https://docs.sentry.io/product/releases/)) -- A pixel perfect overview screenshot showing the feature in action - -## [How: Contained Features - Page Breakdown](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#how-contained-features---page-breakdown) - -Use this approach for a feature that doesn’t require much explanation and has distinct sections, like [Usage Stats](https://docs.sentry.io/product/stats/) \- it’s good for very contained features. - -- Describe each page section/element focusing on how it helps the customer achieve the WHY of this feature. -- Add headings describing the page section/element to make each section of text stand out, if needed. -- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries). - -## [How: Wider-Ranging Features - Benefit Breakdown](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#how-wider-ranging-features---benefit-breakdown) - -Use this approach for a page that requires more explanation to break down and/or has a lot of child pages to explain its different benefits, like [Insights](https://docs.sentry.io/product/insights/). - -- Describe how each page section/element or child page, helps the customer achieve the WHY of this feature. -- Include links to relevant child pages in the text. -- Group page sections/elements or child pages as appropriate. -- Add headings that describe the benefit rather than the page section/element like [here](https://docs.sentry.io/product/insights/overview/#analyze-performance-trends). -- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries). - -If you use this approach, you may want to include a very high-level, one- or two-sentence description of what the page looks like as part of the WHAT/WHY section. - -## [Links](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#links) - -- Create a section called “Learn More” - -- Use a `<PageGrid />` element to link to child pages for this feature - - - This displays a bullet list of page links with their front matter page descriptions - - This might require that you edit the front matter descriptions of the pages displayed in the page grid - -## [Includes](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#includes) - -You might need to use an `include` file for small pieces of reusable content, such as Early Adopter notes, plan/feature notes, or short snippets of text. These are found in [`/includes/`](https://github.com/getsentry/sentry-docs/tree/master/includes). - -## [Other Guidelines](https://docs.sentry.io/contributing/approach/product-docs/write-index/\#other-guidelines) - -Following are some quick tips to keep in mind: - -- Refer to the feature’s main page in the application as a _page_, _home page_, or even _main page_. Do not call it an _index page_ or use _homepage_ (all one word). -- Refer to the organization as _Sentry_; refer to the UI of the application as [sentry.io](https://sentry.io/) (with lower case “s” and embedded link), not _the Sentry UI_. -- Avoid beginning sentences with [sentry.io](https://sentry.io/). -- Do not skip heading levels. Don’t use an H3 as your first sub-heading/page-level heading. The page title is considered the H1 and the next heading level that should be used after that is an H2. If you skip heading levels, the right hand sidebar menu won’t render. -- Do not add more H1 headings to the page. The title is the H1. All other headings on the page should be H2 or lower in hierarchy (that is, higher in number). - -Internal writers, refer to the [Tips for Contributors](https://www.notion.so/sentry/Tips-for-Contributors-b1997ea7f5e84eb9a02e0770b6dcc453) page for further guidance. - -[Previous\\ -\\ -Product Documentation Structure](https://docs.sentry.io/contributing/approach/product-docs) - -[Next\\ -\\ -Platforms & Guides](https://docs.sentry.io/contributing/platforms) - - - -[How to contribute](https://docs.sentry.io/contributing/) \| [Edit this page](https://github.com/getsentry/sentry-docs/edit/master/docs/contributing/approach/product-docs/write-index.mdx) \| [Create a docs issue](https://github.com/getsentry/sentry-docs/issues/new/choose) \| [Get support](https://sentry.zendesk.com/hc/en-us/) -Copy +[Nextjs](/platform/javascript/guides/nextjs/llms.txt) +[React](/platform/javascript/guides/react/llms.txt) +[JavaScrip](/platform/javascript/common/llms.txt) \ No newline at end of file diff --git a/public/platform/javascript/common/llms.txt b/public/platform/javascript/common/llms.txt new file mode 100644 index 0000000000000..f10fec489f209 --- /dev/null +++ b/public/platform/javascript/common/llms.txt @@ -0,0 +1,79 @@ +# Sentry and JavaScript LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instrucitons, while taking into account the users request. + +Always ensure you are installing Sentry using `npm i @sentry/browser@latest`. The latest package should always be used. + +By default you should instrument the latest version of packages unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in JavaScript based applications. Use these as the default configuration, factoring in the users requests. + +### Sentry Setup (applies to all configuraitons) + +Configure Sentry using the following parameters unless explicitly told otherwise. + +```javascript +import * as Sentry from "@sentry/browser"; + +Sentry.init({ + dsn: "<sentry dsn>", + + release: "dev", + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.replayIntegration(), + ], + + tracesSampleRate: 1.0, + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); +``` + +### Error Tracking and Exception Catching + +Instrument errors throughout the application as desired by using the following configuration + +```javascript +import * as Sentry from "@sentry/browser"; + +Sentry.captureException(error) +``` + +### Tracing + +Utilize the following example for tracing scenarios where the user wants to instrument tracing. Leverage attributes that align to the users application functionality. + +```javascript +Sentry.startSpan( + { + name: "Span Name", + op: "example.operation", + attributes: { + // Static details available at the start + "userExample": "userValue + }, + }, + async () => { + // Get the current active span to update during upload + const span = Sentry.getActiveSpan(); + + try { + if (span) { + span.setAttribute("samplespan.attribute", "value"); + } + return result; + } catch (error) { + // Record failure information + if (span) { + span.setAttribute("otherSample.attribute", true); + } + throw error; + } + }, +); +``` \ No newline at end of file diff --git a/public/platform/javascript/guides/nextjs/llms.txt b/public/platform/javascript/guides/nextjs/llms.txt new file mode 100644 index 0000000000000..d840b5de35d1b --- /dev/null +++ b/public/platform/javascript/guides/nextjs/llms.txt @@ -0,0 +1,59 @@ +# Sentry and Nextjs LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instrucitons, while taking into account the users request. + +Always ensure you are installing Sentry using `npx @sentry/wizard@latest -i nextjs` wizard command. This command is interactive so the user will need to answer questions. The latest package should always be used. + +By default you should instrument the latest version of packages unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in Nextjs based applications. Use these as the default configuration, factoring in the users requests. + +### Sentry Setup (applies to all configuraitons) + +The Nextjs wizard will automatically create `instrumentation-client.config.ts`, `server.config.ts`, and `edge.config.ts` files during the setup. + +### Error Tracking and Exception Catching + +Instrument errors throughout the application as desired by using the following configuration + +```javascript +import * as Sentry from "@sentry/nextjs"; + +Sentry.captureException(error) +``` + +### Tracing + +Utilize the following example for tracing scenarios where the user wants to instrument tracing. Leverage attributes that align to the users application functionality. + +```javascript +Sentry.startSpan( + { + name: "Span Name", + op: "example.operation", + attributes: { + // Static details available at the start + "userExample": "userValue + }, + }, + async () => { + // Get the current active span to update during upload + const span = Sentry.getActiveSpan(); + + try { + if (span) { + span.setAttribute("samplespan.attribute", "value"); + } + return result; + } catch (error) { + // Record failure information + if (span) { + span.setAttribute("otherSample.attribute", true); + } + throw error; + } + }, +); +``` \ No newline at end of file diff --git a/public/platform/javascript/guides/react/llms.txt b/public/platform/javascript/guides/react/llms.txt new file mode 100644 index 0000000000000..919d8c148f07a --- /dev/null +++ b/public/platform/javascript/guides/react/llms.txt @@ -0,0 +1,79 @@ +# Sentry and React LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instrucitons, while taking into account the users request. + +Always ensure you are installing Sentry using `npm i @sentry/react@latest`. The latest package should always be used. + +By default you should instrument the latest version of packages unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in JavaScript based applications. Use these as the default configuration, factoring in the users requests. + +### Sentry Setup (applies to all configuraitons) + +Configure Sentry using the following parameters unless explicitly told otherwise. + +```javascript +import * as Sentry from "@sentry/react"; + +Sentry.init({ + dsn: "<sentry dsn>", + + release: "dev", + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.replayIntegration(), + ], + + tracesSampleRate: 1.0, + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, +}); +``` + +### Error Tracking and Exception Catching + +Instrument errors throughout the application as desired by using the following configuration + +```javascript +import * as Sentry from "@sentry/react"; + +Sentry.captureException(error) +``` + +### Tracing + +Utilize the following example for tracing scenarios where the user wants to instrument tracing. Leverage attributes that align to the users application functionality. + +```javascript +Sentry.startSpan( + { + name: "Span Name", + op: "example.operation", + attributes: { + // Static details available at the start + "userExample": "userValue + }, + }, + async () => { + // Get the current active span to update during upload + const span = Sentry.getActiveSpan(); + + try { + if (span) { + span.setAttribute("samplespan.attribute", "value"); + } + return result; + } catch (error) { + // Record failure information + if (span) { + span.setAttribute("otherSample.attribute", true); + } + throw error; + } + }, +); +``` \ No newline at end of file From 5aa6f38c1f054404d59ffc07d606024d7e157e30 Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Thu, 3 Apr 2025 02:28:50 -0700 Subject: [PATCH 4/7] Moving llms.txt to correct directory --- public/{platform => platforms}/javascript/common/llms.txt | 0 public/{platform => platforms}/javascript/guides/nextjs/llms.txt | 0 public/{platform => platforms}/javascript/guides/react/llms.txt | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename public/{platform => platforms}/javascript/common/llms.txt (100%) rename public/{platform => platforms}/javascript/guides/nextjs/llms.txt (100%) rename public/{platform => platforms}/javascript/guides/react/llms.txt (100%) diff --git a/public/platform/javascript/common/llms.txt b/public/platforms/javascript/common/llms.txt similarity index 100% rename from public/platform/javascript/common/llms.txt rename to public/platforms/javascript/common/llms.txt diff --git a/public/platform/javascript/guides/nextjs/llms.txt b/public/platforms/javascript/guides/nextjs/llms.txt similarity index 100% rename from public/platform/javascript/guides/nextjs/llms.txt rename to public/platforms/javascript/guides/nextjs/llms.txt diff --git a/public/platform/javascript/guides/react/llms.txt b/public/platforms/javascript/guides/react/llms.txt similarity index 100% rename from public/platform/javascript/guides/react/llms.txt rename to public/platforms/javascript/guides/react/llms.txt From 415c21a21281374c8c569fdd9caf4d2c0c03dcfa Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Thu, 3 Apr 2025 10:07:13 -0700 Subject: [PATCH 5/7] Correcting url to platforms --- public/llms.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/public/llms.txt b/public/llms.txt index 86c2e74e785fc..dd4a79ff43002 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -2,6 +2,6 @@ Sentry llms.txt This llmx.txt focuses on platform specific configuration options for the major sdks, linked below. AI sdks should parse these paths to access the framework specific llm instructions. -[Nextjs](/platform/javascript/guides/nextjs/llms.txt) -[React](/platform/javascript/guides/react/llms.txt) -[JavaScrip](/platform/javascript/common/llms.txt) \ No newline at end of file +[Nextjs](/platforms/javascript/guides/nextjs/llms.txt) +[React](/platforms/javascript/guides/react/llms.txt) +[JavaScrip](/platforms/javascript/common/llms.txt) \ No newline at end of file From 716f321c91ea3a394835bca103133f52a037a1d4 Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Mon, 7 Apr 2025 00:18:44 -0700 Subject: [PATCH 6/7] Adding python, fixing javascript reference --- public/llms.txt | 3 +- public/platforms/python/llms.txt | 110 +++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 public/platforms/python/llms.txt diff --git a/public/llms.txt b/public/llms.txt index dd4a79ff43002..204f4f8df8294 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -4,4 +4,5 @@ This llmx.txt focuses on platform specific configuration options for the major s [Nextjs](/platforms/javascript/guides/nextjs/llms.txt) [React](/platforms/javascript/guides/react/llms.txt) -[JavaScrip](/platforms/javascript/common/llms.txt) \ No newline at end of file +[JavaScript](/platforms/javascript/common/llms.txt) +[Python](/platforms/python/llms.txt) \ No newline at end of file diff --git a/public/platforms/python/llms.txt b/public/platforms/python/llms.txt new file mode 100644 index 0000000000000..2b1bb567fb34e --- /dev/null +++ b/public/platforms/python/llms.txt @@ -0,0 +1,110 @@ +# Sentry and Python LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instructions, while taking into account the user's request. + +Always ensure you are installing Sentry using `pip install --upgrade sentry-sdk`. The latest package should always be used unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in Python applications. Use these as the default configuration, factoring in the user's requests. + +### Sentry Setup (applies to all configurations) + +Configure Sentry using the following parameters unless explicitly told otherwise. + +```python +import sentry_sdk + +sentry_sdk.init( + dsn="<sentry dsn>", + + # Add request headers and IP for users + send_default_pii=True, + + # Set traces_sample_rate to 1.0 to capture 100% + # of transactions for tracing. + traces_sample_rate=1.0, + + # Set profiles_sample_rate to 1.0 to profile 100% + # of sampled transactions. + # Recommend adjusting this value in production. + profiles_sample_rate=1.0, +) +``` + +### Error Tracking and Exception Catching + +Instrument errors throughout the application using the following approaches: + +```python +# Explicitly capture an exception +try: + division_by_zero = 1 / 0 +except Exception as e: + sentry_sdk.capture_exception(e) + +# Capture a custom message with additional context +sentry_sdk.capture_message( + "Something went wrong", + level="error", + extras={"additional_context": "value"} +) +``` + +### Tracing and Performance Monitoring + +Utilize the following examples for tracing scenarios: + +```python +with sentry_sdk.start_transaction(name="task_name", op="task"): + # Get the current active span to update during operation + span = sentry_sdk.start_span(op="subtask", description="Subtask description") + with span: + try: + # Your code here + span.set_data("key", "value") + except Exception as e: + # Record failure information + span.set_status("internal_error") + raise e +``` + +### AI/LLM Monitoring + +For AI and LLM monitoring: + +```python +import sentry_sdk +from sentry_sdk.ai.monitoring import ai_track + +sentry_sdk.init( + dsn="<sentry dsn>", + send_default_pii=True, + # To include AI prompts and completions, set send_default_pii=True +) + +@ai_track("My AI pipeline") +def my_pipeline(): + with sentry_sdk.start_transaction(op="ai-inference", name="AI operation"): + # AI operation code + pass +``` + +### Framework Integrations + +Python SDK automatically enables integrations for frameworks detected in your environment. To explicitly configure: + +```python +import sentry_sdk +from sentry_sdk.integrations.flask import FlaskIntegration +from sentry_sdk.integrations.django import DjangoIntegration + +sentry_sdk.init( + dsn="<sentry dsn>", + integrations=[ + FlaskIntegration(), + DjangoIntegration(), + # Add other integrations as needed + ], +) +``` \ No newline at end of file From 5a85ff2706cf7d6bf53d3619785073cf6ab040f0 Mon Sep 17 00:00:00 2001 From: Cody De Arkland <codydearkland@gmail.com> Date: Tue, 8 Apr 2025 09:19:24 -0700 Subject: [PATCH 7/7] Adding bun and node llms.txt for testing --- public/llms.txt | 10 ++- public/platforms/bun/llms.txt | 130 +++++++++++++++++++++++++++++++++ public/platforms/node/llms.txt | 125 +++++++++++++++++++++++++++++++ 3 files changed, 261 insertions(+), 4 deletions(-) create mode 100644 public/platforms/bun/llms.txt create mode 100644 public/platforms/node/llms.txt diff --git a/public/llms.txt b/public/llms.txt index 204f4f8df8294..5e6a568313e57 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -2,7 +2,9 @@ Sentry llms.txt This llmx.txt focuses on platform specific configuration options for the major sdks, linked below. AI sdks should parse these paths to access the framework specific llm instructions. -[Nextjs](/platforms/javascript/guides/nextjs/llms.txt) -[React](/platforms/javascript/guides/react/llms.txt) -[JavaScript](/platforms/javascript/common/llms.txt) -[Python](/platforms/python/llms.txt) \ No newline at end of file +[nextjs](/platforms/javascript/guides/nextjs/llms.txt) +[react](/platforms/javascript/guides/react/llms.txt) +[javaScript](/platforms/javascript/common/llms.txt) +[python](/platforms/python/llms.txt) +[bun](/platforms/bun/llms.txt) +[node](/platforms/node/llms.txt) \ No newline at end of file diff --git a/public/platforms/bun/llms.txt b/public/platforms/bun/llms.txt new file mode 100644 index 0000000000000..bf0d74e1e6be9 --- /dev/null +++ b/public/platforms/bun/llms.txt @@ -0,0 +1,130 @@ +# Sentry and Bun LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instructions, while taking into account the user's request. + +Always ensure you are installing Sentry using `bun add @sentry/bun@latest`. The latest package should always be used unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in Bun applications. Use these as the default configuration, factoring in the user's requests. + +### Sentry Setup (applies to all configurations) + +Sentry should be initialized as early as possible in your application's lifecycle. Create a file named `instrument.js` that imports and initializes Sentry: + +```javascript +import * as Sentry from "@sentry/bun"; + +// Initialize Sentry before importing any other modules +Sentry.init({ + dsn: "<sentry dsn>", + + // Enable tracing to capture 100% of transactions + // Recommend adjusting this value in production + tracesSampleRate: 1.0, + + // Set tracePropagationTargets for which URLs trace propagation should be enabled + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], +}); +``` + +Then import this file at the very beginning of your main application file: + +```javascript +// Import this first! +import "./instrument"; + +// Now import other modules +import http from "http"; + +// Your application code goes here +``` + +### Error Tracking and Exception Catching + +Instrument errors throughout the application using the following approaches: + +```javascript +// Explicitly capture an exception +try { + throw new Error("Example error"); +} catch (e) { + Sentry.captureException(e); +} + +// Capture a custom message +Sentry.captureMessage("Something went wrong", "error"); + +// Add extra context to the error +Sentry.configureScope((scope) => { + scope.setTag("page_locale", "de-at"); + scope.setUser({ id: '123', email: 'user@example.com' }); + scope.setExtra("character_name", "Mighty Fighter"); +}); +``` + +### Tracing and Performance Monitoring + +Utilize the following examples for tracing scenarios: + +```javascript +// Create a transaction +const transaction = Sentry.startTransaction({ + op: "test", + name: "My First Test Transaction" +}); + +// Set transaction as the current scope +Sentry.getCurrentHub().configureScope(scope => { + scope.setSpan(transaction); +}); + +// Create a child span +const span = transaction.startChild({ op: "functionX", description: "Function doing work" }); + +try { + // Do something... + span.setStatus("ok"); +} catch (error) { + span.setStatus("internal_error"); + throw error; +} finally { + // Finish the span + span.finish(); + // Finish the transaction + transaction.finish(); +} +``` + +### Bun.serve Integration + +For Bun server applications: + +```javascript +import * as Sentry from "@sentry/bun"; + +// Initialize Sentry before anything else +Sentry.init({ + dsn: "<sentry dsn>", + integrations: [ + // Add Bun server integration + Sentry.bunServerIntegration(), + ], + tracesSampleRate: 1.0, +}); + +// Example Bun server +Bun.serve({ + port: 3000, + fetch(req) { + const url = new URL(req.url); + + if (url.pathname === "/error") { + // This will be automatically captured by Sentry + throw new Error("Example server error"); + } + + return new Response("Hello World!"); + }, +}); +``` \ No newline at end of file diff --git a/public/platforms/node/llms.txt b/public/platforms/node/llms.txt new file mode 100644 index 0000000000000..562b8c8b7e98e --- /dev/null +++ b/public/platforms/node/llms.txt @@ -0,0 +1,125 @@ +# Sentry and Node.js LLM Rules + +You are an expert in application architecture and the configuration of observability tools like Sentry. Ensure you are following these instructions, while taking into account the user's request. + +Always ensure you are installing Sentry using `npm install @sentry/node@latest` or `yarn add @sentry/node@latest`. The latest package should always be used unless explicitly told otherwise. + +## Configuration examples + +These examples should be used to configure the different Sentry functionality in Node.js applications. Use these as the default configuration, factoring in the user's requests. + +### Sentry Setup (applies to all configurations) + +Configure Sentry using the following parameters unless explicitly told otherwise. + +```javascript +import * as Sentry from "@sentry/node"; + +// Initialize Sentry as early as possible +Sentry.init({ + dsn: "<sentry dsn>", + + // Enable tracing to capture 100% of transactions + // Recommend adjusting this value in production + tracesSampleRate: 1.0, + + // Set tracePropagationTargets for which URLs trace propagation should be enabled + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Enable HTTP capturing + integrations: [ + Sentry.httpIntegration(), + ], +}); +``` + +### Error Tracking and Exception Catching + +Instrument errors throughout the application using the following approaches: + +```javascript +// Explicitly capture an exception +try { + throw new Error("Example error"); +} catch (e) { + Sentry.captureException(e); +} + +// Capture a custom message +Sentry.captureMessage("Something went wrong", "error"); + +// Add extra context to the error +Sentry.configureScope((scope) => { + scope.setTag("page_locale", "de-at"); + scope.setUser({ id: '123', email: 'user@example.com' }); + scope.setExtra("character_name", "Mighty Fighter"); +}); +``` + +### Tracing and Performance Monitoring + +Utilize the following examples for tracing scenarios: + +```javascript +// Create a transaction +const transaction = Sentry.startTransaction({ + op: "test", + name: "My First Test Transaction" +}); + +// Set transaction as the current scope +Sentry.getCurrentHub().configureScope(scope => { + scope.setSpan(transaction); +}); + +// Create a child span +const span = transaction.startChild({ op: "functionX", description: "Function doing work" }); + +try { + // Do something... + span.setStatus("ok"); +} catch (error) { + span.setStatus("internal_error"); + throw error; +} finally { + // Finish the span + span.finish(); + // Finish the transaction + transaction.finish(); +} +``` + +### Express Framework Integration + +For Express.js applications: + +```javascript +import express from "express"; +import * as Sentry from "@sentry/node"; + +const app = express(); + +// Initialize Sentry - this must happen before other app middleware +Sentry.init({ + dsn: "<sentry dsn>", + integrations: [ + // Enable Express.js monitoring + Sentry.expressIntegration(), + Sentry.httpIntegration(), + ], + tracesSampleRate: 1.0, +}); + +// The request handler must be the first middleware on the app +app.use(Sentry.Handlers.requestHandler()); + +// All your controllers should go here +app.get("/", function rootHandler(req, res) { + res.end("Hello world!"); +}); + +// The error handler must be registered before any other error middleware and after all controllers +app.use(Sentry.Handlers.errorHandler()); + +app.listen(3000); +``` \ No newline at end of file