From efbd5cbea12f2c039099163fba4e6bc6e5381f31 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Tue, 13 Jun 2023 11:55:33 +0200 Subject: [PATCH 01/23] Document Apollo3 GraphQL client errors --- .../configuration/integrations/apollo3.mdx | 91 ++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 9764da9cef028..deda0f3f55a78 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -32,7 +32,8 @@ Add `Interceptors` to `ApolloClient.Builder` using `ApolloBuilderExtensions`: import com.apollographql.apollo3.ApolloClient; import io.sentry.apollo3.SentryApolloBuilderExtensionsKt; -ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(new ApolloClient.Builder()) +ApolloClient apollo = SentryApolloBuilderExtensionsKt + .sentryTracing(new ApolloClient.Builder()) .serverUrl("https://your-api-host/") .build(); ``` @@ -118,3 +119,91 @@ val apollo = ApolloClient.builder() } .build() ``` + +## GraphQL Client Errors + +This feature, once enabled, automatically captures GraphQL client errors, like bad operations and response codes, as error events and reports them to Sentry. The error event will contain the `request` and `response` data, such as `url`, `status_code`, `data` (stringified `query`) and so on. + +This feature is opt-in and can be enabled by setting the `captureFailedRequests` option to `true`: + +```kotlin +import com.apollographql.apollo3.ApolloClient +import io.sentry.apollo3.sentryTracing + +val apollo = ApolloClient.builder() + .serverUrl("https://your-api-host/") + .sentryTracing(captureFailedRequests = true) + .build() +``` + +By default, only GraphQL client errors with a response that includes the [errors](https://spec.graphql.org/October2021/#sec-Errors) array are captured as error events. + +GraphQL client errors from every target (`.*` regular expression) are automatically captured, but you can change this behavior by setting the `failedRequestTargets` option with either a regular expression or a plain `String`. A plain string must contain at least one of the items from the list. Plain strings don't have to be full matches, meaning the URL of a request is matched when it contains a string provided through the option. + +```kotlin +import com.apollographql.apollo3.ApolloClient +import io.sentry.apollo3.sentryTracing + +val apollo = ApolloClient.builder() + .serverUrl("https://your-api-host/") + .sentryTracing(captureFailedRequests = true, failedRequestTargets = listOf("myapi.com")) + .build() +``` + +By default, error events won't contain `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: + +```xml {filename:AndroidManifest.xml} + + + +``` + +Error events will contain the raw bodies of GraphQL requests and responses, the raw bodies can contain sensitive data, to avoid that, you can do the parametrization of your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field, using parametrized queries, [Relay](https://docs.sentry.io/product/relay) will run [PII Data Scrubbing](https://docs.sentry.io/product/relay/#pii-data-scrubbing) automatically transforming the values into `[Filtered]`. + +Alternatively, you can customize the event and scrub the data yourself. + +### Customize or Drop the Error Event + +To customize or drop the error event, you need to do a [manual initialization](/platforms/android/configuration/manual-init/) of the Sentry Android SDK. + +The captured error event can be customized or dropped with a `BeforeSendCallback`: + +```kotlin +import io.sentry.android.core.SentryAndroid +import io.sentry.SentryOptions.BeforeSendCallback +import com.apollographql.apollo3.api.http.HttpRequest +import com.apollographql.apollo3.api.http.HttpResponse +import io.sentry.TypeCheckHint.APOLLO_REQUEST +import io.sentry.TypeCheckHint.APOLLO_RESPONSE + +SentryAndroid.init(this) { options -> + // Add a callback that will be used before the event is sent to Sentry. + // With this callback, you can modify the event or, when returning null, also discard the event. + options.beforeSend = BeforeSendCallback { event, hint -> + val request = hint.getAs(APOLLO_REQUEST, HttpRequest::class.java) + val response = hint.getAs(APOLLO_RESPONSE, HttpResponse::class.java) + + // customize or drop the event + event + } +} +``` + +### Automatically Captured GraphQL Client Errors and Manually Captured Errors + +When `captureFailedRequests` is enabled, some GraphQL client libraries throw unchecked exceptions like `ApolloException` and its implementations. In this case, the error event is captured twice; once by the GraphQL client library and once by the Sentry Android SDK: + +```kotlin +import io.sentry.Sentry +import com.apollographql.apollo3.exception.ApolloException + +try { + // If this API call returns 500, it will be captured as an error event by the `SentryOkHttpInterceptor`. + return apolloClient.query(LaunchDetailsQuery(launchId)).execute() +} catch (e: ApolloException) { + // Do not manually capture this exception to avoid duplicated error events. + // Sentry.captureException(e) +} +``` + +We recommend you identify those errors and **not** capture them manually with the `Sentry.captureException` method. From 0ccc1d21767a4cddf7d497ca9851a312aef32aed Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Tue, 13 Jun 2023 11:59:58 +0200 Subject: [PATCH 02/23] fix --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index deda0f3f55a78..1e27dc6de312d 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -198,7 +198,7 @@ import io.sentry.Sentry import com.apollographql.apollo3.exception.ApolloException try { - // If this API call returns 500, it will be captured as an error event by the `SentryOkHttpInterceptor`. + // If this API call returns the `errors` array, it will be captured as an error event by the `SentryApollo3HttpInterceptor`. return apolloClient.query(LaunchDetailsQuery(launchId)).execute() } catch (e: ApolloException) { // Do not manually capture this exception to avoid duplicated error events. From 22357240f7412aaa9ddfaa4cda660e63734d5b91 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Tue, 13 Jun 2023 12:02:16 +0200 Subject: [PATCH 03/23] add grouping note --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 1e27dc6de312d..63b65c1859452 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -124,6 +124,8 @@ val apollo = ApolloClient.builder() This feature, once enabled, automatically captures GraphQL client errors, like bad operations and response codes, as error events and reports them to Sentry. The error event will contain the `request` and `response` data, such as `url`, `status_code`, `data` (stringified `query`) and so on. +Sentry will group GraphQL client errors by the `operationName`, `operationType` and `statusCode`, so that you can easily see how many errors happened for a specific `operationName`, `operationType` and `statusCode`. + This feature is opt-in and can be enabled by setting the `captureFailedRequests` option to `true`: ```kotlin From cfe220859ddb702c7ec20f3f5fc03c1d5c2d6f1a Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:47:19 +0200 Subject: [PATCH 04/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Karl Heinz Struggl --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 63b65c1859452..2b2127ff193e9 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -122,7 +122,7 @@ val apollo = ApolloClient.builder() ## GraphQL Client Errors -This feature, once enabled, automatically captures GraphQL client errors, like bad operations and response codes, as error events and reports them to Sentry. The error event will contain the `request` and `response` data, such as `url`, `status_code`, `data` (stringified `query`) and so on. +Once enabled, this feature will automatically capture GraphQL client errors such as bad operations and response codes, and report them to Sentry as error events. Each error event will contain the `request` and `response` data, including the `url`, `status_code`, and `data` (stringified `query`). Sentry will group GraphQL client errors by the `operationName`, `operationType` and `statusCode`, so that you can easily see how many errors happened for a specific `operationName`, `operationType` and `statusCode`. From 2def437d5867fa6c398dea09445bbc8f49d790f5 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:47:38 +0200 Subject: [PATCH 05/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Liza Mock --- src/platforms/android/configuration/integrations/apollo3.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 2b2127ff193e9..76af06479fdf9 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -124,9 +124,9 @@ val apollo = ApolloClient.builder() Once enabled, this feature will automatically capture GraphQL client errors such as bad operations and response codes, and report them to Sentry as error events. Each error event will contain the `request` and `response` data, including the `url`, `status_code`, and `data` (stringified `query`). -Sentry will group GraphQL client errors by the `operationName`, `operationType` and `statusCode`, so that you can easily see how many errors happened for a specific `operationName`, `operationType` and `statusCode`. +Sentry will group GraphQL client errors by the `operationName`, `operationType`, and `statusCode`, so that you can easily see the number of errors that happened for each. -This feature is opt-in and can be enabled by setting the `captureFailedRequests` option to `true`: +This is an opt-in feature and can be enabled by setting the `captureFailedRequests` option to `true`: ```kotlin import com.apollographql.apollo3.ApolloClient From d264bb1ffc304f6a109a930be0d97a49a5c0ccd5 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:50:09 +0200 Subject: [PATCH 06/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Liza Mock --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 76af06479fdf9..ceae0058ce837 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -152,7 +152,7 @@ val apollo = ApolloClient.builder() .build() ``` -By default, error events won't contain `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: +By default, error events won't contain `Headers` or `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`: ```xml {filename:AndroidManifest.xml} From 1ba203528738b5a83a0f4d5700c87b0c51b8e81c Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:50:48 +0200 Subject: [PATCH 07/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Karl Heinz Struggl --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index ceae0058ce837..c696b930e4470 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -160,7 +160,7 @@ By default, error events won't contain `Headers` or `Cookies`, but you can chang ``` -Error events will contain the raw bodies of GraphQL requests and responses, the raw bodies can contain sensitive data, to avoid that, you can do the parametrization of your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field, using parametrized queries, [Relay](https://docs.sentry.io/product/relay) will run [PII Data Scrubbing](https://docs.sentry.io/product/relay/#pii-data-scrubbing) automatically transforming the values into `[Filtered]`. +Error events will contain the raw bodies of GraphQL requests and responses, which may include sensitive data. To avoid this, parameterize your queries using the [variables](https://spec.graphql.org/October2021/#sec-Language.Variables) field. [Relay](/product/relay) will then run [PII Data Scrubbing](/product/relay/#pii-data-scrubbing), automatically transforming values into `[Filtered]`. Alternatively, you can customize the event and scrub the data yourself. From b9d9c1adb2a7ff964a39272cb077ee6ba2ddbb0c Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:51:16 +0200 Subject: [PATCH 08/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Liza Mock --- src/platforms/android/configuration/integrations/apollo3.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index c696b930e4470..e636a9aaa51f5 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -166,9 +166,7 @@ Alternatively, you can customize the event and scrub the data yourself. ### Customize or Drop the Error Event -To customize or drop the error event, you need to do a [manual initialization](/platforms/android/configuration/manual-init/) of the Sentry Android SDK. - -The captured error event can be customized or dropped with a `BeforeSendCallback`: +To customize or drop the error event, you'll need to do a [manual initialization](/platforms/android/configuration/manual-init/) of the Sentry Android SDK. The captured error event can then be customized or dropped with a `BeforeSendCallback`: ```kotlin import io.sentry.android.core.SentryAndroid From 8218c378b2855e002d3b0a64ed52c9ec225fb796 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:51:26 +0200 Subject: [PATCH 09/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Liza Mock --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index e636a9aaa51f5..da0f5c0a9014f 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -189,7 +189,7 @@ SentryAndroid.init(this) { options -> } ``` -### Automatically Captured GraphQL Client Errors and Manually Captured Errors +### Automatically and Manually Captured GraphQL Client Errors When `captureFailedRequests` is enabled, some GraphQL client libraries throw unchecked exceptions like `ApolloException` and its implementations. In this case, the error event is captured twice; once by the GraphQL client library and once by the Sentry Android SDK: From 7da4eaacfeed21b324d8dbd01a7d3ddf63224fea Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto <5731772+marandaneto@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:51:47 +0200 Subject: [PATCH 10/23] Update src/platforms/android/configuration/integrations/apollo3.mdx Co-authored-by: Karl Heinz Struggl --- src/platforms/android/configuration/integrations/apollo3.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index da0f5c0a9014f..8c89dfff1ace6 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -191,7 +191,7 @@ SentryAndroid.init(this) { options -> ### Automatically and Manually Captured GraphQL Client Errors -When `captureFailedRequests` is enabled, some GraphQL client libraries throw unchecked exceptions like `ApolloException` and its implementations. In this case, the error event is captured twice; once by the GraphQL client library and once by the Sentry Android SDK: +When `captureFailedRequests` is enabled, some GraphQL client libraries will throw unchecked exceptions, such as the `ApolloException` and its implementations. This means the error event will be captured by both the GraphQL client library and the Sentry Android SDK. To avoid this, we recommend identifying these errors and using the `Sentry.captureException` method instead of capturing them manually: ```kotlin import io.sentry.Sentry From 5a0123e709ef45ae60cb994b33f52029cb2fff2f Mon Sep 17 00:00:00 2001 From: Michi Hoffmann Date: Tue, 13 Jun 2023 18:07:58 +0200 Subject: [PATCH 11/23] Use correct license identifer in package.json (#7141) --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 453bb796534b6..475fd88bfc70e 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "url": "git+https://github.com/getsentry/sentry-docs.git" }, "author": "getsentry", - "license": "BSL-1.1", + "license": "BUSL-1.1", "bugs": { "url": "https://github.com/getsentry/sentry-docs/issues" }, From ec90a51b1ed3d1768e436943109cdb8de06e0ff5 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Tue, 13 Jun 2023 19:01:00 +0200 Subject: [PATCH 12/23] Add hint about electron SDK version in source maps troubleshooting docs (#7140) --- .../sourcemaps/troubleshooting/javascript.mdx | 24 +++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/platform-includes/sourcemaps/troubleshooting/javascript.mdx b/src/platform-includes/sourcemaps/troubleshooting/javascript.mdx index 08a2b23eb6d0d..782216652a9ff 100644 --- a/src/platform-includes/sourcemaps/troubleshooting/javascript.mdx +++ b/src/platform-includes/sourcemaps/troubleshooting/javascript.mdx @@ -7,10 +7,26 @@ For information on the legacy method of uploading source maps, please see the gu Dependency versions that require the legacy method of uploading source maps include: -- JavaScript SDK version `7.46.0` or lower -- `@sentry/webpack-plugin` package version `1.x` or lower -- `sentry-cli` version `2.16.1` or lower -- Sentry self-hosted or single-tenant on version `23.4.0` or lower +
    + +
  • + Electron SDK version 4.5.0 or lower +
    • +     +
  • + JavaScript SDK version 7.46.0 or lower +
    • +
  • + @sentry/webpack-plugin package version 1.x or + lower +
    • +
  • + sentry-cli version 2.16.1 or lower +
    • +
  • + Sentry self-hosted or single-tenant on version 23.4.0 or lower +
    • +
