diff --git a/docs/concepts/key-terms/tracing/event-detail.mdx b/docs/concepts/key-terms/tracing/event-detail.mdx deleted file mode 100644 index e69de29bb2d1d6..00000000000000 diff --git a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx index f4ba56683c2d86..cf140e80b1134b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx @@ -19,6 +19,47 @@ Sentry.init({ }); ``` +## Options + +### `shouldHandleError` + +A function that decides whether an error is captured. By default, errors with a 5xx status code (and errors with a 2xx status code or lower) are captured, and errors with a 3xx or 4xx status code aren't. + +```typescript +declare function shouldHandleError( + error: Error, + request: FastifyRequest, + reply: FastifyReply +): boolean; +``` + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.fastifyIntegration({ + shouldHandleError(error, request, reply) { + return reply.statusCode >= 500; + }, + }), + ], +}); +``` + +If you use TypeScript, cast the request and reply to get full type safety: + +```typescript +import type { FastifyRequest, FastifyReply } from "fastify"; + +Sentry.fastifyIntegration({ + shouldHandleError(error, minimalRequest, minimalReply) { + const request = minimalRequest as FastifyRequest; + const reply = minimalReply as FastifyReply; + return reply.statusCode >= 500; + }, +}); +``` + ## Supported Versions - `fastify`: `^3.21.0 || ^4.0.0` diff --git a/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx b/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx index b5c70dd09409fc..dae753d55eacb4 100644 --- a/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx @@ -1,7 +1,7 @@ --- title: "Scrubbing Sensitive Data" description: "Learn about filtering or scrubbing sensitive data within the Sentry JavaScript SDK, so that data is not sent with the event. You can also configure server-side scrubbing to ensure the data is not stored." -customCanonicalTag: "/platforms/javascript/guides/koa/data-management/sensitive-data/" +customCanonicalTag: "/platforms/javascript/guides/node/data-management/sensitive-data/" sidebar_order: 100 keywords: - pii diff --git a/docs/platforms/javascript/common/sourcemaps/uploading/rollup.mdx b/docs/platforms/javascript/common/sourcemaps/uploading/rollup.mdx index 29b44acd07dd1b..3c8f4aac66d5cb 100644 --- a/docs/platforms/javascript/common/sourcemaps/uploading/rollup.mdx +++ b/docs/platforms/javascript/common/sourcemaps/uploading/rollup.mdx @@ -2,7 +2,7 @@ title: Rollup description: "Upload your source maps with the Sentry Rollup Plugin." sidebar_order: 5 -customCanonicalTag: "/platforms/javascript/guides/koa/sourcemaps/uploading/rollup/" +customCanonicalTag: "/platforms/javascript/guides/node/sourcemaps/uploading/rollup/" --- diff --git a/docs/platforms/javascript/guides/bun/index.mdx b/docs/platforms/javascript/guides/bun/index.mdx index d70ce4d8aa9aca..6d5107d0bac231 100644 --- a/docs/platforms/javascript/guides/bun/index.mdx +++ b/docs/platforms/javascript/guides/bun/index.mdx @@ -7,6 +7,14 @@ categories: - server-only --- + + +Express, Fastify, Hapi, Hono, and Koa don't need any extra setup. Follow this guide, and the SDK instruments them automatically. + +Elysia has its own Sentry SDK. Follow the [Elysia guide](/platforms/javascript/guides/elysia/) instead. + + + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx index 6a7df59814d506..0dc23f392abd82 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx @@ -67,4 +67,4 @@ To read the DSN from a Worker binding, pass a callback instead of a plain option app.use(sentry(app, (env) => ({ dsn: env.SENTRY_DSN }))); ``` -For the full setup, including verification and the other runtimes, see the **[Hono Quick Start Guide](/platforms/javascript/guides/hono/)**. +To set up Sentry for Hono on other runtimes, see [Hono](/platforms/javascript/guides/hono/). diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index 07bc0e6562d4e4..033ffc7562e976 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -15,7 +15,7 @@ This guide covers Cloudflare Workers. If you're deploying a Cloudflare Pages app If you're using any of the listed frameworks, follow their specific setup instructions: - **[Astro](/platforms/javascript/guides/cloudflare/frameworks/astro/)** -- **[Hono](/platforms/javascript/guides/hono/)** (with @sentry/hono) +- **[Hono](/platforms/javascript/guides/cloudflare/frameworks/hono/)** (with @sentry/hono) - **[Hydrogen](/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router/)** - **[Next.js](/platforms/javascript/guides/cloudflare/frameworks/nextjs/)** - **[Nuxt](/platforms/javascript/guides/cloudflare/frameworks/nuxt/)** diff --git a/docs/platforms/javascript/guides/cordova/data-management/sensitive-data/index.mdx b/docs/platforms/javascript/guides/cordova/data-management/sensitive-data/index.mdx index 5045b48f990e1f..5a280d3a5710c7 100644 --- a/docs/platforms/javascript/guides/cordova/data-management/sensitive-data/index.mdx +++ b/docs/platforms/javascript/guides/cordova/data-management/sensitive-data/index.mdx @@ -1,7 +1,7 @@ --- title: "Scrubbing Sensitive Data" description: "Learn about filtering or scrubbing sensitive data within the Sentry JavaScript SDK, so that data is not sent with the event. You can also configure server-side scrubbing to ensure the data is not stored." -customCanonicalTag: "/platforms/javascript/guides/koa/data-management/sensitive-data/" +customCanonicalTag: "/platforms/javascript/guides/node/data-management/sensitive-data/" sidebar_order: 100 keywords: - pii diff --git a/docs/platforms/javascript/guides/cordova/sourcemaps/uploading/rollup.mdx b/docs/platforms/javascript/guides/cordova/sourcemaps/uploading/rollup.mdx index 29b44acd07dd1b..3c8f4aac66d5cb 100644 --- a/docs/platforms/javascript/guides/cordova/sourcemaps/uploading/rollup.mdx +++ b/docs/platforms/javascript/guides/cordova/sourcemaps/uploading/rollup.mdx @@ -2,7 +2,7 @@ title: Rollup description: "Upload your source maps with the Sentry Rollup Plugin." sidebar_order: 5 -customCanonicalTag: "/platforms/javascript/guides/koa/sourcemaps/uploading/rollup/" +customCanonicalTag: "/platforms/javascript/guides/node/sourcemaps/uploading/rollup/" --- diff --git a/docs/platforms/javascript/guides/deno/index.mdx b/docs/platforms/javascript/guides/deno/index.mdx index 03e6221cbfa321..328978715756e6 100644 --- a/docs/platforms/javascript/guides/deno/index.mdx +++ b/docs/platforms/javascript/guides/deno/index.mdx @@ -13,6 +13,12 @@ This SDK is currently in **beta**. Beta features are still in progress and may h + + +Express, Fastify, Hapi, Hono, and Koa don't need any extra setup. Follow this guide, and the SDK instruments them automatically. + + + diff --git a/docs/platforms/javascript/guides/express/configuration/integrations/contextlines.mdx b/docs/platforms/javascript/guides/express/configuration/integrations/contextlines.mdx deleted file mode 100644 index 7b3af587274903..00000000000000 --- a/docs/platforms/javascript/guides/express/configuration/integrations/contextlines.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ContextLines -description: "Adds source code to your stack frames. (default)" ---- - -_Import name: `Sentry.contextLinesIntegration`_ - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -This integration adds source code to your stack frames. It ensures that you can see the code that caused the error directly in the Sentry UI. - - - -## Options - -### `frameContextLines` - -_Type: `number`_ - -The number of lines to collect around each stack frame's line number. Defaults to 7. diff --git a/docs/platforms/javascript/guides/express/index.mdx b/docs/platforms/javascript/guides/express/index.mdx index c495ee6e41d748..d7cdeba89b349d 100644 --- a/docs/platforms/javascript/guides/express/index.mdx +++ b/docs/platforms/javascript/guides/express/index.mdx @@ -1,11 +1,51 @@ --- title: Express -description: "Learn how to manually set up Sentry in your Express app and capture your first errors." +description: "Learn how to set up Sentry in your Express app on Node.js, Bun, or Deno." sdk: sentry.javascript.node fallbackGuide: javascript.node +inheritCommonContent: false categories: - server - server-only --- - +[Express](https://expressjs.com/) doesn't need its own Sentry SDK. Set up Sentry for the runtime your app runs on, and the SDK instruments Express automatically: `expressIntegration` captures errors from your routes and middleware, and creates spans for incoming requests when tracing is enabled. + +## Set Up Sentry for Your Runtime + +- +- +- + +## Customize Error Capturing + +Errors with a 3xx or 4xx status code are skipped, since they're usually expected redirects or client errors. To change which errors are captured, pass a `shouldHandleError` callback to `expressIntegration()`: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.expressIntegration({ + shouldHandleError(error) { + const status = Number(error.status ?? error.statusCode ?? 500); + // Capture 401/403 in addition to the default 5xx errors + return status === 401 || status === 403 || status >= 500; + }, + }), + ], +}); +``` + +If you capture errors yourself in your own error-handling middleware, set `shouldHandleError: false` to avoid duplicate events. diff --git a/docs/platforms/javascript/guides/express/index__v7.x.mdx b/docs/platforms/javascript/guides/express/index__v7.x.mdx deleted file mode 100644 index 76ef56f70dc764..00000000000000 --- a/docs/platforms/javascript/guides/express/index__v7.x.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Express -description: "Learn how to instrument the Sentry Express SDK." -sdk: sentry.javascript.node -fallbackGuide: javascript.node -categories: - - server ---- - - - -This guide explains how to set up Sentry in your Express application. - - diff --git a/docs/platforms/javascript/guides/express/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/express/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index c7b42fb602ab92..00000000000000 --- a/docs/platforms/javascript/guides/express/tracing/instrumentation/automatic-instrumentation.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Automatic Instrumentation -description: "Learn what transactions are captured after tracing is enabled in the Sentry Express SDK." ---- - - diff --git a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx b/docs/platforms/javascript/guides/fastify/features/error-handler.mdx deleted file mode 100644 index 43e3c0f8cf935e..00000000000000 --- a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Fastify Error Handler -description: "Learn how Sentry's Fastify integration captures errors and how to configure it." ---- - -The `fastifyIntegration` captures errors in your Fastify application and sends them to Sentry. It's enabled by default, so you only need to add it to your `Sentry.init` call to configure it. - -By default, errors with status codes 5xx and above, as well as errors with status codes 2xx and below, are captured. Errors with 3xx and 4xx status codes aren't sent to Sentry. - -## Configuration - -To control which errors are captured, pass `shouldHandleError` to `Sentry.fastifyIntegration`: - -```javascript -import * as Sentry from "@sentry/node"; - -Sentry.init({ - dsn: "your-dsn", - integrations: [ - Sentry.fastifyIntegration({ - shouldHandleError(error, request, reply) { - return reply.statusCode >= 500; - }, - }), - ], -}); -``` - -## Options - -`Sentry.fastifyIntegration` accepts the following options: - -- `shouldHandleError` - -A function that determines whether an error should be captured. - -```typescript -declare function shouldHandleError( - error: Error, - request: FastifyRequest, - reply: FastifyReply -): boolean; -``` - -If using TypeScript, you can cast the request and reply to get full type safety. - -```typescript -import type { FastifyRequest, FastifyReply } from "fastify"; - -Sentry.fastifyIntegration({ - shouldHandleError(error, minimalRequest, minimalReply) { - const request = minimalRequest as FastifyRequest; - const reply = minimalReply as FastifyReply; - return reply.statusCode >= 500; - }, -}); -``` diff --git a/docs/platforms/javascript/guides/fastify/features/index.mdx b/docs/platforms/javascript/guides/fastify/features/index.mdx deleted file mode 100644 index b7fcfb338bb495..00000000000000 --- a/docs/platforms/javascript/guides/fastify/features/index.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Fastify Features -description: "Learn how Sentry's Node SDK exposes features for first class integration with Fastify." -excerpt: "" ---- - -The Sentry Node SDK offers Fastify-specific features for first class integration with the framework. - - diff --git a/docs/platforms/javascript/guides/fastify/index.mdx b/docs/platforms/javascript/guides/fastify/index.mdx index d7aecbc64fde8a..3159223afd40d9 100644 --- a/docs/platforms/javascript/guides/fastify/index.mdx +++ b/docs/platforms/javascript/guides/fastify/index.mdx @@ -1,13 +1,34 @@ --- title: Fastify -description: "Learn how to manually set up Sentry in your Fastify app and capture your first errors." +description: "Learn how to set up Sentry in your Fastify app on Node.js, Bun, or Deno." sdk: sentry.javascript.node fallbackGuide: javascript.node +inheritCommonContent: false categories: - server - server-only --- - +[Fastify](https://fastify.dev/) doesn't need its own Sentry SDK. Set up Sentry for the runtime your app runs on, and the SDK instruments Fastify automatically: `fastifyIntegration` captures errors from your routes and hooks, and creates spans for incoming requests when tracing is enabled. - +## Set Up Sentry for Your Runtime + +- +- +- + +## Customize Error Capturing + +Errors with a 3xx or 4xx status code are skipped. To change which errors are captured, pass a `shouldHandleError` callback to `fastifyIntegration()`. See the [Fastify integration](/platforms/javascript/guides/node/configuration/integrations/fastify/#shouldhandleerror) for all options. diff --git a/docs/platforms/javascript/guides/fastify/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/fastify/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index abc98b5bca4fd9..00000000000000 --- a/docs/platforms/javascript/guides/fastify/tracing/instrumentation/automatic-instrumentation.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Automatic Instrumentation -description: "Learn what transactions are captured after tracing is enabled in the Sentry Fastify SDK." ---- - - diff --git a/docs/platforms/javascript/guides/hapi/configuration/integrations/contextlines.mdx b/docs/platforms/javascript/guides/hapi/configuration/integrations/contextlines.mdx deleted file mode 100644 index 7b3af587274903..00000000000000 --- a/docs/platforms/javascript/guides/hapi/configuration/integrations/contextlines.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ContextLines -description: "Adds source code to your stack frames. (default)" ---- - -_Import name: `Sentry.contextLinesIntegration`_ - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -This integration adds source code to your stack frames. It ensures that you can see the code that caused the error directly in the Sentry UI. - - - -## Options - -### `frameContextLines` - -_Type: `number`_ - -The number of lines to collect around each stack frame's line number. Defaults to 7. diff --git a/docs/platforms/javascript/guides/hapi/index.mdx b/docs/platforms/javascript/guides/hapi/index.mdx index d7196e2d78d278..aa00c6ae393661 100644 --- a/docs/platforms/javascript/guides/hapi/index.mdx +++ b/docs/platforms/javascript/guides/hapi/index.mdx @@ -1,11 +1,32 @@ --- title: Hapi -description: "Learn how to manually set up Sentry in your Hapi app and capture your first errors." +description: "Learn how to set up Sentry in your Hapi app on Node.js, Bun, or Deno." sdk: sentry.javascript.node fallbackGuide: javascript.node +inheritCommonContent: false categories: - server - server-only --- - +[Hapi](https://hapi.dev/) doesn't need its own Sentry SDK. Set up Sentry for the runtime your app runs on, and the SDK instruments Hapi automatically: `hapiIntegration` registers an error handler when your server starts, and creates spans for incoming requests when tracing is enabled. + +## Set Up Sentry for Your Runtime + +- +- +- + +To configure the integration, see the [Hapi integration](/platforms/javascript/guides/node/configuration/integrations/hapi/). diff --git a/docs/platforms/javascript/guides/hapi/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/hapi/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index e749b53b702b12..00000000000000 --- a/docs/platforms/javascript/guides/hapi/tracing/instrumentation/automatic-instrumentation.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Automatic Instrumentation -description: "Learn what transactions are captured after tracing is enabled in the Sentry Hapi SDK." ---- - - diff --git a/docs/platforms/javascript/guides/hono/features/error-handler.mdx b/docs/platforms/javascript/guides/hono/features/error-handler.mdx deleted file mode 100644 index 9167f06300b59b..00000000000000 --- a/docs/platforms/javascript/guides/hono/features/error-handler.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Error Handler -description: "Learn how Sentry's Hono SDK captures errors and how to customize which errors are sent to Sentry." ---- - -The `sentry()` middleware automatically captures unhandled errors from Hono's `onError` handler. - -## Default Behavior - -The default logic checks whether the error carries a numeric `status` property (as Hono's `HTTPException` and similar error types do). - -The middleware captures: - -- **5xx errors** — anything with a numeric `status >= 500` -- **Non-HTTP errors** — errors without a numeric `status` property, including standard `Error` instances, non-object throws, and `null` - -The middleware ignores: - -- **3xx–4xx errors** — anything with a numeric `status` in the range 300–499 (redirects, client errors) - -Use `shouldHandleError` when you need to capture errors outside this default range, for example to track 401 and 403 responses as security signals. - -## Using `shouldHandleError` - -Pass a `shouldHandleError` callback to the `sentry()` middleware. The callback receives the raw error as `unknown` and must return `true` to capture it or `false` to suppress it. - -```typescript {tabTitle:Cloudflare Workers} {filename:index.ts} {mdExpandTabs} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/cloudflare"; - -const app = new Hono(); - -app.use( - sentry(app, { - dsn: "___PUBLIC_DSN___", - shouldHandleError(error) { - const status = (error as { status?: number })?.status; - // Capture 401/403 in addition to the default 5xx errors - return ( - status === 401 || - status === 403 || - typeof status !== "number" || - status >= 500 - ); - }, - }) -); - -export default app; -``` - -```typescript {tabTitle:Node.js} {filename:app.ts} -import { Hono } from "hono"; -import { serve } from "@hono/node-server"; -import { sentry } from "@sentry/hono/node"; - -const app = new Hono(); - -app.use( - sentry(app, { - shouldHandleError(error) { - const status = (error as { status?: number })?.status; - // Capture 401/403 in addition to the default 5xx errors - return ( - status === 401 || - status === 403 || - typeof status !== "number" || - status >= 500 - ); - }, - }) -); - -// Your routes here - -serve(app); -``` - -```typescript {tabTitle:Bun} {filename:index.ts} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/bun"; - -const app = new Hono(); - -app.use( - sentry(app, { - dsn: "___PUBLIC_DSN___", - shouldHandleError(error) { - const status = (error as { status?: number })?.status; - // Capture 401/403 in addition to the default 5xx errors - return ( - status === 401 || - status === 403 || - typeof status !== "number" || - status >= 500 - ); - }, - }) -); - -export default app; -``` diff --git a/docs/platforms/javascript/guides/hono/features/index.mdx b/docs/platforms/javascript/guides/hono/features/index.mdx deleted file mode 100644 index 0580f8f8c3f5d2..00000000000000 --- a/docs/platforms/javascript/guides/hono/features/index.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Hono Features -description: "Learn how Sentry's Hono SDK exposes features for first-class integration with Hono." -excerpt: "" ---- - -The Sentry Hono SDK offers Hono-specific features for first-class integration with the framework. - - diff --git a/docs/platforms/javascript/guides/hono/index.mdx b/docs/platforms/javascript/guides/hono/index.mdx index 71ad13f56a967f..9b6832acaf3e6b 100644 --- a/docs/platforms/javascript/guides/hono/index.mdx +++ b/docs/platforms/javascript/guides/hono/index.mdx @@ -1,404 +1,59 @@ --- title: Hono -description: "Learn how to set up Sentry in your Hono app and capture your first errors." +description: "Learn how to set up Sentry in your Hono app on Node.js, Bun, Deno, or Cloudflare Workers." sdk: sentry.javascript.hono fallbackGuide: javascript.node +inheritCommonContent: false categories: - server - server-only --- -The `@sentry/hono` SDK supports Hono 4+ across multiple runtimes: Cloudflare Workers, Node.js, Bun, and Deno. It works as Hono middleware, so you can drop it into your existing app with minimal setup. - - - -The community middleware `@hono/sentry` has been deprecated in favor of `@sentry/hono`, which provides better performance and more features. To migrate: - -1. Uninstall `@hono/sentry` and `toucan-js` -2. Follow the install and configure steps below for your runtime -3. Replace the old middleware with the new `sentry()` middleware - - - - - - - -## Install - -Choose the features you want to configure, and this guide will show you how: - - - - - -### Install the Sentry SDK - - - - - -Install the `@sentry/hono` package: - - - - -```bash {tabTitle:npm} -npm install @sentry/hono -``` - -```bash {tabTitle:yarn} -yarn add @sentry/hono -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/hono -``` - - - - - -### Install the Peer Dependency for Your Runtime - - - - - -The SDK needs a runtime-specific peer dependency. Install the one that matches your environment and keep its version in sync with `@sentry/hono`. You won't import it directly, but it must be present in your project. - - - - -```bash {tabTitle:Cloudflare Workers} {mdExpandTabs} -npm install @sentry/cloudflare -``` - -```bash {tabTitle:Node.js} -npm install @sentry/node -``` - -```bash {tabTitle:Bun} -npm install @sentry/bun -``` - -```bash {tabTitle:Deno} -deno add npm:@sentry/deno -``` - - - - - - - -### Install the Profiling Package (Node.js Only) - - - - - -Profiling is only available for the Node.js runtime. Install the `@sentry/profiling-node` package: - - - - -```bash {tabTitle:npm} -npm install @sentry/profiling-node --save -``` - -```bash {tabTitle:yarn} -yarn add @sentry/profiling-node -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/profiling-node -``` - - - - - - - -## Configure - - - - - - - -If you're deploying to Cloudflare Workers, set the `nodejs_compat` compatibility flag. The SDK needs `AsyncLocalStorage`, which requires this flag. - - - - -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "compatibility_flags": ["nodejs_compat"], -} -``` - -```toml {tabTitle:Toml} {filename:wrangler.toml} -compatibility_flags = ["nodejs_compat"] -``` - - - - - - - - - - - - - -Node.js requires Sentry to initialize before your application loads so it can instrument third-party libraries (like database clients). Create a separate initialization file: - - - - -```typescript {filename:instrument.mjs} -// IMPORTANT: import from `@sentry/hono/node`, not `@sentry/node` -import * as Sentry from "@sentry/hono/node"; -// ___PRODUCT_OPTION_START___ profiling -import { nodeProfilingIntegration } from "@sentry/profiling-node"; -// ___PRODUCT_OPTION_END___ profiling - +[Hono](https://hono.dev/) doesn't need its own Sentry setup. Set up Sentry for the runtime your app runs on, and the SDK instruments Hono automatically: `honoIntegration` captures errors from Hono's `onError` handler, and creates spans for incoming requests when tracing is enabled. + +## Set Up Sentry for Your Runtime + +- +- +- +- + +## Customize Error Capturing + +Errors with a 3xx or 4xx status code are skipped. To change which errors are captured, pass a `shouldHandleError` callback to `honoIntegration()`: + +```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ profiling - - integrations: [nodeProfilingIntegration()], - // ___PRODUCT_OPTION_END___ profiling - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. - // We recommend adjusting this value in production - // Learn more at - // https://docs.sentry.io/platforms/javascript/guides/hono/configuration/options/#tracesSampleRate - tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ profiling - - // Enable profiling for a percentage of sessions - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#profileSessionSampleRate - profileSessionSampleRate: 1.0, - // Profile automatically while there's an active sampled span - profileLifecycle: "trace", - // ___PRODUCT_OPTION_END___ profiling + integrations: [ + Sentry.honoIntegration({ + shouldHandleError(error) { + const status = error?.status; + // Capture 401/403 in addition to the default 5xx errors + return ( + status === 401 || + status === 403 || + typeof status !== "number" || + status >= 500 + ); + }, + }), + ], }); ``` - - - - - - - - - -Load this file with the `--import` flag when starting your app. You can also set this as an environment variable instead: - - - - -```bash {tabTitle:CLI Option} -node --import ./instrument.mjs app.js -``` - -```bash {tabTitle:ENV Variable} -NODE_OPTIONS="--import ./instrument.mjs" -``` - - - - - - - -### Add the Sentry Middleware - - - - - -Add the `sentry()` middleware as early as possible in your Hono app. - -Before continuing, make sure you've completed the runtime-specific steps above: **Cloudflare Workers** users need to enable Node.js compatibility, and **Node.js** users need to create the instrument file. Since Node.js initializes Sentry in that file, the middleware doesn't take any options. - - - - -```typescript {tabTitle:Cloudflare Workers} {filename:index.ts} {mdExpandTabs} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/cloudflare"; - -const app = new Hono(); - -app.use( - sentry(app, { - dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. - tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - }) -); - -// Your routes here - -export default app; -``` - -```typescript {tabTitle:Node.js} {filename:app.ts} -import { Hono } from "hono"; -import { serve } from "@hono/node-server"; -import { sentry } from "@sentry/hono/node"; - -const app = new Hono(); - -app.use(sentry(app)); - -// Your routes here - -serve(app); -``` - -```typescript {tabTitle:Bun} {filename:index.ts} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/bun"; - -const app = new Hono(); - -app.use( - sentry(app, { - dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. - tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - }) -); - -// Your routes here - -export default app; -``` - -```typescript {tabTitle:Deno} {filename:index.ts} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/deno"; - -const app = new Hono(); - -app.use( - sentry(app, { - dsn: "___PUBLIC_DSN___", - - // ___PRODUCT_OPTION_START___ performance - - // Set tracesSampleRate to 1.0 to capture 100% - // of spans for tracing. - tracesSampleRate: 1.0, - // ___PRODUCT_OPTION_END___ performance - }) -); - -// Your routes here - -Deno.serve(app.fetch); -``` - - - - - - - - - - - -To access environment variables from your Cloudflare Worker bindings (for example, to store the DSN as a secret), pass a callback instead of a plain options object. The function receives the Worker `env`: - - - - -```typescript {filename:index.ts} -import { Hono } from "hono"; -import { sentry } from "@sentry/hono/cloudflare"; - -type Bindings = { SENTRY_DSN: string }; - -const app = new Hono<{ Bindings: Bindings }>(); - -app.use(sentry(app, (env) => ({ dsn: env.SENTRY_DSN }))); - -export default app; -``` - - - - - - - -### Report Unhandled Exceptions - -By default, Sentry captures exceptions from Hono's `onError` handler, excluding errors with 3xx or 4xx status codes. No additional configuration is needed for this. - -To control which errors are captured, use the `shouldHandleError` option. - -### Add Readable Stack Traces With Source Maps (Optional) - - - -### Control the Data You Send to Sentry (Optional) - - - -## Verify Your Setup - - - -### View Captured Data in Sentry - -Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - - - -## Next Steps - -At this point, you should have Sentry integrated into your Hono application and already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics: - -- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Learn how to manually capture errors -- Explore Hono-specific features like custom error filtering -- Continue to customize your configuration -- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts - - - -- Find various topics in Troubleshooting -- [Get support](https://www.sentry.help/en/) - - - - diff --git a/docs/platforms/javascript/guides/koa/configuration/integrations/contextlines.mdx b/docs/platforms/javascript/guides/koa/configuration/integrations/contextlines.mdx deleted file mode 100644 index 7b3af587274903..00000000000000 --- a/docs/platforms/javascript/guides/koa/configuration/integrations/contextlines.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: ContextLines -description: "Adds source code to your stack frames. (default)" ---- - -_Import name: `Sentry.contextLinesIntegration`_ - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -This integration adds source code to your stack frames. It ensures that you can see the code that caused the error directly in the Sentry UI. - - - -## Options - -### `frameContextLines` - -_Type: `number`_ - -The number of lines to collect around each stack frame's line number. Defaults to 7. diff --git a/docs/platforms/javascript/guides/koa/index.mdx b/docs/platforms/javascript/guides/koa/index.mdx index f8c201fc2708ab..46c24b474fa709 100644 --- a/docs/platforms/javascript/guides/koa/index.mdx +++ b/docs/platforms/javascript/guides/koa/index.mdx @@ -1,11 +1,32 @@ --- title: Koa -description: "Learn how to manually set up Sentry in your Koa app and capture your first errors." +description: "Learn how to set up Sentry in your Koa app on Node.js, Bun, or Deno." sdk: sentry.javascript.node fallbackGuide: javascript.node +inheritCommonContent: false categories: - server - server-only --- - +[Koa](https://koajs.com/) doesn't need its own Sentry SDK. Set up Sentry for the runtime your app runs on, and the SDK instruments Koa automatically: `koaIntegration` registers an error handler when your app starts, and creates spans for incoming requests and middleware when tracing is enabled. + +## Set Up Sentry for Your Runtime + +- +- +- + +To configure the integration, see the [Koa integration](/platforms/javascript/guides/node/configuration/integrations/koa/). diff --git a/docs/platforms/javascript/guides/koa/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/koa/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index 4ad82b17e57af3..00000000000000 --- a/docs/platforms/javascript/guides/koa/tracing/instrumentation/automatic-instrumentation.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Automatic Instrumentation -description: "Learn what transactions are captured after tracing is enabled in the Sentry Koa SDK." ---- - - diff --git a/docs/platforms/javascript/guides/node/index.mdx b/docs/platforms/javascript/guides/node/index.mdx index 69db24d7d47bf9..943312254bd0f5 100644 --- a/docs/platforms/javascript/guides/node/index.mdx +++ b/docs/platforms/javascript/guides/node/index.mdx @@ -7,6 +7,14 @@ categories: - server-only --- + + +Express, Fastify, Hapi, Hono, and Koa don't need any extra setup. Follow this guide, and the SDK instruments them automatically. + +Frameworks like Next.js have their own Sentry SDK. Follow the guide for your framework instead: [Astro](/platforms/javascript/guides/astro/), [NestJS](/platforms/javascript/guides/nestjs/), [Next.js](/platforms/javascript/guides/nextjs/), [Nitro](/platforms/javascript/guides/nitro/), [Nuxt](/platforms/javascript/guides/nuxt/), [React Router](/platforms/javascript/guides/react-router/), [Remix](/platforms/javascript/guides/remix/), [SolidStart](/platforms/javascript/guides/solidstart/), [SvelteKit](/platforms/javascript/guides/sveltekit/), [TanStack Start](/platforms/javascript/guides/tanstackstart-react/). + + + diff --git a/docs/platforms/javascript/legacy-sdk/integrations.mdx b/docs/platforms/javascript/legacy-sdk/integrations.mdx deleted file mode 100644 index fbd1f60bb07add..00000000000000 --- a/docs/platforms/javascript/legacy-sdk/integrations.mdx +++ /dev/null @@ -1,696 +0,0 @@ ---- -draft: true -categories: [] -toc: true -title: "Integrations (Legacy SDK)" -sidebar_title: "Integrations" -noindex: true -tags: [] ---- - - - -A new JavaScript SDK has superseded this deprecated version. Sentry preserves this documentation for customers using the old client. We recommend using the [updated JavaScript SDK](/platforms/javascript/) for new projects. - - - -Integrations extend the functionality of Raven.js to cover common libraries and environments automatically using simple plugins. - -## What are plugins? - -In Raven.js, plugins are little snippets of code to augment functionality for a -specific application/framework. We highly recommended you check out the list -of plugins and use what apply to your project. - -In order to keep the core small, we have opted to only include the most basic functionality by default, and you can pick and choose which plugins are applicable for you. - -## Why are plugins needed at all? - -JavaScript is pretty restrictive when it comes to exception handling, and there are a lot of things that make it difficult to get relevant information, so it’s important that we inject code and wrap things magically so we can extract what we need. See [_Usage_](/platforms/javascript/legacy-sdk/usage/) for tips regarding that. - -## Installation - -To install a plugin just include the plugin **after** Raven has been loaded and the Raven global variable is registered. This happens automatically if you install from a CDN with the required plugins in the URL. - -## AngularJS - -To use Sentry with your AngularJS (1.x) application, you will need to use both Raven.js (Sentry’s browser JavaScript SDK) and the Raven.js AngularJS plugin. - -On its own, Raven.js will report any uncaught exceptions triggered from your application. For advanced usage examples of Raven.js, please read [_Raven.js usage_](/platforms/javascript/legacy-sdk/usage/). - -Additionally, the Raven.js AngularJS plugin will catch any AngularJS-specific exceptions reported through AngularJS’s `$exceptionHandler` interface. - - - -This documentation is for Angular 1.x. See also: [_Angular 2.x_](#angular). - - - -{/* */} - -### Installation - -Raven.js and the Raven.js Angular plugin are distributed using a few different methods. - -#### Using our CDN - -For convenience, our CDN serves a single, minified JavaScript file containing both Raven.js and the Raven.js AngularJS plugin. It should be included **after** Angular, but **before** your application code. - -Example: - - -```html - - - -``` - -Note that this CDN build auto-initializes the Angular plugin. - -#### Using package managers - -Pre-built distributions of Raven.js and the Raven.js AngularJS plugin are available via both Bower and npm. - -##### Bower - - -```shell -bower install raven-js --save -``` - -```html - - - - -``` - -##### npm - - -```shell -npm install raven-js --save -``` - -```html - - - - -``` - -These examples assume that AngularJS is exported globally as _window.angular_. You can alternatively pass a reference to the _angular_ object directly as the second argument to _addPlugin_: - -```javascript -Raven.addPlugin(Raven.Plugins.Angular, angular); -``` - -#### Module loaders (CommonJS) - -Raven and the Raven AngularJS plugin can be loaded using a module loader like Browserify or webpack. - - -```javascript -var angular = require("angular"); -var Raven = require("raven-js"); - -Raven.config("___PUBLIC_DSN___") - .addPlugin(require("raven-js/plugins/angular"), angular) - .install(); -``` - -Note that when using CommonJS-style imports, you must pass a reference to _angular_ as the second argument to _addPlugin_. - -### AngularJS Configuration - -Inside your main AngularJS application module, you need to declare _ngRaven_ as a module dependency: - -```javascript -var myApp = angular.module("myApp", [ - "ngRaven", - "ngRoute", - "myAppControllers", - "myAppFilters", -]); -``` - -#### Module loaders (CommonJS) - -The raven angular module can be loaded using a module loader like Browserify or webpack. - -```javascript -var angular = require("angular"); -var ngRaven = require("raven-js/plugins/angular").moduleName; -var ngRoute = require("angular-route"); - -var myAppFilters = require("./myAppFilters"); -var myAppControllers = require("./myAppControllers"); -var moduleName = "myApp"; - -angular.module(moduleName, [ngRaven, ngRoute, myAppControllers, myAppFilters]); - -module.exports = moduleName; -``` - -{/* */} - -## Angular - -This document uses Angular to refer to Angular 2+. On its own, Raven.js will report any uncaught exceptions triggered from your application. For advanced usage examples of Raven.js, please read [_Raven.js usage_](/platforms/javascript/legacy-sdk/usage/). - -Additionally, Raven.js can be configured to catch any Angular-specific (2.x) exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) component. - -### TypeScript Support - -Raven.js ships with a [TypeScript declaration file](https://www.npmjs.com/package/@types/raven-js), which helps static checking correctness of Raven.js API calls, and facilitates auto-complete in TypeScript-aware IDEs like Visual Studio Code. - -{/* */} - -### Installation - -Raven.js should be installed via npm. - -```shell -npm install raven-js --save -``` - -### Configuration - -Configuration depends on which module loader/packager you are using to build your Angular application. - -Below are instructions for [SystemJS](https://github.com/systemjs/systemjs), followed by instructions for [webpack](https://webpack.github.io/), Angular CLI, and other module loaders/packagers. - -#### SystemJS - -First, configure SystemJS to locate the Raven.js package: - -```javascript -System.config({ - packages: { - /* ... existing packages above ... */ - "raven-js": { - main: "dist/raven.js", - }, - }, - paths: { - /* ... existing paths above ... */ - "raven-js": "node_modules/raven-js", - }, -}); -``` - -Then, in your main module file (where `@NgModule` is called, e.g. app.module.ts): - - -```javascript -import Raven = require('raven-js'); -import { BrowserModule } from '@angular/platform-browser'; -import { NgModule, ErrorHandler } from '@angular/core'; -import { AppComponent } from './app.component'; -import { environment } from '../environments/environment'; - -Raven - .config('___PUBLIC_DSN___') - .install(); - -export class RavenErrorHandler implements ErrorHandler { - handleError(err:any) : void { - Raven.captureException(err.originalError || err); - if(!environment.production) { - super.handleError(err); - } - } -} - -@NgModule({ - imports: [ BrowserModule ], - declarations: [ AppComponent ], - bootstrap: [ AppComponent ], - providers: [ { provide: ErrorHandler, useClass: RavenErrorHandler } ] -}) -export class AppModule { } -``` - -Once you’ve completed these two steps, you are done. - -#### Angular CLI - -Angular CLI now uses webpack to build instead of SystemJS. All you need to do is modify your main module file (where `@NgModule` is called, e.g. app.module.ts): - - -```javascript -import * as Raven from "raven-js"; -import { BrowserModule } from "@angular/platform-browser"; -import { NgModule, ErrorHandler } from "@angular/core"; -import { AppComponent } from "./app.component"; - -Raven.config("___PUBLIC_DSN___").install(); - -export class RavenErrorHandler implements ErrorHandler { - handleError(err: any): void { - Raven.captureException(err); - } -} - -@NgModule({ - imports: [BrowserModule], - declarations: [AppComponent], - bootstrap: [AppComponent], - providers: [{ provide: ErrorHandler, useClass: RavenErrorHandler }], -}) -export class AppModule {} -``` - -Once you’ve completed that step, you are done. - -{/* */} - -## Backbone - -{/* */} - -### Installation - -Start by adding the `raven.js` script tag to your page. It should be loaded as early as possible. - -```html - -``` - -### Configuring the Client - -Next configure Raven.js to use your Sentry DSN: - - -```javascript -Raven.config("___PUBLIC_DSN___").install(); -``` - -At this point, Raven is ready to capture any uncaught exception. - -{/* */} - -## Ember - -To use Sentry with your Ember application, you will need to use both Raven.js (Sentry’s browser JavaScript SDK) and the Raven.js Ember plugin. - -On its own, Raven.js will report any uncaught exceptions triggered from your application. For advanced usage examples of Raven.js, please read [_Raven.js usage_](/platforms/javascript/legacy-sdk/usage/). - -Additionally, the Raven.js Ember plugin will catch any Ember-specific exceptions reported through Ember’s [onerror](https://guides.emberjs.com/v3.2.0/configuring-ember/debugging/#toc_implement-an-ember-onerror-hook-to-log-all-errors-in-production). hook and any [RSVP promises](https://guides.emberjs.com/v3.2.0/configuring-ember/debugging/#toc_errors-within-an-code-rsvp-promise-code) that would otherwise be swallowed. - -{/* */} - -### Installation - -Raven.js and the Raven.js Ember plugin are distributed using a few different methods. - -#### Using our CDN - -For convenience, our CDN serves a single, minified JavaScript file containing both Raven.js and the Raven.js Ember plugin. It should be included **after** Ember, but **before** your application code. - -Example: - - -```html - - - -``` - -Note that this CDN build auto-initializes the Ember plugin. - -### Using package managers - -Pre-built distributions of Raven.js and the Raven.js Ember plugin are available via both Bower and npm for importing in your `ember-cli-build.js` file. - -##### Bower - - -```shell -bower install raven-js --save -``` - -```javascript -app.import("bower_components/raven-js/dist/raven.js"); -app.import("bower_components/raven-js/dist/plugins/ember.js"); -``` - -```html - - - -``` - -##### npm - - -```shell -npm install raven-js --save -``` - -```javascript -app.import("node_modules/raven-js/dist/raven.js"); -app.import("node_modules/raven-js/dist/plugins/ember.js"); -``` - -```html - - - -``` - -These examples assume that Ember is exported globally as `window.Ember`. You can alternatively pass a reference to the `Ember` object directly as the second argument to `addPlugin`: - -```javascript -Raven.addPlugin(Raven.Plugins.Ember, Ember); -``` - -## React - -{/* */} - -### Installation - -Start by adding the `raven.js` script tag to your page. It should be loaded as early as possible, before your main JavaScript bundle. - -```html - -``` - -### Configuring the Client - -Next configure Raven.js to use your Sentry DSN: - - -```javascript -Raven.config("___PUBLIC_DSN___").install(); -``` - -At this point, Raven is ready to capture any uncaught exception. - -### Expanded Usage - -If you’re using React 16 or above, [Error Boundaries](https://reactjs.org/blog/2017/07/26/error-handling-in-react-16.html) are an important tool for defining the behavior of your application in the face of errors. Be sure to send errors they catch to Sentry using `Raven.captureException`, and optionally this is also a great opportunity to surface [User Feedback](/platforms/javascript/user-feedback/) - -```javascript -class ExampleBoundary extends Component { - constructor(props) { - super(props); - this.state = { error: null }; - } - - componentDidCatch(error, errorInfo) { - this.setState({ error }); - Raven.captureException(error, { extra: errorInfo }); - } - - render() { - if (this.state.error) { - //render fallback UI - return ( -
Raven.lastEventId() && Raven.showReportDialog()} - > - -