From 230e3954279c9e3680e9b6747f8e0d9dc292ec4f Mon Sep 17 00:00:00 2001 From: Sentry Release Bot <75840458+getsentry-release@users.noreply.github.com> Date: Tue, 13 Jun 2023 11:03:34 -0700 Subject: [PATCH 13/23] Bump API schema to f88c7be1 (#7146) Co-authored-by: openapi-getsentry-bot --- src/gatsby/utils/resolveOpenAPI.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/gatsby/utils/resolveOpenAPI.ts b/src/gatsby/utils/resolveOpenAPI.ts index c1a3aafaca714..8a39c68f97509 100644 --- a/src/gatsby/utils/resolveOpenAPI.ts +++ b/src/gatsby/utils/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {promises as fs} from 'fs'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = '24e62b20d267b27565337ba4c644fe0403f156e2'; +const SENTRY_API_SCHEMA_SHA = 'f88c7be1c8f841b0268cfb8a1273af3a4006ae80'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development'; From 7790df5de2f6da859019a9ac4b53eb26c5f2cfd9 Mon Sep 17 00:00:00 2001 From: vivianyentran <20403606+vivianyentran@users.noreply.github.com> Date: Tue, 13 Jun 2023 13:02:47 -0700 Subject: [PATCH 14/23] Fix: Move team plan banner for metric alerts (#7147) Co-authored-by: Vivian Tran --- src/docs/product/alerts/alert-types.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/product/alerts/alert-types.mdx b/src/docs/product/alerts/alert-types.mdx index fc7bc9e25c6a7..d9fbb4b335840 100644 --- a/src/docs/product/alerts/alert-types.mdx +++ b/src/docs/product/alerts/alert-types.mdx @@ -40,6 +40,8 @@ The **Alert Details** page also includes a list of issues that triggered the ale ## Metric Alerts + + Metric alerts tell you when a [metric](/product/performance/metrics/) crosses a threshold, such as a spike in the number of errors in a project, or a change in a performance metric, like [latency](/product/performance/metrics/#latency), [Apdex](/product/performance/metrics/#apdex), [failure rate](/product/performance/metrics/#failure-rate), or [throughput](/product/performance/metrics/#throughput-total-tpm-tps). Metric alerts monitor macro-level metrics for both error and transaction events. A metric takes a set of events and computes an aggregate value using a function, such as `count()` or `avg()`, applied to the event properties over a period of time. When you create a metric alert, you can filter events by attributes and tags, which is particularly useful for aggregating across events that aren't grouped into single issues. @@ -61,8 +63,6 @@ When you create an alert, all the displayed alert types (except “Issues”) ma ### Sessions (Crash Rate Alerts) - - Crash rate alerts tell you when the crash free percentage for either [sessions or users](/product/releases/health/#active-sessionsusers) falls below a specific threshold. This could happen because of a spike in the number of session or user [crashes](/product/releases/health/#crash). Use crash rate alerts to monitor the health of your application per project, or in a specific release - Crash Free Session Rate From 3191a86563cad02995684f159cc82f53ce54d396 Mon Sep 17 00:00:00 2001 From: Shana Matthews Date: Tue, 13 Jun 2023 13:17:39 -0700 Subject: [PATCH 15/23] add redirects for sourcemaps best practices (#7148) --- vercel.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/vercel.json b/vercel.json index 1e875c3dc16bc..098e399b2e97f 100644 --- a/vercel.json +++ b/vercel.json @@ -423,6 +423,10 @@ { "source": "/platforms/python/guides/([^/]*)/configuration/integrations/flask/", "destination": "/platforms/python/guides/flask/" + }, + { + "source": "/platforms/node/guides/([^/]*)/sourcemaps/best-practices/", + "destination": "/platforms/node/guides/$1/sourcemaps/" } ] } From 23dcbcd16c5e03ca23e602d3a924fd014e0203e8 Mon Sep 17 00:00:00 2001 From: Shana Matthews Date: Tue, 13 Jun 2023 13:40:10 -0700 Subject: [PATCH 16/23] Add redirects (#7149) * add redirects for sourcemaps best practices * add clientdev redirects --- vercel.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/vercel.json b/vercel.json index 098e399b2e97f..c26196520f978 100644 --- a/vercel.json +++ b/vercel.json @@ -336,6 +336,10 @@ "source": "/clientdev/interfaces/http/", "destination": "https://develop.sentry.dev/sdk/event-payloads/request" }, + { + "source": "/clientdev/(.*)", + "destination": "https://develop.sentry.dev/sdk/" + }, { "source": "/platforms/([^/]*)/data-management/advanced-datascrubbing/", "destination": "/platforms/$1/data-management-settings/advanced-datascrubbing/" From 26fe322df52f408f175e6ddbd2cddcf4951a4c53 Mon Sep 17 00:00:00 2001 From: Karl Heinz Struggl Date: Wed, 14 Jun 2023 09:24:15 +0200 Subject: [PATCH 17/23] Remove link to Apple debug symbols (#7142) * remove link to Apple debug symbols page --- src/docs/clients/react-native/manual-setup.mdx | 4 ---- src/platforms/react-native/manual-setup/manual-setup.mdx | 3 --- 2 files changed, 7 deletions(-) diff --git a/src/docs/clients/react-native/manual-setup.mdx b/src/docs/clients/react-native/manual-setup.mdx index 58528572b7607..ee773863c51f6 100644 --- a/src/docs/clients/react-native/manual-setup.mdx +++ b/src/docs/clients/react-native/manual-setup.mdx @@ -83,10 +83,6 @@ export SENTRY_PROPERTIES=../sentry.properties ../node_modules/@sentry/cli/bin/sentry-cli debug-files upload "$DWARF_DSYM_FOLDER_PATH" ``` -For bitcode enabled builds via iTunes Connect, additional steps are required. -Follow the instructions at [With Bitcode](/clients/cocoa/dsym/#dsym-with-bitcode) to set up uploads of -symbols for all build variants. - Note that uploading of debug simulator builds by default is disabled for speed reasons. If you do want to also generate debug symbols for debug builds you can pass `--allow-fetch` as a parameter to `react-native-xcode` in the above mentioned build phase. ### Using node with nvm or notion diff --git a/src/platforms/react-native/manual-setup/manual-setup.mdx b/src/platforms/react-native/manual-setup/manual-setup.mdx index 8e0d79b2dabc2..5df84c8b125b4 100644 --- a/src/platforms/react-native/manual-setup/manual-setup.mdx +++ b/src/platforms/react-native/manual-setup/manual-setup.mdx @@ -77,9 +77,6 @@ SENTRY_CLI="../node_modules/@sentry/cli/bin/sentry-cli" $SENTRY_CLI debug-files upload "$INCLUDE_SOURCES_FLAG" "$DWARF_DSYM_FOLDER_PATH" ``` -For bitcode enabled builds via iTunes Connect, additional steps are required. -Follow the instructions in [Sentry's bitcode documentation](/clients/cocoa/dsym/#dsym-with-bitcode) to set up uploads of symbols for all build variants. - By default, uploading of debug simulator builds is disabled for speed reasons. If you want to generate debug symbols for debug builds, you can pass `--allow-fetch` as a parameter to `react-native-xcode` in the above mentioned build phase. ### Using node with nvm or Volta From 5c518591cc195800128fd15b1e068f22fc4aea4e Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Wed, 14 Jun 2023 10:26:21 +0200 Subject: [PATCH 18/23] Add React Router Info to Onboarding Wizard (#7136) Add React Router Info to: *src/wizard/javascript/react/index.md * src/wizard/javascript/react/with-error-monitoring-performance-and-replay.md * src/wizard/javascript/react/with-error-monitoring-and-performance.md --- src/wizard/javascript/react/index.md | 1 + .../javascript/react/with-error-monitoring-and-performance.md | 1 + .../react/with-error-monitoring-performance-and-replay.md | 1 + 3 files changed, 3 insertions(+) diff --git a/src/wizard/javascript/react/index.md b/src/wizard/javascript/react/index.md index e9ae4f39332bf..9a35500c6a5ad 100644 --- a/src/wizard/javascript/react/index.md +++ b/src/wizard/javascript/react/index.md @@ -64,4 +64,5 @@ return ; - [Source Maps](https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/): Learn how to enable readable stack traces in your Sentry errors. - [React Features](https://docs.sentry.io/platforms/javascript/guides/react/features/): Learn about our first class integration with the React framework. +- [React Router](https://docs.sentry.io/platforms/javascript/guides/react/configuration/integrations/react-router/): Configure routing, so Sentry can generate parameterized transaction names for a better overview in Performance Monitoring. - [Session Replay](https://docs.sentry.io/platforms/javascript/guides/react/session-replay/): Get to the root cause of an error or latency issue faster by seeing all the technical details related to that issue in one visual replay on your web application. diff --git a/src/wizard/javascript/react/with-error-monitoring-and-performance.md b/src/wizard/javascript/react/with-error-monitoring-and-performance.md index 3331ab01c5886..f27dc8dc7debe 100644 --- a/src/wizard/javascript/react/with-error-monitoring-and-performance.md +++ b/src/wizard/javascript/react/with-error-monitoring-and-performance.md @@ -58,4 +58,5 @@ return ; - [Source Maps](https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/): Learn how to enable readable stack traces in your Sentry errors. - [React Features](https://docs.sentry.io/platforms/javascript/guides/react/features/): Learn about our first class integration with the React framework. +- [React Router](https://docs.sentry.io/platforms/javascript/guides/react/configuration/integrations/react-router/): Configure routing, so Sentry can generate parameterized transaction names for a better overview in Performance Monitoring. - [Session Replay](https://docs.sentry.io/platforms/javascript/guides/react/session-replay/): Get to the root cause of an error or latency issue faster by seeing all the technical details related to that issue in one visual replay on your web application. diff --git a/src/wizard/javascript/react/with-error-monitoring-performance-and-replay.md b/src/wizard/javascript/react/with-error-monitoring-performance-and-replay.md index 7753e064de699..dadf072e0f908 100644 --- a/src/wizard/javascript/react/with-error-monitoring-performance-and-replay.md +++ b/src/wizard/javascript/react/with-error-monitoring-performance-and-replay.md @@ -62,3 +62,4 @@ return ; - [Source Maps](https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/): Learn how to enable readable stack traces in your Sentry errors. - [React Features](https://docs.sentry.io/platforms/javascript/guides/react/features/): Learn about our first class integration with the React framework. +- [React Router](https://docs.sentry.io/platforms/javascript/guides/react/configuration/integrations/react-router/): Configure routing, so Sentry can generate parameterized transaction names for a better overview in Performance Monitoring. From 5bd1813e2c104ab48e0a9d9f9f6593f9d5df17d4 Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 14 Jun 2023 10:36:49 +0200 Subject: [PATCH 19/23] Re-add troubleshooting guide for legacy source map upload (#7126) --- .../legacy-uploading-methods/javascript.mdx | 250 +++++++++++++++++- 1 file changed, 248 insertions(+), 2 deletions(-) diff --git a/src/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx b/src/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx index 7153550a37249..8fb61727fc5ba 100644 --- a/src/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx +++ b/src/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx @@ -236,6 +236,252 @@ Sentry.init({ }); ``` -## Verify Artifacts Were Uploaded +## Troubleshooting -Open up Sentry and navigate to **[Settings] > Projects > Select your project > Source Maps** on Sentry. +If you followed all of the steps above but still have issues setting up source maps using the legacy method this section will try to help troubleshoot your setup. + +To troubleshoot your source maps set up, you can either: + +1. Use our automated verification tool inside `sentry-cli`, or +2. Follow the manual steps listed below + +### Use the Sentry CLI + +To use the automated verification process, install and configure the Sentry [Command Line Interface](/product/cli/). Then, use the `sourcemaps explain` command, calling it with the relevant event ID, found in the top-left corner of the **Issue Details** page in [sentry.io](https://sentry.io). + +For example, "Event ID: c2ad049f": + +![Image highlighting where to find the ID of an event on Sentry](../troubleshooting/event_id.png) + +```shell +sentry-cli sourcemaps explain c2ad049fd9e448ada7849df94575e019 +``` + +The CLI output should give you useful information about what went wrong with your source maps setup. + + + +### Verify a release is configured in your SDK + +For uploaded source maps to be located and applied, the release needs to be created by the CLI or API (and the correct artifacts uploaded with it), and the name of that newly-created release needs to be specified in your SDK configuration. + +To verify this, open up the issue from the Sentry UI and check if the release is configured. If it says "_not configured_" or "_N/A_" next to **Release** on the right hand side of the screen (or if you do not see a `release` tag in the list of tags), you'll need to go back and [tag your errors](../../../configuration/releases/). If this is properly set up you'll see "Release: my_example_release". + + + +### Verify artifacts are uploaded + +Once your release is properly configured and issues are tagged, you can find the artifacts uploaded to Sentry by navigating to **[Settings] > Projects > Select your project > Source Maps**. + +Additionally, make sure all of the necessary files are available. For Sentry to de-minify your stack traces you must provide both the minified files (for example, app.min.js) and the corresponding source maps. In case the source map files do not contain your original source code (`sourcesContent`), you must additionally provide the original source files. Alternatively, sentry-cli will automatically embed the sources (if missing) into your source maps. + +### Verify `sourceMappingURL` is present + +Some CDNs automatically strip comments from static files, including JavaScript files. This can have the effect of stripping your JavaScript file of its `sourceMappingURL` directive, because it is considered a comment. For example, CloudFlare has a feature called [Auto-Minify](https://blog.cloudflare.com/an-all-new-and-improved-autominify/) which will strip `sourceMappingURL` if it is enabled. + +Double-check that your deployed, final JavaScript files have `sourceMappingURL` present. + +Alternately, instead of `sourceMappingURL`, you can set a `SourceMap` HTTP header on your minified file. If this header is present, Sentry will use it to discover the location of your source map. + + + +### Verify artifact distribution value matches value configured in your SDK + +Whenever you are using a distribution identifier (the `dist` configuration option in the SDK), the same value has to be used during source map upload. Conversely, if your source maps are getting uploaded with a `dist` value, the same value must be set in your SDK. +To add a `dist` value to your uploaded source maps, use the `--dist` flag with `sentry-cli` or the `dist` option in our [Sentry Bundler Plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins) (like for example `@sentry/webpack-plugin`). To set the `dist` value in the SDK, use the `dist` option in your `Sentry.init()`. + +To verify that the distribution has been set correctly in the SDK, open an issue in the Sentry UI and check that the `dist` tag is present. For artifacts, go to the `Source Maps` page in project settings, choose the release shown on the event you just checked, and verify that the `dist` value (in the small oval next to the upload time) matches that on the event. + + + +### Verify artifact names match stack trace frames + +If you've uploaded source maps and they aren't applying to your code in an issue in Sentry, take a look at the JSON of the event and look for the `abs_path` to see exactly where we're attempting to resolve the file - for example, `http://localhost:8000/scripts/script.js` (`abs_path` will appear once for each frame in the stack trace - match this up with the file(s) that are not deminified.). A link to the JSON view can be found at the top of the issue page next to the date the event occurred. The uploaded artifact names must match these values. + +If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. + +#### Using sentry-cli + +If your `sourceMappingURL` comment is similar to: + +```javascript +// -- end script.min.js (located at http://localhost:8000/scripts/script.min.js) +//# sourceMappingURL=script.min.js.map +``` + +An example `sentry-cli` command to upload these files correctly would look like this (assuming you're in the `/scripts` directory, running your web server from one directory higher, which is why we're using the `--url-prefix` option): + +```shell +sentry-cli releases files VERSION upload-sourcemaps . --url-prefix '~/scripts' +``` + +This command uploads all JavaScript files in the current directory. The Artifacts page in Sentry should now look like: + +``` +~/scripts/script.js +~/scripts/script.min.js +~/scripts/script.min.js.map +``` + +Alternately you can specify which files to upload. For example: + +``` +sentry-cli releases files VERSION upload-sourcemaps script.min.js script.min.js.map --url-prefix '~/scripts' +``` + +You can also upload it with the fully qualified URL. For example: + +``` +sentry-cli releases files VERSION upload-sourcemaps . --url-prefix 'http://localhost:8000/scripts' +``` + +#### Using the API + +You can alternately [use our API](/api/releases/update-an-organization-release-file/) to upload artifacts, following the same naming convention explained here. + +```shell +curl -X POST \ + https://sentry.io/api/0/organizations/ORG_SLUG/releases/VERSION/files/ \ + -H 'Authorization: Bearer AUTH_TOKEN' \ + -H 'content-type: multipart/form-data' \ + -F file=@script.min.js.map \ + -F 'name=~/scripts/script.min.js.map' +``` + +#### Using the `~` + +The `~` is used in Sentry to replace the scheme and domain. It is not a glob! + +`http://example.com/dist/js/script.js` will match `~/dist/js/script.js` or `http://example.com/dist/js/script.js` + +but will NOT match `~/script.js`. + +### Multiple Origins + +It's not uncommon for a web application to be accessible at multiple origins. For example: + +- Website is operable over both `https` and `http` +- Geolocated web addresses: such as `https://us.example.com`, `https://eu.example.com` +- Multiple static CDNs: such as `https://static1.example.com`, `https://static2.example.com` +- Customer-specific domains/subdomains + +In this situation, **identical** JavaScript and source map files may be located at two or more distinct origins. In this situation we recommend using our special tilde (`~`) prefix on paths. + +So for example, if you have the following: + +- https://static1.example.com/js/app.js +- https://static2.example.com/js/app.js + +You can upload using the URL of `~/js/app.js`. This will tell Sentry to ignore the domain and use the artifact for any origin. + +Additionally you can also upload the same file under multiple names. Under the hood Sentry will deduplicate these. + + + +The ~ prefix tells Sentry that for a given URL, **any** combination of protocol and hostname whose path is `/js/app.js` should use this artifact. Use this method **only** if your source/source map files are identical at all possible protocol/hostname combinations. **Sentry will prioritize full URLs over tilde prefixed paths**, if found. + + + +### Verify artifact names match `sourceMappingURL` value + +The `sourceMappingURL` comment on the last line of your bundled or minified JavaScript file tells Sentry (or the browser) where to locate the corresponding source map. This can either be a fully qualified URL, a relative path, or the filename itself. When uploading artifacts to Sentry, you must name your source map files with the value the file resolves to. + +That is, if your file is similar to: + +```javascript +// -- end script.min.js +//# sourceMappingURL=script.min.js.map +``` + +and is hosted at http://example.com/js/script.min.js, then Sentry will look for that source map file at http://example.com/js/script.min.js.map. Your uploaded artifact must therefore be named `http://example.com/js/script.min.js.map` (or `~/js/script.min.js.map`). + +Or, if your file is similar to: + +```javascript +//-- end script.min.js +//# sourceMappingURL=https://example.com/dist/js/script.min.js.map +``` + +then your uploaded artifact should also be named `https://example.com/dist/js/script.min.js.map` (or `~/dist/js/script.min.js.map`). + +Finally, if your file is similar to: + +```javascript +//-- end script.min.js +//# sourceMappingURL=../maps/script.min.js.map +``` + +then your uploaded artifact should be named `https://example.com/dist/maps/script.min.js.map` (or `~/dist/maps/script.min.js.map`). + +###Verify Artifacts Are Uploaded Before Errors Occur + +Sentry expects that source code and source maps in a given release are uploaded to Sentry **before** errors occur in that release. + +If you upload artifacts **after** an error is captured by Sentry, Sentry will not go back and retroactively apply any source annotations to those errors. Only new errors triggered after the artifact was uploaded will be affected. + +### Verify your source maps are built correctly + +We maintain an online validation tool that can be used to test your source maps against your **hosted** source: [sourcemaps.io](https://sourcemaps.io). + +Alternatively, if you are using Sentry CLI to upload source maps to Sentry, you can use the `--validate` command line option to verify your source maps are correct. + +### Verify your source maps work locally + +If you find that Sentry is not mapping filename, line, or column mappings correctly, you should verify that your source maps are functioning locally. To do so, you can use Node.js coupled with Mozilla's [source-map library](https://github.com/mozilla/source-map). + +First, install `source-map` globally as an npm module: + +```bash +npm install -g source-map +``` + +Then, write a Node.js script that reads your source map file and tests a mapping. Here's an example: + +```javascript +var fs = require("fs"), + path = require("path"), + sourceMap = require("source-map"); + +// Path to file that is generated by your build tool (webpack, tsc, ...) +var GENERATED_FILE = path.join(".", "app.min.js.map"); + +// Line and column located in your generated file (for example, the source +// of the error from your minified file) +var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 }; + +var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString(); +new sourceMap.SourceMapConsumer(rawSourceMap).then(function (smc) { + var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN); + + // You should see something like: + // { source: 'original.js', line: 57, column: 9, name: 'myfunc' } + console.log(pos); +}); +``` + +If you have the same (incorrect) results locally as you do via Sentry, double-check your source map generation configuration. + +### Verify your source files are not too large + +For an individual artifact, Sentry accepts a max filesize of **40 MB**. + +Often users hit this limit because they are transmitting source files at an interim build stage. For example, after your bundler has combined all your source files, but before minification has taken place. If possible, send the original source files. + +### Verify artifacts are not gzipped + +The Sentry API currently only works with source maps and source files that are uploaded as plain text (UTF-8 encoded). If the files are uploaded in a compressed format (for example, gzip), they will be not be interpreted correctly. + +If you are using `sentry-cli` to upload your artifacts, starting with version `2.4.0` you can add the `--decompress` flag to your `sourcemaps upload` or `files upload` commands. + +Sometimes build scripts and plugins produce pre-compressed minified files (for example, Webpack's [compression plugin](https://github.com/webpack/compression-webpack-plugin)). In these cases, you'll need to disable such plugins and perform the compression **after** the generated source maps/source files have been uploaded to Sentry. + +### Verify workers are sharing the same volume as web (if running self-hosted Sentry via Docker) + +Sentry does source map calculation in its workers. This means the workers need access to the files uploaded through the front end. Double check that the cron workers and web workers can read/write files from the same disk. + +### Verify you are not using the `source-map-support` package + +The Sentry Node.js SDK generally works well with the [source-map-support](https://www.npmjs.com/package/source-map-support) package if you don't already have source maps uploaded to Sentry. + +If you are uploading source maps to Sentry or if you are using a Sentry SDK in the browser, your code cannot use the `source-map-support` package. +`source-map-support` overwrites the captured stack trace in a way that prevents our source map processors from correctly parsing it. From b27558cb263f93893fd9037c44e3d1090f55f3ea Mon Sep 17 00:00:00 2001 From: Luca Forstner Date: Wed, 14 Jun 2023 10:37:03 +0200 Subject: [PATCH 20/23] Restore troubleshooting sourcemaps docs for platforms that support debug IDs yet (#7139) --- .../legacy-troubleshooting/javascript.mdx | 241 ++++++++++++++++++ .../troubleshooting_js/artifact-bundles.mdx | 6 + .../sourcemaps/troubleshooting_js/index.mdx | 24 +- .../legacy-uploading-methods.mdx | 6 + 4 files changed, 276 insertions(+), 1 deletion(-) create mode 100644 src/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx diff --git a/src/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx b/src/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx new file mode 100644 index 0000000000000..c3780fc0708f0 --- /dev/null +++ b/src/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx @@ -0,0 +1,241 @@ +Setting up source maps can be tricky, but it's worth it to get it right. To troubleshoot your source maps set up, you can either: + +1. Use our automated verification tool inside `sentry-cli`, or +2. Follow the manual steps listed below + +## Use the Sentry CLI + +To use the automated verification process, install and configure the Sentry [Command Line Interface](/product/cli/). Then, use the `sourcemaps explain` command, calling it with the relevant event ID, found in the top-left corner of the **Issue Details** page in [sentry.io](https://sentry.io). + +For example, "Event ID: c2ad049f": + +![Image highlighting where to find the ID of an event on Sentry](../troubleshooting/event_id.png) + +```shell +sentry-cli sourcemaps explain c2ad049fd9e448ada7849df94575e019 +``` + +The CLI output should give you useful information about what went wrong with your source maps setup. + + + +## Verify a release is configured in your SDK + +For uploaded source maps to be located and applied, the release needs to be created by the CLI or API (and the correct artifacts uploaded with it), and the name of that newly-created release needs to be specified in your SDK configuration. + +To verify this, open up the issue from the Sentry UI and check if the release is configured. If it says "_not configured_" or "_N/A_" next to **Release** on the right hand side of the screen (or if you do not see a `release` tag in the list of tags), you'll need to go back and [tag your errors](../../configuration/releases/). If this is properly set up you'll see "Release: my_example_release". + + + +## Verify artifacts are uploaded + +Once your release is properly configured and issues are tagged, you can find the artifacts uploaded to Sentry by navigating to **[Settings] > Projects > Select your project > Source Maps**. + +Additionally, make sure all of the necessary files are available. For Sentry to de-minify your stack traces you must provide both the minified files (for example, app.min.js) and the corresponding source maps. In case the source map files do not contain your original source code (`sourcesContent`), you must additionally provide the original source files. Alternatively, sentry-cli will automatically embed the sources (if missing) into your source maps. + +## Verify `sourceMappingURL` is present + +Some CDNs automatically strip comments from static files, including JavaScript files. This can have the effect of stripping your JavaScript file of its `sourceMappingURL` directive, because it is considered a comment. For example, CloudFlare has a feature called [Auto-Minify](https://blog.cloudflare.com/an-all-new-and-improved-autominify/) which will strip `sourceMappingURL` if it is enabled. + +Double-check that your deployed, final JavaScript files have `sourceMappingURL` present. + +Alternately, instead of `sourceMappingURL`, you can set a `SourceMap` HTTP header on your minified file. If this header is present, Sentry will use it to discover the location of your source map. + + + +## Verify artifact distribution value matches value configured in your SDK + +Whenever you are using a distribution identifier (the `dist` configuration option in the SDK), the same value has to be used during source map upload. Conversely, if your source maps are getting uploaded with a `dist` value, the same value must be set in your SDK. +To add a `dist` value to your uploaded source maps, use the `--dist` flag with `sentry-cli` or the `dist` option in our [Sentry Bundler Plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins) (like for example `@sentry/webpack-plugin`). To set the `dist` value in the SDK, use the `dist` option in your `Sentry.init()`. + +To verify that the distribution has been set correctly in the SDK, open an issue in the Sentry UI and check that the `dist` tag is present. For artifacts, go to the `Source Maps` page in project settings, choose the release shown on the event you just checked, and verify that the `dist` value (in the small oval next to the upload time) matches that on the event. + + + +## Verify artifact names match stack trace frames + +If you've uploaded source maps and they aren't applying to your code in an issue in Sentry, take a look at the JSON of the event and look for the `abs_path` to see exactly where we're attempting to resolve the file - for example, `http://localhost:8000/scripts/script.js` (`abs_path` will appear once for each frame in the stack trace - match this up with the file(s) that are not deminified.). A link to the JSON view can be found at the top of the issue page next to the date the event occurred. The uploaded artifact names must match these values. + +If you have **dynamic values in your path** (for example, `https://www.site.com/{some_value}/scripts/script.js`), you may want to use the `rewriteFrames` integration`rewriteFrames` integration to change your `abs_path` values. + +### Using sentry-cli + +If your `sourceMappingURL` comment is similar to: + +```javascript +// -- end script.min.js (located at http://localhost:8000/scripts/script.min.js) +// sourceMappingURL=script.min.js.map +``` + +An example `sentry-cli` command to upload these files correctly would look like this (assuming you're in the `/scripts` directory, running your web server from one directory higher, which is why we're using the `--url-prefix` option): + +```shell +sentry-cli releases files VERSION upload-sourcemaps . --url-prefix '~/scripts' +``` + +This command uploads all JavaScript files in the current directory. The Artifacts page in Sentry should now look like: + +``` +~/scripts/script.js +~/scripts/script.min.js +~/scripts/script.min.js.map +``` + +Alternately you can specify which files to upload. For example: + +``` +sentry-cli releases files VERSION upload-sourcemaps script.min.js script.min.js.map --url-prefix '~/scripts' +``` + +You can also upload it with the fully qualified URL. For example: + +``` +sentry-cli releases files VERSION upload-sourcemaps . --url-prefix 'http://localhost:8000/scripts' +``` + +### Using the API + +You can alternately [use our API](/api/releases/update-an-organization-release-file/) to upload artifacts, following the same naming convention explained here. + +```shell +curl -X POST \ + https://sentry.io/api/0/organizations/ORG_SLUG/releases/VERSION/files/ \ + -H 'Authorization: Bearer AUTH_TOKEN' \ + -H 'content-type: multipart/form-data' \ + -F file=@script.min.js.map \ + -F 'name=~/scripts/script.min.js.map' +``` + +### Using the `~` + +The `~` is used in Sentry to replace the scheme and domain. It is not a glob! + +`http://example.com/dist/js/script.js` will match `~/dist/js/script.js` or `http://example.com/dist/js/script.js` + +but will NOT match `~/script.js`. + +## Multiple Origins + +It's not uncommon for a web application to be accessible at multiple origins. For example: + +- Website is operable over both `https` and `http` +- Geolocated web addresses: such as `https://us.example.com`, `https://eu.example.com` +- Multiple static CDNs: such as `https://static1.example.com`, `https://static2.example.com` +- Customer-specific domains/subdomains + +In this situation, **identical** JavaScript and source map files may be located at two or more distinct origins. In this situation we recommend using our special tilde (`~`) prefix on paths. + +So for example, if you have the following: + +- https://static1.example.com/js/app.js +- https://static2.example.com/js/app.js + +You can upload using the URL of `~/js/app.js`. This will tell Sentry to ignore the domain and use the artifact for any origin. + +Additionally you can also upload the same file under multiple names. Under the hood Sentry will deduplicate these. + + + +The ~ prefix tells Sentry that for a given URL, **any** combination of protocol and hostname whose path is `/js/app.js` should use this artifact. Use this method **only** if your source/source map files are identical at all possible protocol/hostname combinations. **Sentry will prioritize full URLs over tilde prefixed paths**, if found. + + + +## Verify artifact names match `sourceMappingURL` value + +The `sourceMappingURL` comment on the last line of your bundled or minified JavaScript file tells Sentry (or the browser) where to locate the corresponding source map. This can either be a fully qualified URL, a relative path, or the filename itself. When uploading artifacts to Sentry, you must name your source map files with the value the file resolves to. + +That is, if your file is similar to: + +```javascript +// -- end script.min.js +// sourceMappingURL=script.min.js.map +``` + +and is hosted at http://example.com/js/script.min.js, then Sentry will look for that source map file at http://example.com/js/script.min.js.map. Your uploaded artifact must therefore be named `http://example.com/js/script.min.js.map` (or `~/js/script.min.js.map`). + +Or, if your file is similar to: + +```javascript +//-- end script.min.js +// sourceMappingURL=https://example.com/dist/js/script.min.js.map +``` + +then your uploaded artifact should also be named `https://example.com/dist/js/script.min.js.map` (or `~/dist/js/script.min.js.map`). + +Finally, if your file is similar to: + +```javascript +//-- end script.min.js +// sourceMappingURL=../maps/script.min.js.map +``` + +then your uploaded artifact should be named `https://example.com/dist/maps/script.min.js.map` (or `~/dist/maps/script.min.js.map`). + +###Verify Artifacts Are Uploaded Before Errors Occur + +Sentry expects that source code and source maps in a given release are uploaded to Sentry **before** errors occur in that release. + +If you upload artifacts **after** an error is captured by Sentry, Sentry will not go back and retroactively apply any source annotations to those errors. Only new errors triggered after the artifact was uploaded will be affected. + +## Verify your source maps are built correctly + +We maintain an online validation tool that can be used to test your source maps against your **hosted** source: [sourcemaps.io](https://sourcemaps.io). + +Alternatively, if you are using Sentry CLI to upload source maps to Sentry, you can use the `--validate` command line option to verify your source maps are correct. + +## Verify your source maps work locally + +If you find that Sentry is not mapping filename, line, or column mappings correctly, you should verify that your source maps are functioning locally. To do so, you can use Node.js coupled with Mozilla's [source-map library](https://github.com/mozilla/source-map). + +First, install `source-map` globally as an npm module: + +```bash +npm install -g source-map +``` + +Then, write a Node.js script that reads your source map file and tests a mapping. Here's an example: + +```javascript +var fs = require("fs"), + path = require("path"), + sourceMap = require("source-map"); +// Path to file that is generated by your build tool (webpack, tsc, ...) +var GENERATED_FILE = path.join(".", "app.min.js.map"); +// Line and column located in your generated file (for example, the source +// of the error from your minified file) +var GENERATED_LINE_AND_COLUMN = { line: 1, column: 1000 }; +var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString(); +new sourceMap.SourceMapConsumer(rawSourceMap).then(function (smc) { + var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN); + // You should see something like: + // { source: 'original.js', line: 57, column: 9, name: 'myfunc' } + console.log(pos); +}); +``` + +If you have the same (incorrect) results locally as you do via Sentry, double-check your source map generation configuration. + +## Verify your source files are not too large + +For an individual artifact, Sentry accepts a max filesize of **40 MB**. + +Often users hit this limit because they are transmitting source files at an interim build stage. For example, after your bundler has combined all your source files, but before minification has taken place. If possible, send the original source files. + +## Verify artifacts are not gzipped + +The Sentry API currently only works with source maps and source files that are uploaded as plain text (UTF-8 encoded). If the files are uploaded in a compressed format (for example, gzip), they will be not be interpreted correctly. + +If you are using `sentry-cli` to upload your artifacts, starting with version `2.4.0` you can add the `--decompress` flag to your `sourcemaps upload` or `files upload` commands. + +Sometimes build scripts and plugins produce pre-compressed minified files (for example, Webpack's [compression plugin](https://github.com/webpack/compression-webpack-plugin)). In these cases, you'll need to disable such plugins and perform the compression **after** the generated source maps/source files have been uploaded to Sentry. + +## Verify workers are sharing the same volume as web (if running self-hosted Sentry via Docker) + +Sentry does source map calculation in its workers. This means the workers need access to the files uploaded through the front end. Double check that the cron workers and web workers can read/write files from the same disk. + +## Verify you are not using the `source-map-support` package + +The Sentry Node.js SDK generally works well with the [source-map-support](https://www.npmjs.com/package/source-map-support) package if you don't already have source maps uploaded to Sentry. + +If you are uploading source maps to Sentry or if you are using a Sentry SDK in the browser, your code cannot use the `source-map-support` package. +`source-map-support` overwrites the captured stack trace in a way that prevents our source map processors from correctly parsing it. diff --git a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx index d5fd104ec38f1..c49e52097f819 100644 --- a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx +++ b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/artifact-bundles.mdx @@ -1,6 +1,12 @@ --- title: What are Artifact Bundles description: "Learn about artifact bundles." +notSupported: + - javascript.capacitor + - javascript.cordova + - javascript.nextjs + - javascript.remix + - javascript.sveltekit sidebar_order: 6 --- diff --git a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/index.mdx b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/index.mdx index de761b813de5b..bb1f55f8c75cb 100644 --- a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/index.mdx +++ b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/index.mdx @@ -6,4 +6,26 @@ description: "Troubleshooting for source maps." sidebar_order: 5 --- - + + + + + + + diff --git a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/legacy-uploading-methods.mdx b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/legacy-uploading-methods.mdx index 59baab5acef32..c7fe1cb04e946 100644 --- a/src/platforms/javascript/common/sourcemaps/troubleshooting_js/legacy-uploading-methods.mdx +++ b/src/platforms/javascript/common/sourcemaps/troubleshooting_js/legacy-uploading-methods.mdx @@ -2,6 +2,12 @@ title: Legacy Uploading Methods description: "Learn about how to upload source maps with older SDKs and Sentry tools." sidebar_order: 5 +notSupported: + - javascript.capacitor + - javascript.cordova + - javascript.nextjs + - javascript.remix + - javascript.sveltekit redirect_from: - /platforms/javascript/sourcemaps/troubleshooting_js/uploading-without-debug-ids/ --- From 466c281f6d63e5f891641f7a37029b07a024d0d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kry=C5=A1tof=20Wold=C5=99ich?= <31292499+krystofwoldrich@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:39:45 +0200 Subject: [PATCH 21/23] Add iOS source context info to RN debug symbols page (#7143) Co-authored-by: Shana Matthews --- src/platforms/react-native/upload-debug.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/platforms/react-native/upload-debug.mdx b/src/platforms/react-native/upload-debug.mdx index c23227f73d7cc..ee8a3787dc869 100644 --- a/src/platforms/react-native/upload-debug.mdx +++ b/src/platforms/react-native/upload-debug.mdx @@ -16,6 +16,12 @@ Errors raised from the native layer in Android apps require certain debug inform Upload the [Android ProGuard/R8 mapping files and native symbols](/platforms/android/proguard/) by the recommended method of using our Gradle integration. +## Uploading With Xcode + +To upload native iOS debug symbols, set up a Run Script build phase for uploading debug symbols to Sentry with the Sentry CLI. You can find documentation for this on the [Manual Configuration](/platforms/react-native/manual-setup/manual-setup/#upload-debug-symbols-to-sentry) page. + +To enable [Source Context](/platforms/apple/guides/ios/data-management/debug-files/source-context/) set `SENTRY_INCLUDE_NATIVE_SOURCES=true` before the build. + ## Uploading With sentry-cli Upload the [Android ProGuard/R8 mapping files and native symbols](/product/cli/) manually by using `sentry-cli` [upload-proguard](/product/cli/dif/#proguard-mapping-upload) and [debug-files](/product/cli/dif/#uploading-files). From c14aaea6f47cb63db6fe15e5696059bfbfda9a8f Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Wed, 14 Jun 2023 10:52:09 +0200 Subject: [PATCH 22/23] fix --- src/platforms/android/configuration/integrations/apollo3.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/platforms/android/configuration/integrations/apollo3.mdx b/src/platforms/android/configuration/integrations/apollo3.mdx index 8c89dfff1ace6..2d134fc16891f 100644 --- a/src/platforms/android/configuration/integrations/apollo3.mdx +++ b/src/platforms/android/configuration/integrations/apollo3.mdx @@ -138,7 +138,7 @@ val apollo = ApolloClient.builder() .build() ``` -By default, only GraphQL client errors with a response that includes the [errors](https://spec.graphql.org/October2021/#sec-Errors) array are captured as error events. +By default, only GraphQL client errors with a response that includes the [errors](https://spec.graphql.org/October2021/#sec-Errors) array will be captured as error events. GraphQL client errors from every target (`.*` regular expression) are automatically captured, but you can change this behavior by setting the `failedRequestTargets` option with either a regular expression or a plain `String`. A plain string must contain at least one of the items from the list. Plain strings don't have to be full matches, meaning the URL of a request is matched when it contains a string provided through the option. @@ -205,5 +205,3 @@ try { // Sentry.captureException(e) } ``` - -We recommend you identify those errors and **not** capture them manually with the `Sentry.captureException` method. From f7cd85ab83173831a00c4176d836d482fe6a8c2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kry=C5=A1tof=20Wold=C5=99ich?= <31292499+krystofwoldrich@users.noreply.github.com> Date: Wed, 14 Jun 2023 10:51:49 +0200 Subject: [PATCH 23/23] Add Apple Debug Symbols Sentry CLI link to RN manual setup page (#7151) --- src/platforms/react-native/manual-setup/manual-setup.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/platforms/react-native/manual-setup/manual-setup.mdx b/src/platforms/react-native/manual-setup/manual-setup.mdx index 5df84c8b125b4..c171eee231978 100644 --- a/src/platforms/react-native/manual-setup/manual-setup.mdx +++ b/src/platforms/react-native/manual-setup/manual-setup.mdx @@ -79,6 +79,8 @@ $SENTRY_CLI debug-files upload "$INCLUDE_SOURCES_FLAG" "$DWARF_DSYM_FOLDER_PATH" By default, uploading of debug simulator builds is disabled for speed reasons. If you want to generate debug symbols for debug builds, you can pass `--allow-fetch` as a parameter to `react-native-xcode` in the above mentioned build phase. +For more information visit [Sentry CLI Apple Debug Symbols](/platforms/apple/dsym/#sentry-cli) documentation. + ### Using node with nvm or Volta If you are using nvm or notion, Xcode has trouble locating the default node binary, which can look similar to the [troubleshooting example](/platforms/react-native/troubleshooting/#using-node-with-nvm-or-volta).