We're sorry — something's gone wrong.

-

Our team has been notified, but click here fill out a report.

-
- ); - } else { - //when there's not an error, render children untouched - return this.props.children; - } - } -} -``` - -```html -
- -

Sidebar

- - -

This content won't unmount when Widget throws.

-
-``` - -One important thing to note about the behavior of error boundaries in development mode is that React will rethrow errors they catch. This will result in errors being reported twice to Sentry with the above setup, but this won’t occur in your production build. - -Read more about error boundaries [in this blog post](https://blog.sentry.io/react-16-error-boundaries/). - -### Redux - -If you use [Redux](https://github.com/reactjs/redux) there are some useful community maintained middleware packages for annotating error reports with useful information, such as store state and recent actions: - -- [captbaritone/raven-for-redux](https://github.com/captbaritone/raven-for-redux) -- [ngokevin/redux-raven-middleware](https://github.com/ngokevin/redux-raven-middleware) - -### Redux Sagas Middleware - -If you’re using [Redux Saga](https://github.com/redux-saga/redux-saga) be aware that it does not bubble errors up to the browsers uncaught exception handler. - -You may specify an error handler that captures saga exceptions by passing an `onError` function to the `createSagaMiddleware` options, and call `Raven.captureException` inside that callback. See the [Redux Saga documentation](https://redux-saga.js.org/docs/api/#createsagamiddlewareoptions) for more details. - -## Vue.js (2.0) - - - -This plugin only works with Vue 2.0 or greater. - - - -To use Sentry with your Vue application, you will need to use both Raven.js (Sentry’s browser JavaScript SDK) and the Raven.js Vue plugin. - -On its own, Raven.js will report any uncaught exceptions triggered from your application. For advanced usage examples of Raven.js, please read [_Raven.js usage_](/platforms/javascript/legacy-sdk/usage/). - -Additionally, the Raven.js Vue plugin will capture the name and props state of the active component where the error was thrown. This is reported via Vue’s _config.errorHandler_ hook. - -{/* */} - -### Installation - -Raven.js and the Raven.js Vue plugin are distributed using a few different methods. - -#### Using our CDN - -For convenience, our CDN serves a single, minified JavaScript file containing both Raven.js and the Raven.js Vue plugin. It should be included **after** Vue, but **before** your application code. - -Example: - - -```html - - - -``` - -Note that this CDN build auto-initializes the Vue plugin. - -#### Using package managers - -Both Raven.js and the Raven.js Vue plugin can be installed via npm and Bower. - -##### npm - - -```shell -npm install raven-js --save -``` - -```html - - - - -``` - -##### Bower - - -```shell -bower install raven-js --save -``` - -```html - - - - -``` - -These examples assume that Vue is exported globally as _window.Vue_. You can alternatively pass a reference to the _Vue_ object directly as the second argument to _addPlugin_: - -```javascript -Raven.addPlugin(Raven.Plugins.Vue, Vue); -``` - -#### Module loaders - -In your main application file, import and configure both Raven.js and the Raven.js Vue plugin as follows: - - -```javascript -import Vue from "vue"; -import Raven from "raven-js"; -import RavenVue from "raven-js/plugins/vue"; - -Raven.config("___PUBLIC_DSN___").addPlugin(RavenVue, Vue).install(); -``` - -## Deprecated React Native - -The deprecated plugin “React Native for Raven.js” is a pure JavaScript error reporting solution. The plugin will report errors originating from React Native’s JavaScript engine (e.g. programming errors like “x is undefined”), but might not catch errors that originate from the underlying operating system (iOS / Android) unless they happen to be transmitted to React Native’s global error handler. - -**Do not use this plugin for new code but instead use the new :ref:`react-native` client integration instead**. - - - -Unless you have specific reasons not to, it’s recommended to instead the new [React Native](platforms/react-native/) client instead which supports native and JavaScript crashes as well as an improved integration into the Xcode build process. - - - -### Installation - -In the root of your React Native project, install raven-js via npm: - -```bash -npm install raven-js --save -``` - -At the top of your main application file (e.g. index.ios.js and/or index.android.js), add the following code: - -```javascript -var React = require("react"); - -var Raven = require("raven-js"); -require("raven-js/plugins/react-native")(Raven); -``` - -### Configuring the Client - -Now we need to set up Raven.js to use your Sentry DSN: - - -```javascript -Raven.config("___PUBLIC_DSN___", { release: RELEASE_ID }).install(); -``` - -RELEASE_ID is a string representing the “version” of the build you are about to distribute. This can be the SHA of your Git repository’s HEAD. It can also be a semantic version number (e.g. “1.1.2”), pulled from your project’s package.json file. More below. - -### About Releases - -Every time you build and distribute a new version of your React Native app, you’ll want to create a new release inside Sentry. This is for two important reasons: - -- You can associate errors tracked by Sentry with a particular build -- You can store your source files/source maps generated for each build inside Sentry - -Unlike a normal web application where your JavaScript files (and source maps) are served and hosted from a web server, your React Native code is being served from the target device’s filesystem. So you’ll need to upload both your **source code** AND **source maps** directly to Sentry, so that we can generate handy stack traces for you to browse when examining exceptions triggered by your application. - -### Generating and Uploading Source Files/Source Maps - -To generate both an application JavaScript file (main.jsbundle) and source map for your project (main.jsbundle.map), use the React Native CLI tool: - -```bash -react-native bundle \ - --dev false \ - --platform ios \ - --entry-file index.ios.js \ - --reset-cache \ - --bundle-output main.jsbundle \ - --sourcemap-output main.jsbundle.map -``` - -This will write both main.jsbundle and main.jsbundle.map to the current directory. Next, you’ll need to [create a new release and upload these files as release artifacts](/platforms/javascript/legacy-sdk/sourcemaps/). - -#### Naming your Artifacts - -In Sentry, artifacts are designed to be “named” using the full URL or path at which that artifact is located (e.g. _https://example.org/app.js_ or _/path/to/file.js/_). Since React Native applications are installed to a user’s device, on a path that includes unique device identifiers (and thus different for every user), the React Native plugin strips the entire path leading up to your application root. - -This means that although your code may live at the following path: - -``` -/var/containers/Bundle/Application/{DEVICE_ID}/HelloWorld.app/main.jsbundle -``` - -The React Native plugin will reduce this to: - -``` -/main.jsbundle -``` - -Therefore in this example, you should name your artifacts as “/main.jsbundle” and “/main.jsbundle.map”. - -### Source Maps with the Simulator - -When developing with the simulator, it is not necessary to build source maps manually, as they are generated automatically on-demand. - -Note however that artifact names are completely different when using the simulator. This is because instead of those files existing on a path on a device, they are served over HTTP via the [React Native packager](https://github.com/facebook/metro). - -Typically, simulator assets are served at the following URLs: - -- Bundle: [http://localhost:8081/index.ios.bundle?platform=ios&dev=true](http://localhost:8081/index.ios.bundle?platform=ios&dev=true) -- Source map: [http://localhost:8081/index.ios.map?platform=ios&dev=true](http://localhost:8081/index.ios.map?platform=ios&dev=true) - -If you want to evaluate Sentry’s source map support using the simulator, you will need to fetch these assets at these URLs (while the React Native packager is running), and upload them to Sentry as artifacts. They should be named using the full URL at which they are located, including the query string. - -### Expanded Usage - -It’s likely you’ll end up in situations where you want to gracefully handle errors. A good pattern for this would be to setup a logError helper: - -```javascript -function logException(ex, context) { - Raven.captureException(ex, { - extra: context, - }); - /*eslint no-console:0*/ - window.console && console.error && console.error(ex); -} -``` - -Now in your components (or anywhere else), you can fail gracefully: - -```javascript -var Component = React.createClass({ - render() { - try { - // .. - } catch (ex) { - logException(ex); - } - }, -}); -``` diff --git a/docs/product/logs/getting-started/index.mdx b/docs/product/logs/getting-started/index.mdx index abe253815930aa..7f38e91cdf089a 100644 --- a/docs/product/logs/getting-started/index.mdx +++ b/docs/product/logs/getting-started/index.mdx @@ -68,13 +68,13 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s - - - - - - - - - - - + getPathMatch(source, { + strict: true, + regexModifier: regex => modifyRouteRegex(regex, ['/_next']), + }); + +// Same matching as `handleRedirects` in middleware.ts +const guideRegex = /\/guides\/(\w+)\//g; +const matchesMiddlewareSource = (sources: Set) => (pagePath: string) => + sources.has(pagePath) || sources.has(pagePath.replace(guideRegex, '/guides/:guide/')); + +test('redirects do not hide existing pages', {timeout: 60_000}, async () => { + const pages = await getDocsFrontMatterFromDirectory(path.join(root, 'docs')); + const pagePaths = pages.map(({slug}) => + isVersioned(slug) ? `/${slug}` : `/${slug}/`.replace(/\/index\/$/, '/') + ); + + const middlewareSources = new Set( + parseMiddlewareTs(path.join(root, 'middleware.ts')).userDocsRedirects.map( + ({source}) => source + ) + ); + const matchers = [ + ...userDocsRedirects.map(({source}) => ({ + source: `redirects.js: ${source}`, + matches: matchesRedirectSource(source), + })), + {source: 'middleware.ts', matches: matchesMiddlewareSource(middlewareSources)}, + ]; + + const hiddenPages = pagePaths.flatMap(pagePath => + matchers + .filter(({matches}) => matches(pagePath)) + .map(({source}) => `${pagePath} (${source})`) + ); + + expect(hiddenPages).toEqual([]); +});