diff --git a/docs/concepts/key-terms/agent-tracing/index.mdx b/docs/concepts/key-terms/agent-tracing/index.mdx index 1b5979876e81f..9b41e03737659 100644 --- a/docs/concepts/key-terms/agent-tracing/index.mdx +++ b/docs/concepts/key-terms/agent-tracing/index.mdx @@ -152,7 +152,7 @@ Click into a specific model for a detailed dashboard view, or scroll through the Depending on the data your agents handle, some of it may be sensitive and shouldn't be recorded in a span. Prompts and agent output aren't recorded by default in Sentry. This is an opt-in feature you can enable by setting `recordInputs`, `recordOutputs`, or both, to true in your Sentry SDK integration options. -[Here is an example from our JavaScript SDK using the Vercel AI SDK →](/platforms/javascript/guides/cloudflare/agent-tracing/vercelai/#record-inputs-and-outputs) +[Here is an example from our JavaScript SDK using the Vercel AI SDK →](/platforms/javascript/guides/cloudflare/configuration/integrations/vercelai/#options) You can explore agent tracing for your SDK here. diff --git a/docs/concepts/otlp/sentry-with-otel.mdx b/docs/concepts/otlp/sentry-with-otel.mdx index 7553d9655aeb2..4e07fd25d68fb 100644 --- a/docs/concepts/otlp/sentry-with-otel.mdx +++ b/docs/concepts/otlp/sentry-with-otel.mdx @@ -87,7 +87,7 @@ If you're running both a Sentry SDK and OTel instrumentation in the same backend - - defaults.filter((i) => !SENTRY_AI_PROVIDER_INTEGRATIONS.has(i.name)), @@ -214,7 +212,7 @@ Also confirm that a wrapped agent delivers spans, logs, and issues from `workerd ## Troubleshooting - **Logs and issues arrive but no traces.** `SENTRY_TRACES_SAMPLE_RATE` defaults to `0`. Set it above `0`. -- **Token and cost values are doubled.** Don't add a second AI tracing integration such as the Vercel AI integration or Anthropic integration. The blueprint removes them on purpose because Flue already emits the model spans. +- **Token and cost values are doubled.** Don't add a second AI tracing integration such as the Vercel AI integration or Anthropic integration. The blueprint removes them on purpose because Flue already emits the model spans. - **A tool error did not create an issue.** Only terminal operation and submission failures create issues. A recovered tool error stays on the trace as diagnostic context. ## Supported Versions diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index c4389c231d7d6..4ffecb4aadda0 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -13,52 +13,9 @@ With Sentry Agent Tracing, you can -## Getting Started +## Supported Instrumentation -Enable tracing and pass `dataCollection` so generative AI content follows the SDK defaults (including prompts and responses when left unconfigured). - -`dataCollection: {}` also opts into other **permissive** defaults (bodies, cookies, user info, and more). Tighten via `dataCollection`. - - - -```javascript -import * as Sentry from "___SDK_PACKAGE___"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - dataCollection: {}, -}); -``` - - - - - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - dataCollection: {}, - }), - { - async fetch(request, env, ctx) { - // your worker - }, - } -); -``` - -Durable Objects / Agents SDK: use `instrumentDurableObjectWithSentry` with the same options. - - - -## Instrumentation - -Pick your AI stack. Some libraries auto-instrument; others need a short setup — each page has the details. +As of SDK version `11.0.0`, Sentry auto-instruments the most popular AI SDKs and frameworks out of the box — no manual setup is required. Just enable tracing, then pick your AI stack below. Each integration page has the details. @@ -238,38 +213,6 @@ On the default CF entrypoint, control Vercel AI I/O with `experimental_telemetry From SDK `10.61.0`, `gen_ai` spans are sent as standalone envelope items (avoids large-payload drops; required for Conversations). -Self-hosted Sentry users should set `streamGenAiSpans: false` if standalone `gen_ai` spans may not be ingested. - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - streamGenAiSpans: false, -}); -``` - - - - - -```javascript -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - streamGenAiSpans: false, - }), - { - async fetch(request, env, ctx) { - /* ... */ - }, - } -); -``` - - - ## Manual Instrumentation =0.2.0 <2.0.0` diff --git a/docs/platforms/javascript/common/agent-tracing/openai.mdx b/docs/platforms/javascript/common/agent-tracing/openai.mdx deleted file mode 100644 index ffec8e6a242b1..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/openai.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: OpenAI -description: "Adds instrumentation for the OpenAI SDK." -sidebar_order: 21 -supportedCategories: - - server ---- - -_Import name: `Sentry.openAIIntegration`_ - -The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmjs.com/package/openai) SDK to capture spans by wrapping OpenAI SDK calls and recording LLM interactions. - -This integration is enabled by default and automatically captures spans for OpenAI SDK calls (requires Sentry SDK version `10.28.0` or higher). - -To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. - -## Configuration - -### Options - -The following options control what data is captured from OpenAI SDK calls: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to OpenAI SDK calls (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ - -Records outputs from OpenAI SDK calls (such as generated text and responses). - -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -**Usage** - -```javascript -Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work - tracesSampleRate: 1.0, - integrations: [ - Sentry.openAIIntegration({ - // your options here - }), - ], -}); -``` - -## Supported Operations - -By default, tracing support is added to the following OpenAI SDK calls: - -- `chat.completions.create()` - Chat completion requests -- `responses.create()` - Response SDK requests -- `embeddings.create()` - Generate embeddings -- `conversations.create()` - Create conversations - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -`chat.completions.create()` and `responses.create()` produce the same span type in Sentry: op `gen_ai.chat`, name like `chat `. There is no separate `gen_ai.responses` span — `responses.create()` is still a model chat request under the hood, so it uses the standard chat operation. - -Instrumented chat completion and response calls record model, token usage, latency, and (when enabled) inputs/outputs on the LLM span. If you pass `tools` to the request, Sentry stores the tool definitions on the span and records any tool calls the model returns as span attributes. - -### Tool execution spans - -The OpenAI SDK does **not** run your tools — your application does, after the model returns `tool_calls`. Because of that, the OpenAI integration does **not** create `gen_ai.execute_tool` spans for local tool handlers. - -To get the full agent tree (`gen_ai.invoke_agent` → `gen_ai.chat` + `gen_ai.execute_tool`), wrap your tool loop with manual instrumentation. - -### Streaming token usage - - - -When using OpenAI's streaming API, you must also pass `stream_options: { include_usage: true }` to receive token usage data. Without this option, OpenAI does not include `prompt_tokens` or `completion_tokens` in streamed responses, and Sentry will be unable to capture `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` on the resulting span. This is an OpenAI API behavior, not a Sentry limitation. See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create). - - - -```javascript -const stream = await openai.chat.completions.create({ - model: "gpt-4o-mini", - messages: [{ role: "user", content: "Hello!" }], - stream: true, - stream_options: { include_usage: true }, -}); -``` - -## Supported Versions - -- `openai`: `>=4.0.0 <8` diff --git a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx b/docs/platforms/javascript/common/agent-tracing/vercelai.mdx deleted file mode 100644 index fec05b2bc999b..0000000000000 --- a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx +++ /dev/null @@ -1,621 +0,0 @@ ---- -title: Vercel AI -description: "Adds instrumentation for Vercel AI SDK." -sidebar_order: 20 -supportedCategories: - - server ---- - -_Import name: `Sentry.vercelAIIntegration`_ - -The `vercelAIIntegration` adds instrumentation for the [`ai`](https://www.npmjs.com/package/ai) SDK by Vercel to capture spans using the [AI SDK's built-in telemetry](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry). - - - -Don't use the AI SDK's `registerTelemetry` API (AI SDK v7 and above) together with this integration. `vercelAIIntegration` already instruments the AI SDK, so registering telemetry separately produces duplicate spans. - - - - - -## Runtime Differences - - - -Next.js runs your server code in two runtimes. In both, you must pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - -Everything else depends on which runtime you're in: - -| | Node runtime | Edge runtime | -| ------------------------- | ----------------------- | ----------------------------------- | -| Enabled by default | Yes | No — add it to `sentry.edge.config` | -| Record inputs and outputs | Integration or per call | Per call only | -| `force` | Available | Not available — always active | -| AI SDK v7 | Supported | Not supported | - - - - - -Cloudflare Workers can't load OpenTelemetry instrumentation. On both entrypoints, Sentry reads the spans the AI SDK emits on its own instead of patching your call sites, so you must pass `experimental_telemetry` on every call. The `@sentry/cloudflare/nodejs_compat` entrypoint adds the Node.js APIs the AI SDK v7 telemetry channel needs. - -Your entrypoint decides the rest: - -| | `@sentry/cloudflare` | `@sentry/cloudflare/nodejs_compat` | -| ---------------------------- | -------------------- | ---------------------------------- | -| Record inputs and outputs | Per call only | Integration or per call | -| AI SDK v7 | Not supported | Supported | -| Minimum Sentry SDK | `10.6.0` | `10.64.0` | -| Minimum `compatibility_date` | `2024-09-23` | `2026-02-19` | - - - - - -## Setup - - - -The integration is enabled by default and captures spans for all `ai` function calls. No setup code is needed beyond enabling tracing: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` - -Prompts and completions are not captured until you opt in. See [Record inputs and outputs](#record-inputs-and-outputs). - - - - - -### Node Runtime - -The integration is enabled by default: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` - -### Edge Runtime - -The integration is not enabled by default. Add it yourself: - -```javascript {filename:sentry.edge.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], -}); -``` - -In both runtimes, adding the integration is not enough on its own. You must also pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - -If your spans have raw names like `ai.toolCall`, see [Troubleshooting](#troubleshooting). - - - - - -The integration is not enabled by default. Add it yourself: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], -}); -``` - -Deno can't load OpenTelemetry instrumentation, so Sentry can't patch your call sites. Adding the integration is not enough on its own — you must also pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). - - - - - -### AI SDK v7 - -Use the `@sentry/cloudflare/nodejs_compat` entrypoint and enable the Wrangler `nodejs_compat` flag: - -```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -```jsonc {filename:wrangler.jsonc} -{ - "compatibility_date": "2026-02-19", - "compatibility_flags": ["nodejs_compat"], -} -``` - - - -AI SDK v7 only emits telemetry when `compatibility_date` is `2026-02-19` or later, and Wrangler is `4.67.0` or later. With an earlier date you get no AI spans and no error message. - - - -### AI SDK v6 and Below - -Import `@sentry/cloudflare` instead: - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [Sentry.vercelAIIntegration()], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -On both entrypoints, adding the integration is not enough on its own. Cloudflare can't patch your call sites, so you must also pass `experimental_telemetry` on every call — including on `nodejs_compat`. See [Turn on telemetry](#turn-on-telemetry). - - - -## Record Inputs and Outputs - -Prompts and completions are not captured by default, because they usually contain user data. Turn recording on with `recordInputs` and `recordOutputs`. - -Sentry resolves both settings in this order, and stops at the first one that is set: - -1. The integration option — applies to every call. -2. The call's `experimental_telemetry` — applies to that call. -3. `dataCollection.genAI` — applies to every call. - -The integration option wins over the call, not the other way around. If you set `recordInputs: false` on the integration, no call site can turn it back on. - - - -Set the options on the integration to cover every call. Re-adding the integration replaces the default instance and configures it: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], -}); -``` - -To record only some calls, leave the integration options unset and set them per call instead: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -Set the options on the integration to cover every call (Node runtime only). Re-adding the integration replaces the default instance and configures it: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], -}); -``` - - - -The Edge runtime ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -Or set them per call, which works in both runtimes: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -### `@sentry/cloudflare/nodejs_compat` - -Set the options on the integration to cover every call: - -```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - Sentry.vercelAIIntegration({ - recordInputs: true, - recordOutputs: true, - }), - ], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - -### `@sentry/cloudflare` - - - -The default entrypoint ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - - - -Deno ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. - - - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - isEnabled: true, - recordInputs: true, - recordOutputs: true, - }, -}); -``` - - - - - -`dataCollection: {}` also turns recording on, but it opts you into the SDK's permissive defaults for every other category too: user identity, cookies, headers, HTTP bodies, query parameters, and stack-frame locals. Prefer the integration and per-call options above unless you want all of it. See `dataCollection`. - - - -## Configure individual calls - -Every instrumented `ai` function takes an `experimental_telemetry` object. Use it to control one call instead of all of them. For the full list of fields, see the [AI SDK telemetry metadata docs](https://sdk.vercel.ai/docs/ai-sdk-core/telemetry#telemetry-metadata). - - - -### Turn on Telemetry - - - -Required in both the Node and Edge runtimes. - - - -Set `isEnabled` to `true` on every instrumented call. Without it, the AI SDK emits no spans and Sentry has nothing to capture: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: true }, -}); -``` - -For `ToolLoopAgent`, set it on the constructor instead. See [ToolLoopAgent](#toolloopagent). - - - -### Skip a Call - -To capture no span for one call, set `isEnabled` to `false`: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: false }, -}); -``` - -### Identify Your Call Sites - -Spans carry the AI SDK function name, not yours, so a trace with several `generateText` calls is hard to read. Set `functionId` to label the call site. It appears on the span as `gen_ai.function_id`: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { - functionId: "summarize-ticket", - }, -}); -``` - -### ToolLoopAgent - -The integration captures spans for the [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/overview#toolloopagent-class) class. Each call to `generate()` or `stream()` creates an agent span, with the individual LLM requests and tool executions as child spans. - -`ToolLoopAgent` takes its telemetry settings on the constructor, not on `generate()` or `stream()`: - - - -```javascript -const agent = new ToolLoopAgent({ - model: openai("gpt-4o"), - tools: { - /* ... */ - }, - experimental_telemetry: { - functionId: "weather-agent", - }, -}); - -const result = await agent.generate({ - prompt: "What is the weather in San Francisco?", -}); -``` - -Spans are captured without the `experimental_telemetry` block. Pass it only to set `functionId` or the recording options. - - - - - -```javascript -const agent = new ToolLoopAgent({ - model: openai("gpt-4o"), - tools: { - /* ... */ - }, - experimental_telemetry: { - isEnabled: true, - functionId: "weather-agent", - }, -}); - -const result = await agent.generate({ - prompt: "What is the weather in San Francisco?", -}); -``` - - - -## Options - - - -Pass these to `Sentry.vercelAIIntegration()`. The Edge runtime accepts `enableTruncation` only. - - - - - -Pass these to `Sentry.vercelAIIntegration()`. The default `@sentry/cloudflare` entrypoint accepts `enableTruncation` only; `nodejs_compat` also accepts `recordInputs` and `recordOutputs`. Neither has module detection to override, so `force` does not apply. - - - - - -Pass these to `Sentry.vercelAIIntegration()`. Deno accepts `enableTruncation` only. It has no module detection to override, so `force` does not apply. - - - -### `enableTruncation` - -_Type: `boolean`_ - -Truncates recorded input messages so large payloads stay within span size limits. Affects inputs only, not outputs. - -Defaults to `true`. - - - -```javascript -Sentry.init({ - integrations: [Sentry.vercelAIIntegration({ enableTruncation: false })], -}); -``` - - - - - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -export default Sentry.withSentry( - (env) => ({ - dsn: "___PUBLIC_DSN___", - integrations: [Sentry.vercelAIIntegration({ enableTruncation: false })], - }), - { - async fetch(request, env, ctx) { - /* your worker */ - }, - }, -); -``` - - - - - -### `force` - -_Type: `boolean`_ - -Registers the integration's span processors even when the `ai` module can't be detected. Set this when your build bundles `ai`, which defeats module detection. See [Troubleshooting](#troubleshooting). - -Defaults to `false`. - -```javascript -Sentry.init({ - integrations: [Sentry.vercelAIIntegration({ force: true })], -}); -``` - - - -`force` only registers the span processors. You still need `experimental_telemetry` on every call. Not available in the Edge runtime, where the integration is always active once you add it. - - - - - -### `recordInputs` - -_Type: `boolean`_ - -Records inputs to the `ai` function call. See [Record inputs and outputs](#record-inputs-and-outputs) for the full resolution order and the per-call alternative. - -### `recordOutputs` - -_Type: `boolean`_ - -Records outputs from the `ai` function call. See [Record inputs and outputs](#record-inputs-and-outputs) for the full resolution order and the per-call alternative. - -## Supported Operations - - - -Spans are captured for these `ai` functions: - - - - - -Spans are captured for these `ai` functions. Pass `experimental_telemetry` to each one, as described in [Turn on telemetry](#turn-on-telemetry): - - - -- `generateText()` -- `streamText()` -- `generateObject()` -- `streamObject()` -- `embed()` -- `embedMany()` -- `rerank()` - -Plus `generate()` and `stream()` on [`ToolLoopAgent`](#toolloopagent). - -## Supported Versions - -- `ai`: `>=3.0.0 <=7` - - - -- Sentry SDK: `10.6.0`+ - - - - - -- Sentry SDK: `10.6.0`+ -- Edge runtime: `ai` v7 is not supported. Use v6 or below, or run the call in the Node runtime. - - - - - -- Sentry SDK: `10.12.0`+ - - - - - -- Sentry SDK: `10.6.0`+ with `@sentry/cloudflare` -- Sentry SDK: `10.64.0`+ with `@sentry/cloudflare/nodejs_compat`, required for `ai` v7 - - - -## Troubleshooting - - - - - -Raw names mean the AI SDK's telemetry is already on and emitting spans — Sentry's span processors just aren't registered to rename them. Add `force: true`: - -```javascript {filename:sentry.server.config.ts} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [Sentry.vercelAIIntegration({ force: true })], -}); -``` - -Keep `experimental_telemetry` on your calls. It's what produces the spans in the first place, so `force: true` without it leaves you with no AI spans at all. If only some of your spans have raw names, the remaining call sites are missing it: - -```javascript -const result = await generateText({ - model: openai("gpt-4o"), - experimental_telemetry: { isEnabled: true }, -}); -``` - - - - - - - -Recording is off unless you turn it on. Check, in order: - -1. `recordInputs` and `recordOutputs` are set. See [Record inputs and outputs](#record-inputs-and-outputs). -2. You set them in a place the runtime reads. Some runtimes ignore the integration options and take them per call only. -3. No integration option is overriding your per-call value. The integration option wins. - - diff --git a/docs/platforms/javascript/common/best-practices/index.mdx b/docs/platforms/javascript/common/best-practices/index.mdx index 6fbf731a00c1d..53e4910a8c304 100644 --- a/docs/platforms/javascript/common/best-practices/index.mdx +++ b/docs/platforms/javascript/common/best-practices/index.mdx @@ -9,7 +9,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx index 69fde67ba8326..d288edd44641d 100644 --- a/docs/platforms/javascript/common/best-practices/micro-frontends.mdx +++ b/docs/platforms/javascript/common/best-practices/micro-frontends.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx b/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx index f8f01830c2263..4cde6099865e7 100644 --- a/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx +++ b/docs/platforms/javascript/common/best-practices/multiple-sentry-instances.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/offline-caching.mdx b/docs/platforms/javascript/common/best-practices/offline-caching.mdx index 87f29ea9e809f..e27799bb0edbb 100644 --- a/docs/platforms/javascript/common/best-practices/offline-caching.mdx +++ b/docs/platforms/javascript/common/best-practices/offline-caching.mdx @@ -12,7 +12,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 82ae8d0786ce9..bb10d6d4fa03b 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/apis.mdx b/docs/platforms/javascript/common/configuration/apis.mdx index 6838251ae1011..44d8be66000da 100644 --- a/docs/platforms/javascript/common/configuration/apis.mdx +++ b/docs/platforms/javascript/common/configuration/apis.mdx @@ -134,13 +134,12 @@ Sentry.withScope((scope) => { }); ``` - - `beforeSend`, `beforeSendTransaction`, and `beforeSendSpan` are guaranteed to be run last, after all other event processors, (which means they get the final version of the event right before it's sent, hence the name). Event processors added with `addEventProcessor` are run in an undetermined order, which means changes to the event may still be made after the event processor runs. + + `beforeSend` runs after all event processors and receives the final error or message event before it is sent. Event processors added with `addEventProcessor` run in an undetermined order, so another processor may still change the event afterward. - There can only be a single `beforeSend` / `beforeSendTransaction` / `beforeSendSpan` callback, but you can add multiple event processors via `addEventProcessor()`. - - If you're using stream mode, use `beforeSendSpan`, since event processors are not applied to spans. + You can configure one `beforeSend` callback and add multiple event processors with `addEventProcessor()`. + Event processors do not run on streamed spans. Use `beforeSendSpan` to modify each finished span before it is sent. In transaction mode, event processors also run on transaction events, followed by `beforeSendTransaction`. You can configure one `beforeSendTransaction` callback. @@ -473,13 +472,13 @@ Sentry.setContext("character", { On the server, the IP address will be inferred from the incoming HTTP request, if available. - This is automatically done if you have configured `dataCollection: { userInfo: true }` (or the deprecated `sendDefaultPii: true`) in your SDK configuration. + This is automatically done if you have configured `dataCollection: { userInfo: true }` in your SDK configuration. On the browser, if the users' `ip_address` is set to `"{{ auto }}"`, Sentry will infer the IP address from the connection between your app and Sentry's - server. `{{auto}}` is automatically set if you have configured `dataCollection: { userInfo: true }` (or the deprecated `sendDefaultPii: true`) in your SDK configuration. + server. `{{auto}}` is automatically set if you have configured `dataCollection: { userInfo: true }` in your SDK configuration. To ensure your users' IP addresses are never stored in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data scrubbing](/security-legal-pii/scrubbing/) to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. @@ -842,18 +841,15 @@ Sentry.reportPageLoaded(); These utilities can be used for more advanced tracing use cases. - - Convert a span to a JSON object. If you're using{" "} - stream mode, we - recommend using [`spanToStreamedSpanJSON`](#spanToStreamedSpanJSON) instead. + + Convert a span to a JSON object. If you're using {" "} + `traceLifecycle: 'static'`, + use [`spanToStaticSpanJSON`](#spanToStaticSpanJSON) to get the `SpanJSON` format. - - Convert a span to a JSON object. Only available in{" "} - stream mode. + + Convert a span to the static `SpanJSON` format. Use this when working with transaction data in + transaction mode. { ## Server Request Instrumentation -Astro server requests are automatically instrumented starting from Astro version `3.5.2`. +Astro server requests are automatically instrumented. -If you're below Astro version `3.5.2` or want to customize instrumentation, you can use `Sentry.handleRequest()` as an Astro middleware. +If you want to customize instrumentation, you can use `Sentry.handleRequest()` as an Astro middleware. -If you're using Astro version `>=3.5.2`, you must disable automatic instrumentation before adding this middleware manually. +You must disable automatic instrumentation before adding this middleware manually. diff --git a/docs/platforms/javascript/common/configuration/async-context.mdx b/docs/platforms/javascript/common/configuration/async-context.mdx index ecd7a100c3c38..6ac68d46b8ceb 100644 --- a/docs/platforms/javascript/common/configuration/async-context.mdx +++ b/docs/platforms/javascript/common/configuration/async-context.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/event-loop-block.mdx b/docs/platforms/javascript/common/configuration/event-loop-block.mdx index 0f29e92c06620..c5f7cd0440179 100644 --- a/docs/platforms/javascript/common/configuration/event-loop-block.mdx +++ b/docs/platforms/javascript/common/configuration/event-loop-block.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/filtering.mdx b/docs/platforms/javascript/common/configuration/filtering.mdx index 28ffceca97572..d52ef5f3951bc 100644 --- a/docs/platforms/javascript/common/configuration/filtering.mdx +++ b/docs/platforms/javascript/common/configuration/filtering.mdx @@ -57,7 +57,7 @@ This integration can be very helpful in reducing noise that's not related to you -**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js with Turbopack**, use the [`_experimental.turbopackApplicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackapplicationkey) build option instead. +**Prerequisite**: To use the `thirdPartyErrorFilterIntegration`, ensure you are using a bundler and one of [Sentry's bundler plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins). For **Next.js**, set the [`applicationKey`](/platforms/javascript/guides/nextjs/configuration/build/#applicationKey) build option, which works for both Webpack and Turbopack builds. @@ -111,53 +111,17 @@ This is the case because the Sentry Loader Script and CDN Bundles are detected a -## Filtering Transaction Events - - - The options in this section are only available in transaction mode. If you're - using stream mode, go to - [Filtering Spans](#filtering-spans). - - -To prevent certain transactions from being reported to Sentry, use the or configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. - -### Using - -You can use the option to filter out transactions that match a certain pattern. This option receives a list of strings and regular expressions to match against the transaction name. When using strings, partial matches will be filtered out. If you need to filter by exact match, use regex patterns instead. - - - -See ignoreTransactions for details. - -### Using - -You can also use the tracesSampler option to prevent certain transactions from being reported to Sentry. - -See Sampling on information about how to use it. - -### Using `beforeSendTransaction` - - - -See beforeSendTransaction for details, and [Using Hints](#using-hints) for details on the `hint` object. - ## Filtering Spans -### Using - -Use the configuration option, which lets you provide a function to modify a span. -This function is called for the transaction (service span in stream mode) and all child spans. +Use `beforeSendSpan` to change span data and `ignoreSpans` to drop spans. To make sampling decisions when spans start, use `tracesSampler`. -If you want to drop the transaction/service span, including its child spans: - -- Use [`beforeSendTransaction`](#using-beforesendtransaction) in transaction mode. -- Use [`ignoreSpans`](#using-ignore-spans) in stream mode. +### Using - +Use the configuration option to modify each finished span before it is sent. This function is called for all spans, including service spans and their child spans. -If you're using stream mode, make sure to wrap with `Sentry.withStreamedSpan()`. +Check `span.is_segment` to modify only service spans. In transaction mode, wrap the callback with `Sentry.withStaticSpan()` to modify the transaction and its child spans using the `SpanJSON` format. - +To drop a service span and its child spans, use [`ignoreSpans`](#using-ignore-spans). `beforeSendSpan` cannot return `null` to drop spans. @@ -169,12 +133,14 @@ You can use the option to filter out You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided. +In stream mode, rules run when the span starts, so later name and attribute changes do not affect matching. In transaction mode, rules use the final name and attributes when the transaction ends. Ignoring a service span drops its child spans; ignoring a child span reparents its children to the nearest ancestor. + ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", ignoreSpans: [ - "partial/match", - /^Exact Span Name$/, + { name: "partial/match", op: "http.server" }, + { name: /^Exact Span Name$/, op: "http.server" }, { name: /^GET \//, attributes: { @@ -185,8 +151,30 @@ Sentry.init({ }); ``` +Use the operation of your service span, such as `http.server`, `pageload`, or `navigation`, to avoid matching unrelated child spans with the same name. + See ignoreSpans for details. +## Filtering Transaction Events + +These options apply when `traceLifecycle: 'static'` is set. In the default stream mode, use [Filtering Spans](#filtering-spans). + +### Using + +Use `ignoreTransactions` to drop transactions whose names match a string or regular expression. Strings match part of the name. Use an anchored regular expression for an exact match. Matching transactions and their child spans are dropped. + + + +See `ignoreTransactions` for details. + +### Using `beforeSendTransaction` + +Use `beforeSendTransaction` to modify or drop a completed transaction before it is sent. Return the transaction event to send it, or `null` to drop it and its child spans. + + + +See `beforeSendTransaction` for details and [Using Hints](#using-hints) for the `hint` argument. + ## Filtering Breadcrumbs You can filter breadcrumbs by using the `beforeBreadcrumb` configuration option: diff --git a/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx b/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx index 2c64c54c7e15a..dc74de0e324dd 100644 --- a/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/amqplib.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/anr.mdx b/docs/platforms/javascript/common/configuration/integrations/anr.mdx index 80ff2fc2af6d5..4805aaa9504dd 100644 --- a/docs/platforms/javascript/common/configuration/integrations/anr.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/anr.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/agent-tracing/anthropic.mdx b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx similarity index 61% rename from docs/platforms/javascript/common/agent-tracing/anthropic.mdx rename to docs/platforms/javascript/common/configuration/integrations/anthropic.mdx index fc7f104d4b447..6682c766cf3d8 100644 --- a/docs/platforms/javascript/common/agent-tracing/anthropic.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/anthropic.mdx @@ -1,26 +1,52 @@ --- title: Anthropic -description: "Adds instrumentation for the Anthropic SDK." -sidebar_order: 22 +description: "Adds instrumentation for the Anthropic SDK. (default)" supportedCategories: - server + - serverless +notSupported: + - javascript.mastra --- + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + _Import name: `Sentry.anthropicAIIntegration`_ -The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions. +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.anthropicAIIntegration()], +}); +``` -This integration is enabled by default and automatically captures spans for Anthropic SDK calls (requires Sentry SDK version `10.28.0` or higher). +## Supported Operations -To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. +By default, tracing support is added to the following Anthropic SDK calls: -## Configuration +- `messages.create()` - Create messages with Claude models +- `messages.stream()` - Stream messages with Claude models +- `completions.create()` - Create completions (legacy) +- `beta.messages.create()` - Beta messages API -### Options +Streaming and non-streaming requests are automatically detected and handled appropriately. -The following options control what data is captured from Anthropic SDK calls: +## Supported Versions -#### `recordInputs` +- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0` + +## Options + +### `recordInputs` _Type: `boolean` (optional)_ @@ -28,7 +54,7 @@ Records inputs to Anthropic SDK calls (such as prompts and messages). Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. -#### `recordOutputs` +### `recordOutputs` _Type: `boolean` (optional)_ @@ -36,35 +62,15 @@ Records outputs from Anthropic SDK calls (such as generated text and responses). Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. -**Usage** - ```javascript Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work + dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, integrations: [ Sentry.anthropicAIIntegration({ - // your options here + recordInputs: true, + recordOutputs: true, }), ], }); ``` - -## Supported Operations - -By default, tracing support is added to the following Anthropic SDK calls: - -- `messages.create()` - Create messages with Claude models -- `messages.stream()` - Stream messages with Claude models -- `messages.countTokens()` - Count tokens for messages -- `models.get()` - Get model information -- `completions.create()` - Create completions (legacy) -- `models.retrieve()` - Retrieve model details -- `beta.messages.create()` - Beta messages API - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -## Supported Versions - -- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0` diff --git a/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx new file mode 100644 index 0000000000000..028209e809a96 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/bfcache.mdx @@ -0,0 +1,101 @@ +--- +title: BFCache Metrics +description: "Track browser back/forward cache (bfcache) health as Sentry Application Metrics." +beta: true +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun +--- + + + + + +This integration only works inside a browser environment. + + + +_Import name: `Sentry.bfcacheMetricsIntegration`_ + +The `bfcacheMetricsIntegration` tracks the health of the browser's [back/forward cache (bfcache)](https://web.dev/articles/bfcache) and emits it as [Sentry Application Metrics](/product/metrics/). The bfcache is a browser optimization that restores a previously visited page instantly from an in-memory snapshot when the user navigates back or forward. When the cache is hit, the back button feels instant; when it isn't, the same action becomes a full page reload. + +Use this integration to answer these questions: + +- What share of back/forward navigations does the browser restore instantly? +- Which routes miss the bfcache most often? +- What is blocking the browser from caching the page? +- How expensive is the fallback reload when a restore fails? + +```javascript +Sentry.init({ + integrations: [Sentry.bfcacheMetricsIntegration()], +}); +``` + +This integration requires Sentry Application Metrics to be available in your Sentry organization. + +A **hit** is a back/forward navigation that the browser restored instantly from the bfcache; a **miss** is one that fell back to a full page load. Hit/miss detection works across modern Chromium, Firefox, and Safari. When a miss occurs, the SDK also records the [`notRestoredReasons`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons) the browser reports for it. This API is currently Chromium-only, so the SDK records misses on other browsers without reasons. + +## Options + +### `maxReasons` + +A single miss can report several not-restored reasons (for example, multiple frames can block one page). By default, the SDK emits every reported reason. Set `maxReasons` to cap how many it emits per miss: + +```javascript +Sentry.init({ + integrations: [ + Sentry.bfcacheMetricsIntegration({ + maxReasons: 3, + }), + ], +}); +``` + +The SDK clamps values below `1` to `1`, since a lower cap would drop all reason data. This option only limits the `browser.bfcache.not_restored` metric and doesn't affect the reason count on `browser.bfcache.navigation`. + +## Emitted Metrics + +| Metric | Type | Description | +| --------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.navigation` | counter | One per back/forward navigation, split by outcome (`hit` or `miss`). | +| `browser.bfcache.not_restored` | counter | One per not-restored reason on a miss. Chromium-only. | +| `browser.bfcache.reload.duration` | distribution | Duration (in milliseconds) of the fallback reload when a back/forward navigation missed the bfcache. The SDK only emits this when the browser reports a duration. | + +### Attributes + +`browser.bfcache.navigation` includes: + +| Attribute | Description | +| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.outcome` | `hit` if the browser restored the page from the bfcache, `miss` if it reloaded the page. | +| `browser.bfcache.not_restored_reason_count` | The number of reasons the browser reported for a miss. The SDK omits this on hits and on misses where the browser reported no reasons. | +| `sentry.segment.name` | The route the navigation landed on, which the SDK takes from the scope's transaction name. Falls back to `window.location.pathname` if the scope has none. | + +`browser.bfcache.not_restored` includes: + +| Attribute | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------- | +| `browser.bfcache.reason` | A reason the browser reported for not restoring the page (for example, `unload-listener`, `websocket`). | +| `browser.bfcache.frame` | Where the reason originated: the `top` document or a `child` frame. | +| `sentry.segment.name` | The route the navigation landed on. | + +`browser.bfcache.reload.duration` includes `sentry.segment.name` only. + +## A Note on Reasons + +The browser defines the `notRestoredReasons` strings, and they can change between versions. Chrome also reports a privacy-masked `masked` reason alongside real ones for cross-origin frames. Treat the reason values as a moving target rather than a fixed enum, and group on them accordingly in dashboards. diff --git a/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx b/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx index 72fbe1fbe7273..1fe7d59974365 100644 --- a/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx @@ -6,8 +6,6 @@ notSupportedCategories: - server-only --- - - This integration only works inside a browser environment. @@ -20,13 +18,14 @@ This integration is enabled by default. If you'd like to modify your default int The `breadcrumbsIntegration` wraps native APIs to capture breadcrumbs. -By default, the Sentry SDK wraps the `console`, `dom`, `fetch`, `history`, and `xhr` browser APIs to add breadcrumbs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture `console.log` calls as breadcrumbs) via the options below. +By default, the Sentry SDK wraps the `dom`, `fetch`, `history`, and `xhr` browser APIs to add breadcrumbs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture click and keypress events as breadcrumbs) via the options below. + +Console calls are captured by the `consoleIntegration`, which is enabled by default. ```JavaScript Sentry.init({ integrations: [ Sentry.breadcrumbsIntegration({ - console: true, dom: true, fetch: true, history: true, @@ -38,12 +37,6 @@ Sentry.init({ ## Options -### `console` - -_Type: `boolean`_ - -Log calls to `console.log`, `console.debug`, and so on. - ### `dom` _Type: `boolean` | `{ serializeAttribute: string | string[] }`_ diff --git a/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx b/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx index 2dfc4d4e13f09..4708c2bc60018 100644 --- a/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/browsersession.mdx @@ -27,11 +27,21 @@ Sentry.init({ ## Configuration Options - + Controls how long one session lasts and when a new session is started. -- `'route'`: A new session is started when the route changes, based on the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). This is the default behavior. If you're building a single-page application (SPA), this will result in one session being created per soft navigation. -- `'page'`: A new session is started when the page changes on a hard page reload or navigation. This is useful if you're building a single-page application (SPA) and want to track one session across multiple routes as users navigate through your application. +- `'page'`: Starts a session on page load. Client-side route changes keep the same session. This is the default. +- `'route'`: Starts a session on page load and on each navigation detected through the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). + +Before SDK version 11, the default was `'route'`. + +To create a session on each client-side navigation in a single-page application, set `lifecycle` to `'route'`: + +```javascript +Sentry.init({ + integrations: [Sentry.browserSessionIntegration({ lifecycle: "route" })], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx b/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx index 61e0ef1e52b4f..fc9695bd3fe1c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/childProcess.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/connect.mdx b/docs/platforms/javascript/common/configuration/integrations/connect.mdx deleted file mode 100644 index 063349091b6ad..0000000000000 --- a/docs/platforms/javascript/common/configuration/integrations/connect.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Connect -description: "Adds performance instrumentation for Connect. (default)" -supported: - - javascript.node - - javascript.connect - - javascript.hapi ---- - -For more information on setting up Sentry Connect support, see the [Connect Sentry documentation](/platforms/javascript/guides/connect/). - - - -This integration only works in the Node.js and Bun runtimes. - - - -_Import name: `Sentry.connectIntegration`_ - -This integration is enabled by default when performance monitoring is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -The `connectIntegration` adds instrumentation for the Hapi framework to capture spans using [`@opentelemetry/instrumentation-connect`](https://www.npmjs.com/package/@opentelemetry/instrumentation-connect). - -```JavaScript -Sentry.init({ - integrations: [Sentry.connectIntegration()], -}); -``` - -## Supported Versions - -- `connect`: `^3.0.0` diff --git a/docs/platforms/javascript/common/configuration/integrations/console.mdx b/docs/platforms/javascript/common/configuration/integrations/console.mdx index 8bd80ff2d03e4..85184d2d03b59 100644 --- a/docs/platforms/javascript/common/configuration/integrations/console.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/console.mdx @@ -1,10 +1,19 @@ --- title: Console description: "Capture console logs as breadcrumbs. (default)" -customCanonicalTag: "/platforms/javascript/guides/express/configuration/integrations/console/" +customCanonicalTag: "/platforms/javascript/configuration/integrations/console/" supportedCategories: - server supported: + - javascript + - javascript.angular + - javascript.ember + - javascript.gatsby + - javascript.react + - javascript.solid + - javascript.svelte + - javascript.vue + - javascript.wasm - javascript.electron --- diff --git a/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx b/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx index 1dc82214c26dd..4b94250dfb48b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/dataloader.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx index c13728f4ddd06..e048b45bca42c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/event-loop-block.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx b/docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx similarity index 86% rename from docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx rename to docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx index efabcf626d75c..83b29752ed011 100644 --- a/docs/platforms/javascript/common/configuration/integrations/inboundfilters.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/eventfilters.mdx @@ -1,9 +1,15 @@ --- -title: InboundFilters +title: EventFilters description: "Allows you to ignore specific errors based on the type, message, or URLs in a given exception. (default)" --- -_Import name: `Sentry.inboundFiltersIntegration`_ +_Import name: `Sentry.eventFiltersIntegration`_ + + + +In SDK versions before 11, this integration was called `InboundFilters` and exported as `inboundFiltersIntegration`. + + This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). diff --git a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx index 2a3100fddb41c..41f997c579394 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fastify.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fastify.mdx @@ -30,4 +30,4 @@ Sentry.init({ ## Supported Versions -- `fastify`: `^3.0.0 || ^4.0.0` +- `fastify`: `^3.21.0 || ^4.0.0` diff --git a/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx new file mode 100644 index 0000000000000..cae1dbf0ca6b6 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/fetchstreamperformance.mdx @@ -0,0 +1,55 @@ +--- +title: FetchStreamPerformance +description: "Measure how long streamed fetch response bodies take to finish." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.fetchStreamPerformanceIntegration`_ + +The FetchStreamPerformance integration measures how long streamed fetch responses take to finish. It captures spans from when response headers arrive until the body finishes, up to 90 seconds. + +Use it with BrowserTracing or your framework's routing integration. + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.fetchStreamPerformanceIntegration(), + ], +}); +``` + +Responses are tracked when they have no `content-length` header and their `content-type` starts with one of these values: + +- `text/event-stream` +- `application/x-ndjson` +- `application/stream+json` + +This integration has no configuration options. diff --git a/docs/platforms/javascript/common/configuration/integrations/fs.mdx b/docs/platforms/javascript/common/configuration/integrations/fs.mdx index 50f2aeac1f41d..14f143e58904c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/fs.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/fs.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx b/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx index 3b9bd2f879aae..f44627c0438e9 100644 --- a/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/genericpool.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/agent-tracing/google-genai.mdx b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx similarity index 60% rename from docs/platforms/javascript/common/agent-tracing/google-genai.mdx rename to docs/platforms/javascript/common/configuration/integrations/google-genai.mdx index 762ad9a0d1731..e28027998f703 100644 --- a/docs/platforms/javascript/common/agent-tracing/google-genai.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/google-genai.mdx @@ -1,26 +1,54 @@ --- title: Google Gen AI -description: "Adds instrumentation for Google Gen AI SDK." -sidebar_order: 23 +description: "Adds instrumentation for the Google Gen AI SDK. (default)" supportedCategories: - server + - serverless +notSupported: + - javascript.mastra --- + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + _Import name: `Sentry.googleGenAIIntegration`_ -The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions. +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.googleGenAIIntegration()], +}); +``` -This integration is enabled by default and automatically captures spans for Google Gen AI SDK calls (requires Sentry SDK version `10.28.0` or higher). +## Supported Operations -To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. +By default, tracing support is added to the following Google Gen AI SDK calls: -## Configuration +- `models.generateContent()` - Generate content with a given model +- `models.generateContentStream()` - Stream content generation with a given model +- `models.embedContent()` - Generate embeddings with a given model +- `chats.create()` - Create chat sessions +- `sendMessage()` - Send messages in chat sessions +- `sendMessageStream()` - Stream messages in chat sessions -### Options +Streaming and non-streaming requests are automatically detected and handled appropriately. -The following options control what data is captured from Google Gen AI SDK calls: +## Supported Versions -#### `recordInputs` +- `@google/genai`: `>=0.10.0 <3` + +## Options + +### `recordInputs` _Type: `boolean` (optional)_ @@ -28,7 +56,7 @@ Records inputs to Google Gen AI SDK calls (such as prompts and messages). Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. -#### `recordOutputs` +### `recordOutputs` _Type: `boolean` (optional)_ @@ -36,33 +64,15 @@ Records outputs from Google Gen AI SDK calls (such as generated text and respons Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. -**Usage** - ```javascript Sentry.init({ - dsn: "____PUBLIC_DSN____", - // Tracing must be enabled for agent tracing to work + dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, integrations: [ Sentry.googleGenAIIntegration({ - // your options here + recordInputs: true, + recordOutputs: true, }), ], }); ``` - -## Supported Operations - -By default, tracing support is added to the following Google Gen AI SDK calls: - -- `models.generateContent()` - Generate content with a given model -- `models.generateContentStream()` - Stream content generation with a given model -- `chats.create()` - Create chat sessions -- `sendMessage()` - Send messages in chat sessions -- `sendMessageStream()` - Stream messages in chat sessions - -Streaming and non-streaming requests are automatically detected and handled appropriately. - -## Supported Versions - -- `@google/genai`: `>=0.10.0 <2` diff --git a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx index 61dd3b73cc9fc..8c4bb846575c0 100644 --- a/docs/platforms/javascript/common/configuration/integrations/graphql.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/graphql.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -69,10 +68,10 @@ When a resolver function is not defined on the schema for a field, GraphQL will _Type: `boolean`_ -By default, this option is `true`. +By default, this option is `true`. When enabled, it records GraphQL operations on the enclosing root span in the `sentry.graphql.operation` attribute. Its effect on the root span name depends on the tracing mode: -With this setting enabled, the GraphQL instrumentation dynamically updates the name of the `http.server` root span by appending -the operation names. Instead of generic span names like `POST /graphql`, span names will be more descriptive, such as `POST /graphql (query MyQuery)`. -For requests containing multiple operations, the span names will aggregate operation names, for example `POST /graphql (query Query1, query Query2)` +- In streaming mode, the root span name stays unchanged. Set the option to `false` to skip adding `sentry.graphql.operation` to the root span. -Set the option to `false` to preserve the default `http.server` span name without this additional context. +- In static mode, with `traceLifecycle: "static"`, enabling this option also appends operation names to the `http.server` root span name. For example, `POST /graphql` becomes `POST /graphql (query MyQuery)`. Requests containing multiple operations include each operation name, such as `POST /graphql (query Query1, query Query2)`. Set the option to `false` to skip the root span attribute and preserve the original root span name. + +In both modes, the GraphQL span records `graphql.operation.name` and `graphql.operation.type` when available, regardless of this option. diff --git a/docs/platforms/javascript/common/configuration/integrations/groq.mdx b/docs/platforms/javascript/common/configuration/integrations/groq.mdx new file mode 100644 index 0000000000000..b6a142dab30bd --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/groq.mdx @@ -0,0 +1,74 @@ +--- +title: Groq +description: "Adds instrumentation for the Groq SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.groqIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `groqIntegration` adds instrumentation for the [`groq-sdk`](https://www.npmjs.com/package/groq-sdk) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. Groq speaks the OpenAI wire format, so it reuses the same span and streaming logic as the OpenAI integration. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.groqIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Groq SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `embeddings.create()` - Embedding requests + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `groq-sdk`: `>=0.3.0 <2` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Groq SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Groq SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.groqIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/http.mdx b/docs/platforms/javascript/common/configuration/integrations/http.mdx index c3666472ad12d..5c6fde57a8957 100644 --- a/docs/platforms/javascript/common/configuration/integrations/http.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/http.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -37,10 +36,11 @@ _Import name: `Sentry.httpIntegration`_ This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). -The `httpIntegration` does two things: +The `httpIntegration` does the following: 1. It captures breadcrumbs for HTTP requests. -2. It captures spans for outgoing HTTP requests. +2. It captures spans for incoming and outgoing HTTP requests. +3. It creates sessions for incoming requests to track [Release Health](/product/releases/health/). ```JavaScript Sentry.init({ @@ -58,11 +58,11 @@ If set to false, no breadcrumbs will be captured. ### `spans` -_Type: `boolean`_ (Defaults to `false`) +_Type: `boolean`_ (Defaults to `true` when tracing is enabled) -If set to true, spans will be created for outgoing HTTP requests. +If set to false, no spans will be created for HTTP requests, neither for incoming nor for outgoing ones. -### `maxIncomingRequestBodySize` +### `maxRequestBodySize` _Type: `'none' | 'small' | 'medium' | 'always'`_ (Defaults to `'medium'`) @@ -77,7 +77,7 @@ Available options: Note that even with the `'always'` setting, bodies exceeding 1 MB will never be attached for performance and security reasons. -### `ignoreIncomingRequestBody` +### `ignoreRequestBody` _Type: `(url: string, request: RequestOptions) => boolean`_ @@ -93,13 +93,13 @@ The callback function receives two arguments: _Type: `boolean`_ (Defaults to `true`) -Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing HTTP requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). This is useful when `skipOpenTelemetrySetup: true` is configured and your external OpenTelemetry setup already handles trace propagation, to avoid duplicate headers. +Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing HTTP requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). With `openTelemetryIntegration()` enabled and Sentry tracing off, your OpenTelemetry propagator already handles outgoing trace propagation. ### `ignoreOutgoingRequests` _Type: `(url: string, request: RequestOptions) => boolean`_ -Allows you to define a method to filter out outgoing requests based on the URL. If the method returns `true`, no spans or breadcrumbs will be captured for the outgoing request. +Allows you to define a method to filter out outgoing requests based on the URL. If the method returns `true`, the request is skipped entirely: no span or breadcrumb is captured, and no trace propagation headers are injected. The callback function receives two arguments: @@ -129,17 +129,23 @@ _Type: `boolean`_ If set to true, no spans will be generated for incoming requests. -### `dropSpansForIncomingRequestStatusCodes` +### `ignoreStatusCodes` _Type: `(number | [number, number])[]`_ (Defaults to `[[401, 404], [301, 303], [305, 399]]`) + + +This option is deprecated and will be removed in the next major version without a replacement. It only has an effect when `traceLifecycle` is set to `'static'`. With span streaming, child spans are sent as they end, before the response status code is known, so spans can't be dropped based on the status code. To keep requests out of Sentry, use [`ignoreIncomingRequests`](#ignoreincomingrequests), `tracesSampler`, or `ignoreSpans` instead. + + + Do not capture spans for incoming HTTP requests with the given status codes. By default, spans with some 3xx and 4xx status codes are ignored. Expects an array that can contain individual status codes (numbers) or ranges (2-element arrays of `[start, end]` where both start and end are inclusive). For example, `[[300, 399], 404]` would ignore all 3xx status codes (300-399 inclusive) and 404 status codes. -### `trackIncomingRequestsAsSessions` +### `sessions` _Type: `boolean`_ (Defaults to `true`) @@ -152,19 +158,42 @@ _Type: `number`_ (Defaults to `60000`) The delay in milliseconds before sessions are flushed as a session aggregate. This controls how frequently session data is sent to Sentry. -### `instrumentation` +### `onSpanCreated` + +_Type: `(span: Span, request: IncomingMessage, response: ServerResponse) => void`_ -You can also pass some hooks through to the [underlying OpenTelemetry Instrumentation](https://www.npmjs.com/package/@opentelemetry/instrumentation-http): +A hook that's called after a span is created for an incoming request, before it's recorded. Use this to add custom attributes to incoming request spans. -```typescript -httpIntegration({ - instrumentation?: { - requestHook?: (span: Span, req: ClientRequest | HTTPModuleRequestIncomingMessage) => void; - responseHook?: (span: Span, response: HTTPModuleRequestIncomingMessage | ServerResponse) => void; - applyCustomAttributesOnSpan?: ( - span: Span, - request: ClientRequest | HTTPModuleRequestIncomingMessage, - response: HTTPModuleRequestIncomingMessage | ServerResponse, - ) => void; +```javascript +Sentry.httpIntegration({ + onSpanCreated: (span, request, response) => { + span.setAttribute("custom", true); + }, }); ``` + +### `outgoingRequestHook` + +_Type: `(span: Span, request: ClientRequest) => void`_ + +A hook that's called after a span is created for an outgoing request. Use this to add custom attributes to outgoing request spans. Only called when spans are created for outgoing requests. + +```javascript +Sentry.httpIntegration({ + outgoingRequestHook: (span, request) => { + span.setAttribute("custom", true); + }, +}); +``` + +### `outgoingResponseHook` + +_Type: `(span: Span, response: IncomingMessage) => void`_ + +A hook that's called when an outgoing request receives a response. Only called when spans are created for outgoing requests. + +### `outgoingRequestApplyCustomAttributes` + +_Type: `(span: Span, request: ClientRequest, response: IncomingMessage) => void`_ + +A hook that's called when both the outgoing request and its response are available. Only called when spans are created for outgoing requests. diff --git a/docs/platforms/javascript/common/configuration/integrations/index.mdx b/docs/platforms/javascript/common/configuration/integrations/index.mdx index cfedf1d887d79..171c31599897b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/index.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/index.mdx @@ -18,19 +18,44 @@ Integrations automatically add error instrumentation, performance instrumentatio To disable system integrations, set `defaultIntegrations: false` when calling `init()`. -To override their settings, provide a new instance with your config to the `integrations` option. For example, to turn off browser capturing console calls: +To override their settings, provide a new instance with your config to the `integrations` option. + + + +For example, to stop capturing click and keypress events as breadcrumbs: ```javascript {3-7} Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ Sentry.breadcrumbsIntegration({ - console: false, + dom: false, }), ], }); ``` + + + + + +For example, to stop recording breadcrumbs for outgoing HTTP requests: + +```javascript {3-7} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + Sentry.httpIntegration({ + breadcrumbs: false, + }), + ], +}); +``` + + + + ## Adding an Integration You can add additional integrations in your `init` call: @@ -85,6 +110,8 @@ Lazy loading is available for the following integrations: - `reportingObserverIntegration` - `rewriteFramesIntegration` - `browserProfilingIntegration` +- `userTimingIntegration` +- `interactionsIntegration` diff --git a/docs/platforms/javascript/common/configuration/integrations/interactions.mdx b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx new file mode 100644 index 0000000000000..9fcc5a9ce4544 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/interactions.mdx @@ -0,0 +1,77 @@ +--- +title: Interactions +description: "Capture clicks and the work they trigger as browser spans." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.interactionsIntegration`_ + +The Interactions integration captures clicks and the work they trigger as spans. Use it with BrowserTracing or your framework's routing integration to associate interactions with the current route. + + + +This integration is experimental and can generate a large number of spans. + + + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.interactionsIntegration(), + ], +}); +``` + +Clicks outside an active pageload or navigation start an interaction span. Requests and other spans started during the interaction become its children. The integration also captures individual clicks. + +INP is collected by the WebVitals integration and does not require this integration. + +## Configuration Options + +These timeouts apply to interaction spans, independently of BrowserTracing's pageload and navigation timeouts. + + + +Time in milliseconds to wait before finishing an interaction span when no unfinished child spans remain. + + + + + +Maximum duration of an interaction span in milliseconds, including time spent waiting for child spans. + + + + + +Maximum time in milliseconds a child span can run before the interaction span finishes. + + diff --git a/docs/platforms/javascript/common/configuration/integrations/kafka.mdx b/docs/platforms/javascript/common/configuration/integrations/kafka.mdx index aa048fc9c1a25..590184741ae4e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/kafka.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/kafka.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/knex.mdx b/docs/platforms/javascript/common/configuration/integrations/knex.mdx index 0cdb4eae51065..2febe5759e235 100644 --- a/docs/platforms/javascript/common/configuration/integrations/knex.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/knex.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/agent-tracing/langchain.mdx b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx similarity index 67% rename from docs/platforms/javascript/common/agent-tracing/langchain.mdx rename to docs/platforms/javascript/common/configuration/integrations/langchain.mdx index 604862dc704bd..9f78f6939b8b2 100644 --- a/docs/platforms/javascript/common/agent-tracing/langchain.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/langchain.mdx @@ -1,92 +1,60 @@ --- title: LangChain -description: "Adds instrumentation for LangChain." -sidebar_order: 24 +description: "Adds instrumentation for LangChain. (default)" supportedCategories: - server + - serverless +notSupported: + - javascript.mastra --- -_Import name: `Sentry.langChainIntegration`_ - -The `langChainIntegration` adds instrumentation for [`langchain`](https://www.npmjs.com/package/langchain) to capture spans by automatically wrapping LangChain operations and recording agent interactions with configurable input/output recording. - -This integration is enabled by default and automatically captures spans for LangChain SDK calls (requires Sentry SDK version `10.28.0` or higher). - -To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section. + -## Configuration +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. -### Options - -The following options control what data is captured from LangChain operations: - -#### `recordInputs` - -_Type: `boolean` (optional)_ - -Records inputs to LangChain operations (such as prompts and messages). - -Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. - -#### `recordOutputs` - -_Type: `boolean` (optional)_ + -Records outputs from LangChain operations (such as generated text and responses). +_Import name: `Sentry.langChainIntegration`_ -Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). -**Usage** +The `langChainIntegration` adds instrumentation for [`langchain`](https://www.npmjs.com/package/langchain) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. ```javascript Sentry.init({ - dsn: "____PUBLIC_DSN____", + dsn: "___PUBLIC_DSN___", // Tracing must be enabled for agent tracing to work tracesSampleRate: 1.0, - integrations: [ - Sentry.langChainIntegration({ - // your options here - }), - ], + integrations: [Sentry.langChainIntegration()], }); ``` ## Supported Operations -By default, tracing support is added to the following LangChain SDK calls: +By default, tracing support is added to the following LangChain operations: - **Chat model invocations** - Captures spans for chat model calls - **LLM invocations** - Captures spans for LLM pipeline executions - **Chain executions** - Captures spans for chain invocations - **Tool executions** - Captures spans for tool calls -### Runnables - -The integration automatically instruments the following LangChain runnable methods: - -- `invoke()` - Single execution -- `stream()` - Streaming execution -- `batch()` - Batch execution - -### Embeddings - -The integration captures `gen_ai.embeddings` spans for `embedQuery()` and `embedDocuments()` calls from these provider packages: +The integration automatically instruments the `invoke()`, `stream()`, and `batch()` runnable methods, across the following LangChain provider packages: +- `@langchain/anthropic` - `@langchain/openai` - `@langchain/google-genai` - `@langchain/mistralai` - `@langchain/google-vertexai` +- `@langchain/groq` -### Providers +### Embeddings -The automatic instrumentation supports the following LangChain provider packages: +The integration captures `gen_ai.embeddings` spans for `embedQuery()` and `embedDocuments()` calls from these provider packages: -- `@langchain/anthropic` - `@langchain/openai` - `@langchain/google-genai` - `@langchain/mistralai` - `@langchain/google-vertexai` -- `@langchain/groq` ## Supported Versions @@ -102,3 +70,34 @@ Automatic embeddings instrumentation supports these package versions: | `@langchain/google-common` | `>=0.1.0 <3.0.0` | For `@langchain/google-vertexai`, the version requirement applies to its `@langchain/google-common` dependency, which implements the embedding methods. + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to LangChain operations (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from LangChain operations (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.langChainIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx new file mode 100644 index 0000000000000..00c486398502a --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/langgraph.mdx @@ -0,0 +1,144 @@ +--- +title: LangGraph +description: "Adds instrumentation for the LangGraph SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.langGraphIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `langGraphIntegration` adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.langGraphIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following LangGraph operations: + +- **Agent Creation** (`gen_ai.create_agent`) - Captures spans when compiling a StateGraph into an executable agent +- **Agent Invocation** (`gen_ai.invoke_agent`) - Captures spans for agent execution via `invoke()` + +## Supported Versions + +- `@langchain/langgraph`: `>=0.2.0 <2.0.0` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to LangGraph operations (such as messages and state data passed to the graph). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from LangGraph operations (such as generated responses, agent outputs, and final state). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.langGraphIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` + +## Manual Instrumentation + +_Import names: `Sentry.instrumentStateGraph`, `Sentry.instrumentCreateReactAgent`_ + +If your application does not use automatic instrumentation, wrap your agent after setting up Sentry. Two helpers are available, depending on how you build your agent: + +- **`instrumentStateGraph`**: for graphs you build yourself with `StateGraph`. Call it on the graph **before** calling `.compile()`. +- **`instrumentCreateReactAgent`**: for LangGraph's prebuilt `createReactAgent`. Wrap the factory, then use the wrapped version exactly like `createReactAgent`. This also captures the model and wraps tools, so you get `execute_tool` spans as well. + +Both accept the same `recordInputs` and `recordOutputs` options as the integration. + +Instrumenting a `StateGraph`: + +```javascript +import { ChatOpenAI } from "@langchain/openai"; +import { + StateGraph, + MessagesAnnotation, + START, + END, +} from "@langchain/langgraph"; +import { SystemMessage, HumanMessage } from "@langchain/core/messages"; + +// Create LLM call +const llm = new ChatOpenAI({ + modelName: "gpt-4o", + apiKey: "your-api-key", +}); + +async function callLLM(state) { + const response = await llm.invoke(state.messages); + + return { + messages: [...state.messages, response], + }; +} + +// Create the agent +const agent = new StateGraph(MessagesAnnotation) + .addNode("agent", callLLM) + .addEdge(START, "agent") + .addEdge("agent", END); + +// Instrument the graph before compiling +Sentry.instrumentStateGraph(agent, { + recordInputs: true, + recordOutputs: true, +}); + +const graph = agent.compile({ name: "my_agent" }); + +// Invoke the agent +const result = await graph.invoke({ + messages: [ + new SystemMessage("You are a helpful assistant."), + new HumanMessage("Hello!"), + ], +}); +``` + +Instrumenting a prebuilt `createReactAgent`: + +```javascript +import { createReactAgent } from "@langchain/langgraph/prebuilt"; + +// Instrument createReactAgent, then use the wrapped version in its place +const instrumentedCreateReactAgent = + Sentry.instrumentCreateReactAgent(createReactAgent); + +const agent = instrumentedCreateReactAgent({ llm, tools }); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx index ff7f83c571988..99c27546e3af7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/localvariables.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx b/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx index bc87ce11fc413..a801949e4b7a4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/lrumemoizer.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/mistral.mdx b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx new file mode 100644 index 0000000000000..8e3a2dfacf12c --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/mistral.mdx @@ -0,0 +1,177 @@ +--- +title: Mistral AI +description: "Adds instrumentation for the Mistral AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.mistralAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `mistralAIIntegration` adds instrumentation for the [`@mistralai/mistralai`](https://www.npmjs.com/package/@mistralai/mistralai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.mistralAIIntegration()], +}); +``` + + + +On Deno, preload Sentry's import hook so the Mistral SDK can be instrumented: + +```bash +deno run --allow-net --allow-env --allow-read --allow-sys --allow-write --preload=npm:@sentry/deno/import app.ts +``` + + + + + + + +With the Node.js adapter, no build step is needed. The integration is enabled by default when tracing is enabled. + +On Bun, add `sentryBunPlugin()` to your build so the plugin can instrument the bundled Mistral SDK: + + + + + +On Bun, add `sentryBunPlugin()` to your build so the plugin can instrument the bundled Mistral SDK: + + + +```typescript {filename:build.ts} +import { sentryBunPlugin } from "@sentry/bun/plugin"; + +await Bun.build({ + entrypoints: ["./src/index.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], +}); +``` + +The Mistral SDK must be part of the bundle. The plugin only runs during a build, so for unbundled applications started with `bun run`, use [Manual Instrumentation](#manual-instrumentation). + + + + + +On Cloudflare, add `sentryCloudflareVitePlugin()` alongside Cloudflare's Vite plugin so the bundled Mistral SDK is instrumented: + +```typescript {filename:vite.config.mts} +import { cloudflare } from "@cloudflare/vite-plugin"; +import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [cloudflare(), sentryCloudflareVitePlugin()], +}); +``` + +Build-time instrumentation is enabled by default, and the plugin registers the integration in both `vite dev` and `vite build`. Keep the `nodejs_compat` flag enabled in your Wrangler configuration, and see the Vite plugin page for the full setup. Without the plugin, or with `buildTimeInstrumentation: false`, use [Manual Instrumentation](#manual-instrumentation). + + + +## Supported Operations + +By default, tracing support is added to the following Mistral AI SDK calls: + +- `chat.complete()` / `chat.parse()` - Chat completion requests +- `chat.stream()` / `chat.parseStream()` - Streaming chat completions +- `embeddings.create()` - Embedding requests +- `agents.complete()` - Agent completion requests +- `agents.stream()` - Streaming agent completions + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `@mistralai/mistralai`: `>=2.0.0 <3` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Mistral AI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Mistral AI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.mistralAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` + + + +## Manual Instrumentation + +_Import name: `Sentry.instrumentMistralAiClient`_ + +If your application does not use automatic instrumentation, wrap your Mistral client after setting up Sentry. Use the returned client for all Mistral calls. + + + +Import Sentry from the entry point for your runtime: `@sentry/hono/node`, `@sentry/hono/bun`, or `@sentry/hono/cloudflare`. + + + + + +```javascript +import * as Sentry from "___SDK_PACKAGE___"; +``` + + + +```javascript +import { Mistral } from "@mistralai/mistralai"; + +const mistral = new Mistral({ apiKey: "your-mistral-api-key" }); +const client = Sentry.instrumentMistralAiClient(mistral, { + recordInputs: false, + recordOutputs: false, +}); + +const response = await client.chat.complete({ + model: "mistral-small-latest", + messages: [{ role: "user", content: "Hello!" }], +}); +``` + +Use one instrumentation approach for each client. If automatic instrumentation is already active, you don't need to wrap the client. + + diff --git a/docs/platforms/javascript/common/configuration/integrations/mongo.mdx b/docs/platforms/javascript/common/configuration/integrations/mongo.mdx index 4f5b313332c7b..a1bc795ce82e4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mongo.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mongo.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx b/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx index 8f459e2fbebe4..dead732266b41 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mongoose.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mysql.mdx b/docs/platforms/javascript/common/configuration/integrations/mysql.mdx index cf22d747a0c6d..0bc57a91339a4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mysql.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mysql.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx b/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx index 4484cec1d5ee0..53423805a9ca4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/mysql2.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx b/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx index 220f09a3aabf7..8493b9219093b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodecontext.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx index e18f6fea19c0b..4044765c25c7e 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodefetch.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -61,7 +60,7 @@ If set to false, no breadcrumbs will be captured. _Type: `boolean`_ (Defaults to `true`) -Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing fetch requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). This is useful when `skipOpenTelemetrySetup: true` is configured and your external OpenTelemetry setup already handles trace propagation, to avoid duplicate headers. +Whether to inject trace propagation headers (`sentry-trace`, `baggage`, `traceparent`) into outgoing fetch requests. When set to `false`, Sentry will not inject any trace propagation headers but will still create breadcrumbs (if `breadcrumbs` is enabled). With `openTelemetryIntegration()` enabled and Sentry tracing off, your OpenTelemetry propagator already handles outgoing trace propagation. ### `ignoreOutgoingRequests` diff --git a/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx b/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx index 8b1d4ab7b8b1e..7d96d68d36db4 100644 --- a/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/nodeprofiling.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx index bc90666643df9..e0a2edd1a253a 100644 --- a/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/noderuntimemetrics.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/openai.mdx b/docs/platforms/javascript/common/configuration/integrations/openai.mdx new file mode 100644 index 0000000000000..0bc82bae2c996 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/openai.mdx @@ -0,0 +1,76 @@ +--- +title: OpenAI +description: "Adds instrumentation for the OpenAI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.openAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmjs.com/package/openai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.openAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following OpenAI SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `responses.create()` - Response SDK requests +- `embeddings.create()` - Generate embeddings +- `conversations.create()` - Create conversations + +Streaming and non-streaming requests are automatically detected and handled appropriately. `chat.completions.create()` and `responses.create()` produce the same span type: op `gen_ai.chat`, name like `chat `. + +## Supported Versions + +- `openai`: `>=4.0.0 <8` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to OpenAI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from OpenAI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.openAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx new file mode 100644 index 0000000000000..fd65c00bb5012 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/opentelemetry.mdx @@ -0,0 +1,95 @@ +--- +title: OpenTelemetry +description: "Connect Sentry to an OpenTelemetry setup that owns tracing." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +--- + + + +_Import name: `Sentry.openTelemetryIntegration`_ + +This integration is not enabled by default. Use it when OpenTelemetry owns tracing in your application and you want Sentry's errors, logs, metrics, and check-ins to land on the same traces. + +Everything Sentry sends that carries trace information is attached to the OpenTelemetry span that's active when it happens, so it shows up on the same trace as the spans your OpenTelemetry SDK exports. Outgoing request propagation is left to your OpenTelemetry propagator. + +An active Sentry span still takes precedence, so this only changes what happens when Sentry has no span of its own. If there is no active OpenTelemetry span, or its span context is invalid, Sentry uses its own trace context. + + + +This integration sends no spans. To get your OpenTelemetry spans into Sentry, point your own exporter at Sentry's OTLP endpoint with `getOtlpTracesEndpoint()`, as shown below. + + + +## Configure + +This integration runs on the server and takes no options. Leave Sentry tracing off so the two pipelines stay separate. `getOtlpTracesEndpoint()` turns your DSN into the URL and authentication headers of Sentry's OTLP endpoint: + +```javascript {filename: instrument.mjs} +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; +import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; +import * as Sentry from "___SDK_PACKAGE___"; + +const dsn = "___PUBLIC_DSN___"; +const endpoint = Sentry.getOtlpTracesEndpoint(dsn); + +if (!endpoint) { + throw new Error("Could not parse the Sentry DSN"); +} + +const provider = new NodeTracerProvider({ + spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter(endpoint))], +}); + +provider.register(); + +Sentry.init({ + dsn, + // Leave the OpenTelemetry setup to your own provider. + enableOpenTelemetrySetup: false, + // Leave tracesSampleRate and tracesSampler unset. OpenTelemetry owns spans. + integrations: [Sentry.openTelemetryIntegration()], +}); +``` + +If you already have a provider, add the exporter to that provider instead of registering a second one. Initialize OpenTelemetry before calling `Sentry.init()`. In frameworks with their own instrumentation entry point, initialize both there in that order. + +Set `enableOpenTelemetrySetup: false`. Leave `tracesSampleRate` and `tracesSampler` unset to keep Sentry tracing off. + +For sampling guidance, see the OpenTelemetry setup guide. + +## `getOtlpTracesEndpoint` + +`Sentry.getOtlpTracesEndpoint(dsn)` converts a Sentry DSN into configuration for an OpenTelemetry HTTP trace exporter. It takes a DSN string and returns an object with these fields: + +| Field | Type | Description | +| --------- | ------------------------ | ------------------------------------------------------------------- | +| `url` | `string` | The project's Sentry OTLP traces endpoint. | +| `headers` | `Record` | Authentication headers for the endpoint, including `X-Sentry-Auth`. | + +If the helper cannot parse the DSN, it returns `undefined`. The helper does not register a provider or send spans. + +Pass the result to `OTLPTraceExporter` and add it to your provider with a `BatchSpanProcessor`, as shown in the [configuration example](#configure). If you only want to associate Sentry errors with traces exported elsewhere, keep your existing exporter and omit this helper. diff --git a/docs/platforms/javascript/common/configuration/integrations/pino.mdx b/docs/platforms/javascript/common/configuration/integrations/pino.mdx index 2fc6e9da2a295..d5c02ef49140d 100644 --- a/docs/platforms/javascript/common/configuration/integrations/pino.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/pino.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/postgres.mdx b/docs/platforms/javascript/common/configuration/integrations/postgres.mdx index 9f6e47b0daedd..b6cef3a7e7a74 100644 --- a/docs/platforms/javascript/common/configuration/integrations/postgres.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/postgres.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx index 2c4236eea6161..e7d6d411d11c0 100644 --- a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx b/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx index 0f300c55cbf0e..118be82e733c1 100644 --- a/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/prisma__v8.x.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/redis.mdx b/docs/platforms/javascript/common/configuration/integrations/redis.mdx index 168b28a253474..b888ac2984891 100644 --- a/docs/platforms/javascript/common/configuration/integrations/redis.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/redis.mdx @@ -7,7 +7,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx b/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx index b689165dd9b12..716351b8039b7 100644 --- a/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/requestdata.mdx @@ -25,7 +25,7 @@ This integration adds data from incoming requests to transaction and error event -The `include` option will likely be removed in a future SDK version. Use the `dataCollection` option instead. +The `include` option will likely be removed in a future SDK version. Use the `dataCollection` option instead. diff --git a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx index cf1db184ade2c..7b4872928a670 100644 --- a/docs/platforms/javascript/common/configuration/integrations/supabase.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/supabase.mdx @@ -16,22 +16,19 @@ The `supabaseIntegration` adds instrumentation for the Supabase client to captur You need to have both the Sentry SDK and the Supabase library installed. For Supabase installation instructions, refer to the [Supabase JavaScript documentation](https://supabase.com/docs/reference/javascript/introduction). - ## Configuration This is the preferred method for most use cases and follows Sentry's standard integration pattern. ```javascript import * as Sentry from "___SDK_PACKAGE___"; -import { createClient } from '@supabase/supabase-js'; +import { createClient } from "@supabase/supabase-js"; -const supabaseClient = createClient('YOUR_SUPABASE_URL', 'YOUR_SUPABASE_KEY'); +const supabaseClient = createClient("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY"); Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [ - Sentry.supabaseIntegration({ supabaseClient }) - ], + integrations: [Sentry.supabaseIntegration({ supabaseClient })], tracesSampleRate: 1.0, }); ``` @@ -43,6 +40,7 @@ The integration provides comprehensive monitoring for both authentication and da ### Authentication Spans The integration automatically instruments the following auth operations: + - `signInWithPassword` - `signOut` - `signInAnonymously` @@ -55,6 +53,7 @@ The integration automatically instruments the following auth operations: - `reauthenticate` Admin operations are also instrumented: + - `createUser` - `deleteUser` - `listUsers` @@ -70,7 +69,7 @@ These spans are used to populate Sentry's [pre-built Query Dashboards](/product/ - `db.schema`: The database schema - `db.url`: The Supabase instance URL - `db.sdk`: Client information -- `db.system`: Set to 'postgresql' +- `db.system.name`: Set to 'postgresql' - `db.query`: The query parameters - `db.body`: The request body (for mutations) @@ -78,15 +77,14 @@ These spans are used to populate Sentry's [pre-built Query Dashboards](/product/ Coming soon, the Sentry SDK will also support generating spans for interactions with Supabase queues. For more information, please follow [this GitHub issue](https://github.com/getsentry/sentry-javascript/issues/14611). - ## Error Tracking The integration automatically: + - Captures errors from failed operations - Adds breadcrumbs for database operations - Includes detailed context about the operation that failed - ## Supported Versions - `@supabase/supabase-js`: `>=2.0.0` diff --git a/docs/platforms/javascript/common/configuration/integrations/tedious.mdx b/docs/platforms/javascript/common/configuration/integrations/tedious.mdx index d2b70c6fa8208..d755e4380b25b 100644 --- a/docs/platforms/javascript/common/configuration/integrations/tedious.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/tedious.mdx @@ -8,7 +8,6 @@ supported: - javascript.astro - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.deno - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx new file mode 100644 index 0000000000000..bd1a7636baf1c --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/together-ai.mdx @@ -0,0 +1,74 @@ +--- +title: Together AI +description: "Adds instrumentation for the Together AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. + + + +_Import name: `Sentry.togetherAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `togetherAIIntegration` adds instrumentation for the [`together-ai`](https://www.npmjs.com/package/together-ai) SDK to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. Together AI speaks the OpenAI wire format, so it reuses the same span and streaming logic as the OpenAI integration. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.togetherAIIntegration()], +}); +``` + +## Supported Operations + +By default, tracing support is added to the following Together AI SDK calls: + +- `chat.completions.create()` - Chat completion requests +- `embeddings.create()` - Embedding requests + +Streaming and non-streaming requests are automatically detected and handled appropriately. + +## Supported Versions + +- `together-ai`: `>=0.6.0 <1` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to Together AI SDK calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from Together AI SDK calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.togetherAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx new file mode 100644 index 0000000000000..5461ea644b4c7 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/usertiming.mdx @@ -0,0 +1,61 @@ +--- +title: UserTiming +description: "Capture performance.mark() and performance.measure() entries as browser spans." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 11 or later. + + + +_Import name: `Sentry.userTimingIntegration`_ + +The UserTiming integration captures `performance.mark()` and `performance.measure()` entries as spans. Use it with BrowserTracing or your framework's routing integration. Timing entries are added to pageload and navigation spans when those spans end. + +Before SDK version 11, BrowserTracing captured these entries automatically, without a separate integration. + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.userTimingIntegration(), + ], +}); +``` + +## Configuration Options + + + +Skip timing entries whose names match any string or regular expression in this array. Use this to exclude measurements from third-party code. + +```javascript +Sentry.userTimingIntegration({ + ignore: ["third-party-mark", /^framework-/], +}); +``` + + diff --git a/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx new file mode 100644 index 0000000000000..46395ea603f29 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/vercelai.mdx @@ -0,0 +1,95 @@ +--- +title: Vercel AI +description: "Adds instrumentation for the Vercel AI SDK. (default)" +supportedCategories: + - server + - serverless +notSupported: + - javascript.mastra +--- + + + +Requires SDK version `11.0.0` or higher. On earlier versions, see the [Agent Tracing](/platforms/javascript/agent-tracing/) setup for your SDK. + + + +_Import name: `Sentry.vercelAIIntegration`_ + +This integration is enabled by default when tracing is enabled. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). + +The `vercelAIIntegration` adds instrumentation for the [`ai`](https://www.npmjs.com/package/ai) SDK by Vercel to capture agent tracing `gen_ai` spans, recording model, token usage, latency, and (when enabled) inputs and outputs. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Tracing must be enabled for agent tracing to work + tracesSampleRate: 1.0, + integrations: [Sentry.vercelAIIntegration()], +}); +``` + + + + + +The Edge runtime isn't instrumented. The instrumentation relies on diagnostics channels, which Edge doesn't support. `@sentry/nextjs` still exports `vercelAIIntegration` from its Edge build so imports resolve, but it captures no spans. Run AI calls in the Node runtime. + + + + + + + +Don't use the AI SDK's `registerTelemetry` API (AI SDK v7 and above) together with this integration. `vercelAIIntegration` already instruments the AI SDK, so registering telemetry separately produces duplicate spans. + + + +## Supported Operations + +By default, tracing support is added to the following `ai` functions: + +- `generateText()` +- `streamText()` +- `generateObject()` +- `streamObject()` +- `embed()` +- `embedMany()` +- `rerank()` + +Plus `generate()` and `stream()` on [`ToolLoopAgent`](https://ai-sdk.dev/docs/agents/overview#toolloopagent-class). + +## Supported Versions + +- `ai`: `>=3.0.0 <=7` + +## Options + +### `recordInputs` + +_Type: `boolean` (optional)_ + +Records inputs to `ai` function calls (such as prompts and messages). + +Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +### `recordOutputs` + +_Type: `boolean` (optional)_ + +Records outputs from `ai` function calls (such as generated text and responses). + +Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`. + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + Sentry.vercelAIIntegration({ + recordInputs: true, + recordOutputs: true, + }), + ], +}); +``` diff --git a/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx new file mode 100644 index 0000000000000..815577c35500e --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/webvitals.mdx @@ -0,0 +1,87 @@ +--- +title: WebVitals +description: "Configure browser Web Vitals collection, including INP, LCP, and CLS." +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.electron + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nitro + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun + - javascript.effect + - javascript.elysia + - javascript.firebase + - javascript.mastra +--- + + + +This integration only works inside a browser environment. Requires JavaScript SDK version 10.57.0 or later. + + + +_Import name: `Sentry.webVitalsIntegration`_ + +The WebVitals integration captures LCP, CLS, and INP for the [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/). + + + BrowserTracing + +adds this integration automatically. In SDK version 11 and later, configure it through BrowserTracing's +`webVitals` option: + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + webVitals: { + ignore: ["inp"], + }, + }), + ], +}); +``` + +To configure it in SDK versions before 11, add `Sentry.webVitalsIntegration({ ... })` directly to `integrations`: + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.webVitalsIntegration({ ignore: ["inp"] }), + ], +}); +``` + +You can also use this approach in SDK version 11 and later. An explicitly added WebVitals integration takes precedence over BrowserTracing's Web Vitals settings. + +## Configuration Options + + + +Web Vitals to skip. By default, all supported Web Vitals are collected. + + + + + +Collect LCP, CLS, and INP for each soft navigation detected by the browser's Soft Navigations API. Requires stream mode and a browser that supports this API. Set to `false` to collect one set of vitals for the page lifetime. + + + + + +Collect LCP, CLS, and INP when a page is restored from the back/forward cache. Requires stream mode and BrowserTracing with `instrumentBfcacheRestore` enabled. Set to `false` to disable Web Vitals collection for restores. + + diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx index 0cc649fc82b9f..b8ec0ae52f01b 100644 --- a/docs/platforms/javascript/common/configuration/options.mdx +++ b/docs/platforms/javascript/common/configuration/options.mdx @@ -103,47 +103,15 @@ Set to `false` to opt out, for example, when using a custom `tunnel` or when run - - - - `sendDefaultPii` is deprecated and will be removed in the next major version - (v11). Use [`dataCollection`](#dataCollection) instead. - - -Set this option to `true` to send default PII data to Sentry. Among other things, enabling this will enable automatic IP address collection on events. - -For backwards compatibility, `sendDefaultPii: true` behaves like enabling all [`dataCollection`](#dataCollection) categories. -If both options are set, `dataCollection` takes precedence. - - - Passing [`dataCollection`](#dataCollection) opts you into the more permissive `dataCollection` defaults. To preserve the old `sendDefaultPii: false` behavior while using `dataCollection`, opt out of each category explicitly: - -```javascript -Sentry.init({ - dataCollection: { - userInfo: false, - graphQL: { document: false, variables: false }, - genAI: { inputs: false, outputs: false }, - databaseQueryData: false, - queues: false, - httpBodies: [], - httpHeaders: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - cookies: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - urlQueryParams: { deny: ["forwarded", "-ip", "remote-", "via", "-user"] }, - }, -}); -``` - -Data you set explicitly (for example, via `Sentry.setUser()`) is always sent, regardless of `dataCollection`. - - - - Controls which categories of data the SDK collects automatically. All fields are optional. By default the SDK collects rich debugging context (including user identity, request/response bodies, and generative AI content) and scrubs values whose keys match the built-in sensitive denylist (`auth`, `token`, `password`, and similar). +In version 10 of the SDK, the defaults below apply only when you set the `dataCollection` option. +Without it, the deprecated `sendDefaultPii` option controls data collection. +Starting with version 11, the defaults always apply. + For more on what data Sentry collects and how to control it, see Data Management. | Key | Type | Default | Description | @@ -190,7 +158,7 @@ This variable controls the total amount of breadcrumbs that should be captured. - + Enabled per Electron process. @@ -394,20 +362,6 @@ Controls how many seconds to wait before shutting down. Sentry SDKs send events - - -Depending on your setup, the Sentry SDK will try to detect if it has been incorrectly set up. This can result in warnings like this being logged: - -> [Sentry] < libraryName > is not instrumented. This is likely because you required/imported < libraryName > before calling `Sentry.init()`. - -Or - -> [Sentry] < libraryName > is not instrumented. Please make sure to initialize Sentry in a separate file that you \`--import\` when running node, see: < docs link >. - -This means the SDK detected that the library hasn't been wrapped for automatic performance instrumentation. This may result in some spans not being reported correctly. If this is not affecting you (for example because the warning is a false positive or you do not care about these specific spans), you can disable this warning by setting this option to `true`. - - - **Note:** Electron `main` process only. @@ -631,37 +585,15 @@ This is useful to prevent traces of unknown third-party services from being cont - - -This function is called with a transaction event object, and can return a modified transaction event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending. - -Not available in stream mode. Instead, use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendSpan`](#beforeSendSpan) to modify spans. - - - - - -This function is called with a serialized span object and can return a modified span object. Use it, for example, to manually strip PII from spans or filter data from spans before they're sent to Sentry. It runs for all spans, including transactions and their child spans. + -Note that `beforeSendSpan` can only modify span data, meaning you cannot use it to drop spans. Use [`ignoreSpans`](#ignoreSpans) to drop spans, or [`beforeSendTransaction`](#beforeSendTransaction) to drop transactions. +Called for each finished span before it is sent to Sentry, including service spans and their child spans. Return the modified span to rename it or remove sensitive data. Check `span.is_segment` to apply changes only to service spans. -The `span` you receive as an argument is a serialized object, not a `Span` class instance. +`beforeSendSpan` can only modify spans. It cannot drop them or return `null`. Use [`ignoreSpans`](#ignoreSpans) to drop spans. -If you're using stream mode, wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` — otherwise the SDK falls back to transaction mode. +The callback receives a serialized `StreamedSpanJSON` object, not a `Span` instance. `Sentry.spanToJSON()` returns the same shape. - - -In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names: - -| Transaction Mode (`SpanJSON`) | Stream Mode (`StreamedSpanJSON`) | -| ---------------------------------- | ----------------------------------- | -| `span.description` | `span.name` | -| `span.data` (processed attributes) | `span.attributes` (raw attributes) | -| `span.timestamp` (end time) | `span.end_timestamp` | -| `span.status` (optional string) | `span.status` (`'ok'` or `'error'`) | -| `span.op` | `span.attributes['sentry.op']` | - - +With [`traceLifecycle: 'static'`](#traceLifecycle), wrap the callback with `Sentry.withStaticSpan()` to receive and return `SpanJSON`. The static callback runs for the transaction and its child spans. A callback that doesn't match the trace lifecycle is ignored. @@ -671,11 +603,17 @@ In stream mode, the span object is `StreamedSpanJSON` instead of `SpanJSON` and - + + +This callback has no effect in stream mode. Use [`beforeSendSpan`](#beforeSendSpan) to modify spans and check `span.is_segment` to target service spans. Use [`ignoreSpans`](#ignoreSpans) to drop spans. + +With [`traceLifecycle: 'static'`](#traceLifecycle), this callback receives a transaction event and an event hint after all event processors have run. Return the modified event to change its data, or `null` to drop the transaction and its child spans. - + -Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead. + + + @@ -683,18 +621,14 @@ Not available in stream mode. Use [`ignoreSpans`](#ignoreSpans) instead. A list of strings or regex patterns matching spans that shouldn't be sent to Sentry. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. You can also provide an object with `name`, `op`, and `attributes` properties to match on multiple conditions. At least one property must be provided. -If a matching span is a transaction or service span, the entire local trace will be dropped. If a child span matches, its children will be reparented to the dropped span's parent span. +If a matching span is a service span, its child spans are also dropped. If a child span matches, its children will be reparented to the dropped span's parent span. By default, no spans are ignored. In stream mode, `ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped. - +In transaction mode, `ignoreSpans` is evaluated when the transaction ends, using the span's final name and attributes. -In transaction mode, `ignoreSpans` is evaluated at transaction end rather than at span start. Review your existing rules to make sure the attributes you're matching on are passed when the span is created. - -If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting `debug: true` when initializing the SDK. - - +To inspect the initial names of automatically created spans, enable SDK debug logging during development with `debug: true`. @@ -741,13 +675,27 @@ Sentry.init({ + + +This option has no effect in stream mode. Use [`ignoreSpans`](#ignoreSpans) to filter spans by name, operation, or attributes. + +With [`traceLifecycle: 'static'`](#traceLifecycle), this option filters transaction names against a list of strings and regular expressions. Strings match part of the name. Use a regular expression anchored with `^` and `$` for an exact match. A matching transaction and its child spans are dropped. + + + + + + + + + If set to `true`, the SDK adds the [W3C `traceparent` header](https://www.w3.org/TR/trace-context/) to outgoing Http requests made via `fetch` or `XMLHttpRequest`. This header is attached in addition to the `sentry-trace` and `baggage` headers. Set this option to `true` if your backend services are instrumented with e.g. OpenTelemetry or other W3C Trace Context compatible libraries and you want to continue traces from the client. - + **Important:** Make sure that your backend services' CORS configuration allows the `traceparent` header. Otherwise, requests might be blocked. @@ -760,32 +708,24 @@ See De - - -When enabled, `gen_ai` spans are sent as standalone envelope items instead of being bundled in the transaction payload. This prevents AI spans with large inputs and outputs from being dropped due to transaction payload size limits. - -This is enabled by default starting with SDK version `10.61.0` (before that, it defaulted to `false`). Set it to `false` to send `gen_ai` spans as part of the transaction instead. - -Self-hosted Sentry users should set this option to `false`, as standalone `gen_ai` spans may not be ingested by their Sentry instance. - - - - + Controls how spans are sent to Sentry: -- In transaction mode (`'static'`, the default), all spans are collected in memory and sent to Sentry as a single transaction once the root span ends. -- In stream mode (`'stream'`), spans are sent in batches as they finish. - - - +- In stream mode (`'stream'`, the default), spans are sent in batches as they finish. +- In transaction mode (`'static'`), spans are collected in memory and sent as a transaction once the root span ends. This mode is available for backwards compatibility. -You don't need to use this option if you're using a browser-based SDK (for example, React or Vue) or a framework SDK that handles client-side rendering (for example Next.js or Remix). -Instead, enable stream mode by adding `spanStreamingIntegration` to your integrations when initializing the SDK. +To opt out of span streaming, set `traceLifecycle: 'static'`. If you use `beforeSendSpan`, wrap it with `Sentry.withStaticSpan()` to receive the `SpanJSON` format: - - - +```javascript +Sentry.init({ + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.description = "[filtered]"; + return span; + }), +}); +``` @@ -819,13 +759,6 @@ This function is called with a log object, and can return a modified log object, are set. - - -Set this option to `false` to disable metric capturing in Sentry (enabled by default). -Only when this option is enabled will the `metrics` APIs actually send metrics to Sentry. - - - This function is called with a metric object, and can return a modified metric object, or `null` to skip sending this metric to Sentry. @@ -872,14 +805,6 @@ Determines how profiling sessions are controlled. It has two modes: - - -**Deprecated:** Use `profileSessionSampleRate` instead to configure continuous profiling from version `7.4.0` onwards. - -A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled. - - - @@ -911,14 +836,6 @@ Determines how profiling sessions are controlled. It has two modes: - - -**Deprecated:** Use `profileSessionSampleRate` instead to configure continuous profiling from version 10.27.0 onwards. - -A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled. - - - diff --git a/docs/platforms/javascript/common/configuration/transports.mdx b/docs/platforms/javascript/common/configuration/transports.mdx index 1a3ba82cc54a4..be8c17b03ceb6 100644 --- a/docs/platforms/javascript/common/configuration/transports.mdx +++ b/docs/platforms/javascript/common/configuration/transports.mdx @@ -12,7 +12,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/configuration/tree-shaking.mdx b/docs/platforms/javascript/common/configuration/tree-shaking.mdx index e3d50897086c4..24040c3dc27dd 100644 --- a/docs/platforms/javascript/common/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/common/configuration/tree-shaking.mdx @@ -269,7 +269,6 @@ This means that the `ClientOptions.integrations` property is the final array of + ## Requirements @@ -41,7 +40,7 @@ Once implemented, it'll allow you to get alerts and metrics to help you solve er - + ## Requirements diff --git a/docs/platforms/javascript/common/crons/troubleshooting.mdx b/docs/platforms/javascript/common/crons/troubleshooting.mdx index 3d3822f44d4bf..bfed46e4d4108 100644 --- a/docs/platforms/javascript/common/crons/troubleshooting.mdx +++ b/docs/platforms/javascript/common/crons/troubleshooting.mdx @@ -16,7 +16,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/data-management/data-collected/index.mdx b/docs/platforms/javascript/common/data-management/data-collected/index.mdx index 8945a902a7a2f..280657b5c519c 100644 --- a/docs/platforms/javascript/common/data-management/data-collected/index.mdx +++ b/docs/platforms/javascript/common/data-management/data-collected/index.mdx @@ -12,9 +12,9 @@ The category types and amount of data collected vary, depending on the integrati -You can control many of the categories listed here with the `dataCollection` option, which lets you opt in or out of each data category individually. The `sendDefaultPii` option is still supported, but deprecated as of version `10.54.0`. +You can control many of the categories listed here with the `dataCollection` option, which lets you opt in or out of each data category individually. -How much data the SDK collects by default depends on which option you use. Without `dataCollection` (and with `sendDefaultPii` unset or `false`), the SDK collects conservatively, and the defaults described on this page apply. As soon as you pass a `dataCollection` object, the categories you don't set explicitly fall back to their `dataCollection` defaults, which are more permissive. For example, cookies, query parameters (with sensitive values scrubbed), and AI message content is then collected unless you opt out. Setting `sendDefaultPii: true` is equivalent to enabling all `dataCollection` categories. If both are set, `sendDefaultPii` is ignored. +By default, the SDK collects all `dataCollection` categories and scrubs values whose keys match the built-in sensitive denylist. To collect less, opt out of a category or restrict it. Regardless of these options, you can always scrub any data before it's sent to Sentry. See Scrubbing Sensitive Data for details. @@ -28,15 +28,13 @@ Use the `dataCollection.httpHeaders` option to control this. For example, set `d ## Cookies -By default, the Sentry SDK doesn't send cookies. When using `dataCollection`, however, cookies are collected with sensitive values (like `token` or `key`) scrubbed. Opt out by setting `dataCollection: { cookies: false }`. - -To collect cookies when not using `dataCollection`, set the deprecated `sendDefaultPii: true` in `Sentry.init()`. To disable cookie collection when using `dataCollection`, set `dataCollection: { cookies: false }`. You can also restrict which cookie values are sent using `{ allow: [...] }` or `{ deny: [...] }`. +By default, the Sentry SDK sends cookies and scrubs sensitive values (like `token` or `key`). To disable cookie collection, set `dataCollection: { cookies: false }`. You can also restrict which cookie values are sent using `{ allow: [...] }` or `{ deny: [...] }`. ## Information About Logged-in User -When using `dataCollection`, the SDK automatically populates user identity fields (`user.id`, `user.email`, `user.username`) from instrumentation. To disable this, set `dataCollection: { userInfo: false }`. +By default, the SDK populates user identity fields (`user.id`, `user.email`, `user.username`) from instrumentation. To disable this, set `dataCollection: { userInfo: false }`. -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), user identity fields are not sent automatically. Some integrations (e.g. User Feedback) may still send data like the user ID, username, and email address when explicitly configured. +With `userInfo: false`, user identity fields are not sent automatically. Some integrations (e.g. User Feedback) may still send data like the user ID, username, and email address when explicitly configured. ### Local Device User @@ -46,14 +44,13 @@ Without `dataCollection` (and with `sendDefaultPii` unset or `false`), user iden ## Users' IP Address and Location -When using `dataCollection`, the SDK sends the user's IP address by default. To disable it, set `dataCollection: { userInfo: false }`. +By default, the SDK sends the user's IP address. To disable it, set `dataCollection: { userInfo: false }`. -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), the user's IP address is not sent. In some integrations such as [`handleRequest`](/platforms/javascript/guides/astro/#customize-server-instrumentation) in Astro, the user's IP address can also be sent by enabling `trackClientIp`. If sending the IP address is enabled we will try to infer the IP address or use the IP address provided by `ip_address` in `Sentry.setUser()`. If you set `ip_address: null`, the IP address won't be inferred. -Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). If you use `dataCollection`, add these terms to the partially-matched deny lists for those categories so their values are filtered: +Even when this is disabled, IP addresses can still reach Sentry through collected HTTP headers, cookies, or query parameters (for example, the `X-Forwarded-For` header). Add these terms to the partially-matched deny lists for those categories so their values are filtered: ```JavaScript Sentry.init({ @@ -74,13 +71,13 @@ The full request URL of outgoing and incoming HTTP requests is **always sent to By default, the full request query string of outgoing and incoming HTTP requests is sent to Sentry. Depending on your application, this could contain PII data. For example, a query string like `?user_id=1234`, where `1234` is a user id (which may be considered PII). -Use the `dataCollection.urlQueryParams` option to control this. Set it to `false` to disable collection entirely, or use `{ allow: [...] }` / `{ deny: [...] }` to filter which values are sent. When `dataCollection` is used, values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. +Use the `dataCollection.urlQueryParams` option to control this. Set it to `false` to disable collection entirely, or use `{ allow: [...] }` / `{ deny: [...] }` to filter which values are sent. Values whose keys match the built-in sensitive denylist (terms like `auth`, `token`, `password`, and `secret`) are scrubbed automatically. Sentry also has some additional [server-side data scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) in place to remove sensitive data from the query string. ## Request Body -When using `dataCollection`, incoming and outgoing request bodies are collected by default. To disable body collection, set `dataCollection: { httpBodies: [] }`. You can also collect only specific body types by providing a subset: `"incomingRequest"`, `"outgoingRequest"`, `"incomingResponse"`, and `"outgoingResponse"`. +By default, incoming and outgoing request bodies are collected. To disable body collection, set `dataCollection: { httpBodies: [] }`. You can also collect only specific body types by providing a subset: `"incomingRequest"`, `"outgoingRequest"`, `"incomingResponse"`, and `"outgoingResponse"`. ```js Sentry.init({ @@ -91,14 +88,18 @@ Sentry.init({ }); ``` -Without `dataCollection` (and with `sendDefaultPii` unset or `false`), Sentry only sends the body size inferred from the `content-length` header, not the body content itself. +If you disable body collection, Sentry only sends the body size inferred from the `content-length` header, not the body content itself. - On the server-side, the incoming request body is captured by default. You can disable sending the incoming request body by configuring `ignoreIncomingRequestBody` in the HTTP Integration. + On the server-side, the incoming request body is captured by default. You can disable sending the incoming request body by configuring `ignoreRequestBody` in the HTTP Integration. - When `dataCollection` is used, HTTP body collection is enabled by default, so Form Data can be sent with `captureActionFormDataKeys` in the Remix server-side configuration. When not using `dataCollection`, this requires the deprecated `sendDefaultPii: true`. + Remix action form data is captured when `dataCollection.httpBodies` includes `"incomingRequest"`, which is the default. All form fields are captured, and values with a sensitive-looking field name (like `password` or `token`) are replaced with `[Filtered]`. + + To capture only specific fields, set `captureActionFormDataKeys` in the Remix server-side configuration. This option works on its own and doesn't require `dataCollection.httpBodies` to include `"incomingRequest"`. To stop capturing form data, remove `captureActionFormDataKeys` and exclude `"incomingRequest"` from `dataCollection.httpBodies`. + + Captured fields are sent as `remix.action_form_data.` span attributes. Before version 11, the Node.js SDK sent them as `formData.`, so update any dashboards, alerts, or saved searches that query the old attribute names. @@ -111,9 +112,9 @@ On the server-side, the + ## Session Replay By default, our Session Replay SDK masks all text content, images, web views, and user input. This helps ensure that no sensitive data is exposed. You can find more details in the Session Replay documentation. - The `dataCollection` and `sendDefaultPii` options don't affect Session Replay. Because Replay is opt-in by default (it masks everything unless you allow it), while `dataCollection` is opt-out, the two use opposite privacy models. To avoid changing behavior on a privacy-sensitive feature, Replay's masking and network capture are controlled exclusively by the Replay integration's own privacy options, regardless of your `dataCollection` or `sendDefaultPii` settings. + The `dataCollection` option doesn't affect Session Replay. Because Replay is opt-in by default (it masks everything unless you allow it), while `dataCollection` is opt-out, the two use opposite privacy models. To avoid changing behavior on a privacy-sensitive feature, Replay's masking and network capture are controlled exclusively by the Replay integration's own privacy options, regardless of your `dataCollection` settings. Session Replay also captures basic information about all outgoing fetch and XHR requests in your application. This includes the URL, request and response body size, method, and status code. If `networkDetailAllowUrls` are defined, the request and response body will be sent to Sentry as well. This can include PII data if the request or response body contains PII information. @@ -166,7 +167,7 @@ By default, the Sentry SDK sends information about the device and runtime to Sen By default, the Sentry SDK sends JS console logs to Sentry as breadcrumbs which may contain PII data. - To disable sending console messages, set `console: false` in your `Sentry.breadcrumbsIntegration` config, see the Breadcrumbs documentation. + To disable sending console messages, remove the `Console` integration from your `integrations` config, see the Console documentation. ## Referrer URL @@ -225,9 +226,9 @@ By default, the Sentry SDK sends information about the device and runtime to Sen ## tRPC Context - When using `dataCollection`, tRPC input is collected by default because `httpBodies` includes `"incomingRequest"` by default. To disable it, set `dataCollection: { httpBodies: [] }` or use a list that excludes `"incomingRequest"`. + By default, tRPC input is collected because `httpBodies` includes `"incomingRequest"` by default. To disable it, set `dataCollection: { httpBodies: [] }` or use a list that excludes `"incomingRequest"`. - Without `dataCollection` (and with `sendDefaultPii` unset or `false`), tRPC input is not collected. You can still opt in per-middleware by setting `attachRpcInput: true` in the `Sentry.trpcMiddleware()` options, regardless of the global `dataCollection` setting. + If you exclude `"incomingRequest"`, tRPC input is not collected. You can still opt in per-middleware by setting `attachRpcInput: true` in the `Sentry.trpcMiddleware()` options, regardless of the global `dataCollection` setting. @@ -236,7 +237,7 @@ By default, the Sentry SDK sends information about the device and runtime to Sen When you use a GraphQL integration, the Sentry SDK sends the operation name and the operation type to Sentry. -When you use `dataCollection`, the SDK also sends the GraphQL document (the query or mutation source text) and the variables passed to the operation by default. This data can include PII. Use the `dataCollection.graphQL` option (available since version `10.66.0`) to control it: +By default, the SDK also sends the GraphQL document (the query or mutation source text) and the variables passed to the operation by default. This data can include PII. Use the `dataCollection.graphQL` option (available since version `10.66.0`) to control it: ```JavaScript Sentry.init({ @@ -255,7 +256,9 @@ Sentry.init({ When using AI integrations, metadata like model ID and used tokens is sent to Sentry. - The content of generative AI inputs (system instructions, prompt messages, tool definitions, and tool call arguments) and outputs (such as completion text and tool call results) might carry personal data. Whether it's recorded depends on your configuration: it's not recorded by default with `sendDefaultPii`, but when you use `dataCollection`, the `genAI` category records both inputs and outputs unless you opt out. Metadata like model ID and token counts is always collected. + The content of generative AI inputs (system instructions, prompt messages, tool definitions, and tool call arguments) and outputs (such as completion text and tool call results) might carry personal data. By default, the SDK records both inputs and outputs. Metadata like model ID and token counts is always collected. + + The same setting applies to MCP servers instrumented with `wrapMcpServerWithSentry`. By default, the SDK records the inputs and outputs of tool calls, prompt retrievals, and resource reads. Use the wrapper's `recordInputs` and `recordOutputs` options to control recording per server. Use the `dataCollection.genAI` option to control this. For example, opt out of recording AI message content while keeping the metadata: 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 2863a6c586237..b5c70dd09409f 100644 --- a/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/javascript/common/data-management/sensitive-data/index.mdx @@ -38,17 +38,17 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide ### Scrubbing in `beforeSend*` SDK Hooks -SDKs provide various `beforeSend*` hooks, which are invoked before an errors, messages, spans, logs or metrics are sent and can be used to modify event data to remove sensitive information. The following hooks are available: +SDKs provide various `beforeSend*` hooks, which are invoked before errors, messages, spans, logs, or metrics are sent and can be used to modify event data to remove sensitive information. The following hooks are available: - `beforeSend` applies to error and message events - `beforeSendSpan` applies to spans - `beforeSendLog` applies to logs - `beforeSendMetric` applies to metrics -- `beforeSendTransaction` applies to transactions (only in transaction mode) +- `beforeSendTransaction` applies to transaction events in transaction mode -If you're using span stream mode, `beforeSendTransaction` has no effect. Instead, use `beforeSendSpan` with the `withStreamedSpan` helper to modify streamed spans directly. +Use `beforeSendSpan` to remove sensitive data from spans, including service spans and child spans. In transaction mode, wrap the callback with `Sentry.withStaticSpan()` and use `beforeSendTransaction` to scrub transaction events. diff --git a/docs/platforms/javascript/common/enriching-events/attributes/index.mdx b/docs/platforms/javascript/common/enriching-events/attributes/index.mdx index 41edd64e15be8..5ad9c71493437 100644 --- a/docs/platforms/javascript/common/enriching-events/attributes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/attributes/index.mdx @@ -11,6 +11,12 @@ Unlike [tags](../tags/), which only accept `string` values, attributes support ` Common uses include subscription tier, feature flags, or any business context that helps you filter and query your telemetry. Check out [Sending Span Metrics](../../tracing/span-metrics/) for an example of how to use attributes to enrich your spans. + + +Use attributes for any data you want to search on spans. Streamed spans only carry attributes, so tags and extra (`Sentry.setTag()`, `Sentry.setExtra()`, and similar) aren't added to any span. They still apply to errors, so you don't need to remove them. Unlike tags, attributes keep their type, so you don't need to convert numbers and booleans to strings. + + + Setting attributes will bind them to the [isolation scope](../scopes/#isolation-scope). This ensures they'll automatically be included on future telemetry for the current request or page view: ```javascript diff --git a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx index f03d771f8d06f..b0502148775f2 100644 --- a/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/request-isolation/index.mdx @@ -6,7 +6,6 @@ supported: - javascript.node - javascript.eve - javascript.mastra - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx index 225af428a63fc..58441d6a711b2 100644 --- a/docs/platforms/javascript/common/enriching-events/scopes/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/scopes/index.mdx @@ -104,6 +104,14 @@ Sentry.captureException(new Error("my error")); // { shared: 'current', global: 'data', isolation: 'data', current: 'data' } ``` + + +With span streaming enabled, spans only carry attributes. Tags and extra set on any scope (for example, with `setTag()`, `setTags()`, `setExtra()`, or `setExtras()`) aren't applied to spans. They still apply to errors, so you don't need to remove them. In transaction mode (`traceLifecycle: "static"`), they're still added to the transaction. + +To make data searchable on spans, set it with `setAttribute()` or `setAttributes()`, which also applies it to logs and metrics. See Attributes. + + + ## Configuring the Scope In most cases, you should use top-level methods like `Sentry.setTag()` directly, which will set the data on the isolation scope, ensuring it is applied to all events related to the current request/process. diff --git a/docs/platforms/javascript/common/enriching-events/tags/index.mdx b/docs/platforms/javascript/common/enriching-events/tags/index.mdx index 14c1e158ddcd8..0d8f2803c0b1d 100644 --- a/docs/platforms/javascript/common/enriching-events/tags/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/tags/index.mdx @@ -8,7 +8,11 @@ description: "Tags in Sentry's JavaScript SDK power UI features such as filters We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues. - Tags are **not** applied to logs or metrics. If you're using SDK version `10.61.0` or above and want to attach context to logs or metrics, use Attributes instead. + +Tags are **not** applied to logs, metrics, or spans when span streaming is enabled. Tags still apply to errors, and in transaction mode (`traceLifecycle: "static"`) they're still added to the transaction. + +If you're using SDK version `10.61.0` or above and want data to be searchable on spans, logs, or metrics, use Attributes instead. + _Tag keys_ have a maximum length of 200 characters and can contain only letters (`a-zA-Z`), numbers (`0-9`), underscores (`_`), periods (`.`), colons (`:`), and dashes (`-`). diff --git a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx index 9096d38425ae3..caf8ff40a7984 100644 --- a/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/transaction-name/index.mdx @@ -104,10 +104,22 @@ Learn more about + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +If you build your server with a bundler, you can instrument your dependencies at build time with the Sentry bundler plugin instead of loading Sentry with the [`--import`](https://nodejs.org/api/cli.html#--importmodule) flag. Because the instrumentation is baked into your bundle, a plain top-level import of your instrument file is enough, and you can start your app with a regular `node` command, without the `--import` flag. + +Use this method if you can't pass a command line flag to the Node.js binary, for example when your start command is fixed by your platform or process manager. + +## 1. Create Your Instrument File + +Create a file named `instrument.(js|mjs)` in the root directory of your project that initializes Sentry: + + + +## 2. Add the Sentry Bundler Plugin + +Add the Sentry plugin for your bundler to your build configuration. The plugin instruments your dependencies at build time, so the SDK no longer depends on `Sentry.init()` running before your other imports. + +```javascript {tabTitle:Vite} {filename: vite.config.mjs} +import { sentryVitePlugin } from "@sentry/node/vite"; + +export default { + plugins: [sentryVitePlugin()], +}; +``` + +```javascript {tabTitle:Rollup} {filename: rollup.config.mjs} +import { sentryRollupPlugin } from "@sentry/node/rollup"; + +export default { + plugins: [sentryRollupPlugin()], +}; +``` + +```javascript {tabTitle:webpack} {filename: webpack.config.mjs} +import { sentryWebpackPlugin } from "@sentry/node/webpack"; + +export default { + plugins: [sentryWebpackPlugin()], +}; +``` + +```javascript {tabTitle:esbuild} {filename: build.mjs} +import { sentryEsbuildPlugin } from "@sentry/node/esbuild"; + +await esbuild.build({ + plugins: [sentryEsbuildPlugin()], +}); +``` + +## 3. Import Your Instrument File First + +Import `instrument.(js|mjs)` at the very top of your application's entry point, before any other imports: + +```javascript {filename: app.mjs} +// Import this first! +import "./instrument.mjs"; + +// Now import other modules +import express from "express"; + +// Your application code goes here +``` + +## 4. Run Your App + +Start your application as usual. No `--import` flag is required, because the instrumentation is already part of your bundle: + +```bash +node app.mjs +``` + +If you can't use a bundler, review our other [installation methods](../) for alternatives that don't rely on the `--import` flag. diff --git a/docs/platforms/javascript/common/install/commonjs.mdx b/docs/platforms/javascript/common/install/commonjs.mdx deleted file mode 100644 index 978d93e2ea363..0000000000000 --- a/docs/platforms/javascript/common/install/commonjs.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: CommonJS (CJS) -sidebar_order: 9 -description: "Learn about running Sentry in an CJS application." -supported: - - javascript.node - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. -CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. - -You need to create a file named `instrument.js` that imports and initializes Sentry: - - - -You need to require or import the `instrument.js` file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: - - diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index a1a742bb750f5..5cdf6b0619c43 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -1,15 +1,22 @@ --- -title: ESM without CLI Flag -sidebar_order: 11 -description: "Learn about running Sentry in an ESM application, without the --import flag." -supported: - - javascript.node - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa +title: Deferred Entrypoint +sidebar_order: 3 +description: "Learn about running Sentry without the --import flag." +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs --- @@ -17,98 +24,20 @@ supported: [installation methods](../). +If you can neither run your application with `--import`, nor use a bundler, you can use a deferred entrypoint to run your application with Sentry. -When running your application in ESM mode, you will most likely want to follow the ESM instructions. However, if you can't use the `--import` command line option, you can either use [direct imports](#direct-imports) or [SEA bootstrap setup](#nodejs-single-executable-applications) if you are using a Node.js Single Executable Application (SEA). +This assumes you've already created an `instrument.mjs` file that calls `Sentry.init()`, as shown in the quickstart. -## Direct Imports +Split the entrypoint in two. The static import runs `Sentry.init()`, and the dynamic `import()` loads your application afterwards, so your application's modules are wrapped: +```javascript {filename: main.mjs} +import "./instrument.mjs"; - - -This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). - -As a result, the Sentry SDK will not capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. - -We recommend using this only if the `--import` flag is not an option for you. - - - -You need to create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); +await import("./app.mjs"); ``` -You need to import the `instrument.mjs` file before importing any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: - -```javascript {filename: app.mjs} -// Import this first! -import "./instrument"; +Your application code stays in `app.mjs` and needs no changes. Start it as usual: -// Now import other modules -import http from "http"; - -// Your application code goes here +```bash +node main.mjs ``` - -## Node.js Single Executable Applications - -Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly. - -The embedded SEA main should only load a filesystem bootstrap file next to the -executable: - -```javascript {filename: sea-main.cjs} -const { createRequire } = require("node:module"); - -createRequire(__filename)("./sea-bootstrap.cjs"); -``` - -The filesystem bootstrap imports Sentry first, then imports your real app -entrypoint: - -```javascript {filename: sea-bootstrap.cjs} -async function startApp() { - await import("./instrument.mjs"); - await import("./app.mjs"); -} - -startApp(); -``` - -Keep your Sentry setup in `instrument.mjs`: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, -}); -``` - -Then configure SEA to use `sea-main.cjs` as its main script: - -```json {filename: sea-config.json} -{ - "main": "sea-main.cjs", - "output": "sea-prep.blob", - "disableExperimentalSEAWarning": true, - "useSnapshot": false -} -``` - -Keep `sea-bootstrap.cjs`, `instrument.mjs`, and `app.mjs` available on the filesystem next to the executable. - -This setup lets the Sentry SDK register ESM instrumentation hooks before your application imports instrumented modules, such as Express or database clients. Your instrumentation file and app entrypoint can stay ESM. The verified bootstrap pattern shown here uses CommonJS only for the small SEA entry files. - -Node.js SEA support is still evolving, including how embedded ESM entrypoints and module loading are configured. The embedded SEA main may not be able to load filesystem modules with `import()` directly, so the example above uses `module.createRequire()` to bridge from the embedded main to a normal filesystem bootstrap. The important requirement is startup order: load Sentry before loading the application modules you want Sentry to instrument. diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx deleted file mode 100644 index d222a843810b8..0000000000000 --- a/docs/platforms/javascript/common/install/esm.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: ESM (MJS) -sidebar_order: 10 -description: "Learn about running Sentry in an ESM application." -supported: - - javascript.node - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in ESM mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. - -You need to create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`, which contains your `Sentry.init()` code: - -```bash -# Note: This is only available for Node v18.19.0 onwards. -node --import ./instrument.mjs app.mjs -``` - -If it is not possible for you to pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows: - -```bash -NODE_OPTIONS="--import ./instrument.mjs" npm run start -``` - -If you're building a Node.js Single Executable Application (SEA) and can't rely -on `--import` or `NODE_OPTIONS`, use the SEA -bootstrap setup instead. - -We do not support ESM in Node versions before 18.19.0. - -## Troubleshooting instrumentation - -By default, all packages are wrapped under the hood by -[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to -aid instrumenting them. - -If `import-in-the-middle` encounters problems wrapping a package, you may see -syntax errors at runtime or logged errors in your console: - -```logs -SyntaxError: The requested module '...' does not provide an export named '...' -(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js' -``` - -To confirm that these errors are caused by `import-in-the-middle`, -disable it by setting `registerEsmLoaderHooks` to false. Note, this will also -disable tracing instrumentation: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - registerEsmLoaderHooks: false, -}); -``` diff --git a/docs/platforms/javascript/common/install/esm__v8.x.mdx b/docs/platforms/javascript/common/install/esm__v8.x.mdx index fb850ab562d98..3796d110427da 100644 --- a/docs/platforms/javascript/common/install/esm__v8.x.mdx +++ b/docs/platforms/javascript/common/install/esm__v8.x.mdx @@ -4,7 +4,6 @@ sidebar_order: 10 description: "Learn about running Sentry in an ESM application." supported: - javascript.node - - javascript.connect - javascript.express - javascript.fastify - javascript.hapi diff --git a/docs/platforms/javascript/common/install/index.mdx b/docs/platforms/javascript/common/install/index.mdx index 07508f115f535..464c2e71387d8 100644 --- a/docs/platforms/javascript/common/install/index.mdx +++ b/docs/platforms/javascript/common/install/index.mdx @@ -5,6 +5,9 @@ description: "Review our alternate installation methods." notSupported: - javascript.eve - javascript.mastra + - javascript.nitro + - javascript.nestjs + - javascript.azure-functions - javascript.angular - javascript.astro - javascript.bun @@ -39,28 +42,41 @@ notSupported: ## How To Decide Which Installation Method To Use -Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. -CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in ESM mode, this will not work. In this case, you can follow the [ESM docs](./esm). +The SDK has to wrap the modules your application uses before your application imports them. How you arrange that is the only difference between the methods below. `--import` works for both ESM and CommonJS applications, so the module system your application uses no longer decides the method. -Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. In this case, you should follow the [CommonJS instructions](./commonjs). +### Load Your Instrument File With `--import` (Recommended) -### My application is in TypeScript +Put `Sentry.init()` in an instrument file and load it with the `--import` flag: -If you're using TypeScript, your application is likely compiled to CommonJS before running it. In this case, you should follow the [CommonJS instructions](./commonjs). +```bash +node --import ./instrument.mjs app.mjs +``` -### My application uses `require` +This runs `Sentry.init()` before any of your application's modules load, so every instrumented library is wrapped and every error during startup is captured. Use this unless one of the cases below applies to you. -If you are using `require()` in your application, you should follow the [CommonJS instructions](./commonjs). +`--import` works for CommonJS applications too, with an `instrument.js` file: -### My application uses `import` +```bash +node --import ./instrument.js app.js +``` -If you are using `import` in your application, your installation method depends on how your application is _run_. If you compile your application (e.g. into a `/dist` folder or similar) before running this, you need to check how the compiled code looks like. Is the compiled code using `require`? Then you should follow the [CommonJS instructions](./commonjs). If the compiled code is using `import`, you should follow the [ESM instructions](./esm). +Note that `--require` is no longer supported for initialization. -If you do not compile your code, you'll need to follow the [ESM instructions](./esm). +### Bundler Plugin and a Top-Level Import -### I don't need automatic spans/transactions +If you build your server with a bundler, instrument your dependencies at build time with the Sentry bundler plugin and import `instrument.mjs` at the top of your entry file. Because the plugin bakes the instrumentation into your bundle, a top-level import is enough and you don't need a flag on the Node.js binary. See With a Bundler. -If you don't need spans emitted by OpenTelemetry instrumentation, you can use `@sentry/node-core` in [Lightweight Mode](./lightweight) without OpenTelemetry dependencies. You still get errors, logs, metrics, breadcrumbs, and more. This mode is experimental. +If you can't use a bundler, a top-level import on its own isn't equivalent to `--import`, because ESM evaluates every import in a file before it runs the first line of that file. See Deferred Entrypoint for an alternative way to run your application in this case. + +### Prepare the instrumentation with `--import` and Initialize Later + +If you can't call `Sentry.init()` at startup, for example because you fetch your DSN from an external source, `--import` the instrumentation early and call `Sentry.init()` at a later point: + +```bash +node --import @sentry/node/import main.mjs +``` + +See Late Initialization. diff --git a/docs/platforms/javascript/common/install/late-initialization.mdx b/docs/platforms/javascript/common/install/late-initialization.mdx index 1362f0af7741a..93bb6184fafd6 100644 --- a/docs/platforms/javascript/common/install/late-initialization.mdx +++ b/docs/platforms/javascript/common/install/late-initialization.mdx @@ -1,15 +1,22 @@ --- -title: Late Initialization (ESM or CJS) -sidebar_order: 12 +title: Late Initialization +sidebar_order: 2 description: "Learn about running Sentry in an ESM or CJS application, in scenarios where you cannot run init early." -supported: - - javascript.node - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs --- @@ -17,67 +24,30 @@ supported: [installation methods](../). -In order for auto-instrumentation to work, it is generally required to run `Sentry.init()` as early as possible, before anything else is imported in your application. +For auto-instrumentation to work, `Sentry.init()` normally has to run before anything else is imported in your application. -However, in some cases this may not be possible to do—for example, if you are fetching your DSN from an external source. In this case, you can use the `@sentry/node/preload` hook to ensure modules are wrapped early, which allows you to call `Sentry.init()` later at a time of your choosing. - - - We recommend to only use this method if strictly necessary. In most cases, it - is better to find a way to run `Sentry.init()` early in your application, in - order to ensure that no error can go unreported. - - -This initialization method is available starting in version **8.5.0**. - -## Late Initialization with CommonJS (CJS) - -In your CJS application, use the `@sentry/node/preload` hook with `--require` to ensure modules are wrapped early: +In some cases that isn't possible, for example when you fetch your DSN from an external source. For these cases, `--import` the SDK itself instead of your own instrument file. The SDK then wraps the modules your application imports, and you call `Sentry.init()` later: ```bash -node --require @sentry/node/preload app.js +node --import @sentry/node/import main.mjs ``` -Then, in your application you can call `Sentry.init()` at a later point: - -```javascript {filename: main.js} -const startApp = require("./app"); -const fetchDsn = require("./utils/fetchDsn"); -const Sentry = require("@sentry/node"); - -startApp(); - -const dsn = fetchDsn(); -Sentry.init({ - dsn, - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); - -// From now on, Sentry is initialized, -// but the app is still auto-instrumented -``` - -## Late Initialization with ESM - -In your ESM application, use the `@sentry/node/preload` hook with `--import` to ensure modules are wrapped early: +This works for CommonJS applications as well. `--require` is no longer supported, so use `--import` there too: ```bash -# Note: This is only available for Node v18.19.0 onwards. -node --import @sentry/node/preload app.js +node --import @sentry/node/import app.js ``` -Then, in your application you can call `Sentry.init()` at a later point: +With the flag in place, call `Sentry.init()` at the point of your choosing: -```javascript {filename: main.js} -import startApp from "./app"; -import fetchDsn from "./utils/fetchDsn"; +```javascript {filename: main.mjs} import * as Sentry from "@sentry/node"; +import startApp from "./app.mjs"; +import fetchDsn from "./utils/fetchDsn.mjs"; startApp(); -const dsn = fetchDsn(); +const dsn = await fetchDsn(); Sentry.init({ dsn, @@ -87,47 +57,18 @@ Sentry.init({ }); // From now on, Sentry is initialized, -// but the app is still auto-instrumented -``` - -## What does Preloading mean? - -Integrations that are preloaded ensure that the necessary modules are wrapped early, before they can be imported by your application. At this point, the modules are wrapped, but will not do anything—nothing will be emitted or captured from them. - -Once you call `Sentry.init()`, the wrapped modules will automatically start emitting performance data which will be sent to Sentry. - -## What is Preloaded? - -By default, all performance instrumentation is preloaded when using the `@sentry/node/preload` hook. - -You can optionally configure to only preload certain integrations by defining a `SENTRY_PRELOAD_INTEGRATIONS` environment variable. This variable should be a comma-separated list of integrations to preload. For example, to only preload the `Http` and `Express` integrations, you can set the environment variable as follows: - -```bash -SENTRY_PRELOAD_INTEGRATIONS="Http,Express" node --require @sentry/node/preload app.js +// and the app is still auto-instrumented ``` -You can pass the names of any of the following integrations: - -- `Http` -- `Express` -- `Connect` -- `Fastify` -- `Hapi` -- `Koa` -- `Nest` -- `Mongo` -- `Mongoose` -- `Mysql` -- `Mysql2` -- `Postgres` -- `Graphql` - -Note that it is not necessary to preload `NodeFetch`, this will always be instrumented. + + Use this method only if it's strictly necessary. Anything that happens before + `Sentry.init()` runs isn't captured, so an error thrown during startup goes + unreported. In most cases it's better to find a way to run `Sentry.init()` + early, as described in the quickstart. + -## Debugging Preload +## What Wrapping Means -You can also define a `SENTRY_DEBUG` environment variable in order to get debug logs from the preload hook. This can be useful to understand what is happening during the preload process. +`--import @sentry/node/import` wraps the modules your application imports before your code runs. At that point the modules are wrapped but inactive: nothing is emitted or captured from them. -```bash -SENTRY_DEBUG=1 node --require @sentry/node/preload app.js -``` +Once you call `Sentry.init()`, the wrapped modules start emitting data to Sentry. diff --git a/docs/platforms/javascript/common/install/lightweight.mdx b/docs/platforms/javascript/common/install/lightweight.mdx deleted file mode 100644 index dd87680c2cc5b..0000000000000 --- a/docs/platforms/javascript/common/install/lightweight.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Lightweight Mode -sidebar_order: 15 -description: "Learn about running Sentry in lightweight mode without OpenTelemetry, or with optional OTLP integration for existing OTel setups." -supported: - - javascript.node - - javascript.connect - - javascript.express - - javascript.fastify - - javascript.hapi - - javascript.hono - - javascript.koa ---- - - - Lightweight mode is experimental and may have breaking changes in minor or - patch releases. - - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -If you don't need automatic spans/transactions, you can use `@sentry/node-core/light` which doesn't require OpenTelemetry dependencies. This mode is ideal when: - -- You only need error tracking, logs, or metrics without tracing data (no automatic span creation) -- You want to minimize bundle size and runtime overhead -- You don't need spans emitted by OpenTelemetry instrumentation - -You still get error tracking, logs, metrics, breadcrumbs, context/user data, local variables capture, distributed tracing (via `sentry-trace` and `baggage` headers), and automatic request isolation (Node.js 22+). - -If needed, you can still manually create spans by using Sentry's custom instrumentation APIs like `startSpan`. - -If you already have your own OpenTelemetry setup, you can also use the [OTLP integration](#using-with-opentelemetry-otlp) to link Sentry errors to your OTel traces and export spans to Sentry. - -## Prerequisites - -- **Node.js 22.12.0+** is recommended for full functionality (automatic request isolation) -- Lower Node.js versions work but with limited capabilities (see [Request Isolation](#request-isolation) below) - -## Step 1: Install - -```bash {tabTitle:npm} -npm install @sentry/node-core --save -``` - -```bash {tabTitle:yarn} -yarn add @sentry/node-core -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/node-core -``` - -## Step 2: Configure - -Import from `@sentry/node-core/light` and call `Sentry.init()` as early as possible in your application lifecycle: - -```javascript {tabTitle:ESM} -import * as Sentry from "@sentry/node-core/light"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", -}); - -// Now create your HTTP server or framework app -``` - -```javascript {tabTitle:CJS} -const Sentry = require("@sentry/node-core/light"); - -Sentry.init({ - dsn: "___PUBLIC_DSN___", -}); - -// Now create your HTTP server or framework app -``` - -## Step 3: Verify - -To verify that Sentry is working, capture a test error: - -```javascript -Sentry.captureException(new Error("Sentry lightweight mode test")); -``` - -After running your application, you should see this error appear in your [Sentry dashboard](https://sentry.io). - -## Request Isolation - -Request isolation ensures that errors, breadcrumbs, and context are correctly scoped to individual requests. - -### Node.js 22.12.0+ - -Request isolation works automatically. No additional setup is needed — just make sure `Sentry.init()` is called before you create your HTTP server. - -### Node.js < 22 - -You need to manually wrap your request handler with `Sentry.withIsolationScope()`: - -```javascript -import * as Sentry from "@sentry/node-core/light"; -import http from "http"; - -const server = http.createServer((req, res) => { - Sentry.withIsolationScope(() => { - // Your request handling code - Sentry.setUser({ id: "user-id" }); - res.end("OK"); - }); -}); -``` - - - When using manual isolation on Node.js < 22, distributed tracing will not - work correctly. - - -## Conversation IDs - -To group AI spans in [Conversations](/product/agents/conversations/), add -`conversationIdIntegration` and call `setConversationId`. Neither is included in -lightweight mode by default: - -```javascript -import * as Sentry from "@sentry/node-core/light"; -import { conversationIdIntegration, setConversationId } from "@sentry/core"; - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [ - ...Sentry.getDefaultIntegrations(), - conversationIdIntegration(), - ], -}); - -setConversationId("conv_abc123"); -``` - -## When to Use Lightweight Mode vs `@sentry/node` - -| | `@sentry/node` | `@sentry/node-core/light` | -| ------------------------------- | ------------------- | ---------------------------------------------- | -| **Error tracking** | Yes | Yes | -| **Logs and metrics** | Yes | Yes | -| **Automatic spans** | Yes | No | -| **OpenTelemetry auto-included** | Yes | No | -| **Dependency footprint** | Larger | Minimal | -| **Best for** | Full observability | No auto-instrumentation, manual tracing setup | - -If you need automatic spans for HTTP requests, database queries, and other operations, use `@sentry/node` (the default). If you don't need automatically created spans and want minimal dependencies, use lightweight mode. - -## Using with OpenTelemetry (OTLP) - - - -If you already have your own OpenTelemetry setup and want to bridge it with Sentry, you can use the `otlpIntegration` from `@sentry/node-core/light/otlp`. This integration: - -- Links Sentry errors and logs to the active OpenTelemetry trace context -- Exports OpenTelemetry spans to Sentry via [OTLP](/concepts/otlp/) - -### Install OpenTelemetry Dependencies - -In addition to `@sentry/node-core`, install the OpenTelemetry packages you need: - -```bash {tabTitle:npm} -npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -```bash {tabTitle:yarn} -yarn add @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -```bash {tabTitle:pnpm} -pnpm add @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http -``` - -### Configure - -Set up your OpenTelemetry `TracerProvider` first, then initialize Sentry with the `otlpIntegration`: - -```javascript -import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; -import * as Sentry from "@sentry/node-core/light"; -import { otlpIntegration } from "@sentry/node-core/light/otlp"; - -// Set up your OpenTelemetry TracerProvider as usual -const provider = new NodeTracerProvider(); -provider.register(); - -Sentry.init({ - dsn: "___PUBLIC_DSN___", - integrations: [otlpIntegration()], -}); -``` - -The integration automatically derives the OTLP endpoint from your DSN. To send traces to your own collector instead, pass a `collectorUrl`: - -```javascript -otlpIntegration({ - collectorUrl: "https://my-collector.example.com/v1/traces", -}); -``` - -### Options - -| Option | Type | Default | Description | -|---|---|---|---| -| `setupOtlpTracesExporter` | `boolean` | `true` | Automatically configure an exporter to send OTLP traces to the right project from the DSN or `collectorUrl`. Set to `false` to set up the `TracerProvider` manually. | -| `collectorUrl` | `string` | `undefined` | URL of your own OpenTelemetry collector. When set, traces are sent here instead of the Sentry OTLP endpoint derived from the DSN. | diff --git a/docs/platforms/javascript/common/install/loader.mdx b/docs/platforms/javascript/common/install/loader.mdx index d3e03fa9c8abc..d22a7d614567e 100644 --- a/docs/platforms/javascript/common/install/loader.mdx +++ b/docs/platforms/javascript/common/install/loader.mdx @@ -27,7 +27,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.elysia - javascript.express - javascript.fastify @@ -418,7 +417,7 @@ Our CDN hosts a variety of bundles: - `bundle.tracing.replay.logs.metrics..js` - Error monitoring, tracing, session replay, logs, and metrics - `bundle.tracing.replay.feedback.logs.metrics..js` - Error monitoring, tracing, session replay, feedback, logs, and metrics -Additionally, each of the integrations in `@sentry/integrations` is available as a bundle named `..js`. +Some integrations are available as separate bundles. See Lazy Loading Integrations for the supported list. Since v8 of the SDK, the bundles are ES6 by default. If you need ES5 support, make sure to add a polyfill for ES5 features yourself. Alternatively, you can use the v7 bundles and add the `.es5` modifier. diff --git a/docs/platforms/javascript/common/install/npm.mdx b/docs/platforms/javascript/common/install/npm.mdx index 02d5422d9c7f7..6005ae6afc6be 100644 --- a/docs/platforms/javascript/common/install/npm.mdx +++ b/docs/platforms/javascript/common/install/npm.mdx @@ -28,7 +28,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.elysia - javascript.express - javascript.fastify diff --git a/docs/platforms/javascript/common/install/single-executable-applications.mdx b/docs/platforms/javascript/common/install/single-executable-applications.mdx new file mode 100644 index 0000000000000..c84d922759266 --- /dev/null +++ b/docs/platforms/javascript/common/install/single-executable-applications.mdx @@ -0,0 +1,67 @@ +--- +title: Single Executable Applications +sidebar_order: 4 +description: "Learn about running Sentry in a Single Executable Application (SEA)" +supportedCategories: + - server-only +notSupported: + - javascript.bun + - javascript.deno + - javascript.cloudflare + - javascript.elysia + - javascript.aws-lambda + - javascript.azure-functions + - javascript.gcp-functions + - javascript.firebase + - javascript.eve + - javascript.mastra + - javascript.nitro + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly. + +The embedded SEA main should only load a filesystem bootstrap file next to the +executable: + +```javascript {filename: sea-main.cjs} +const { createRequire } = require("node:module"); + +createRequire(__filename)("./sea-bootstrap.cjs"); +``` + +The filesystem bootstrap imports Sentry first, then imports your real app +entrypoint: + +```javascript {filename: sea-bootstrap.cjs} +async function startApp() { + await import("./instrument.mjs"); + await import("./app.mjs"); +} + +startApp(); +``` + +This is the deferred entrypoint pattern, packaged for SEA. Keep your Sentry setup in `instrument.mjs`. + +Then configure SEA to use `sea-main.cjs` as its main script: + +```json {filename: sea-config.json} +{ + "main": "sea-main.cjs", + "output": "sea-prep.blob", + "disableExperimentalSEAWarning": true, + "useSnapshot": false +} +``` + +Keep `sea-bootstrap.cjs`, `instrument.mjs`, and `app.mjs` available on the filesystem next to the executable. + +This setup lets the Sentry SDK register ESM instrumentation hooks before your application imports instrumented modules, such as Express or database clients. Your instrumentation file and app entrypoint can stay ESM. The verified bootstrap pattern shown here uses CommonJS only for the small SEA entry files. + +Node.js SEA support is still evolving, including how embedded ESM entrypoints and module loading are configured. The embedded SEA main may not be able to load filesystem modules with `import()` directly, so the example above uses `module.createRequire()` to bridge from the embedded main to a normal filesystem bootstrap. The important requirement is startup order: load Sentry before loading the application modules you want Sentry to instrument. diff --git a/docs/platforms/javascript/common/logs/index.mdx b/docs/platforms/javascript/common/logs/index.mdx index f6ceea5a991c6..e73d8e8531cba 100644 --- a/docs/platforms/javascript/common/logs/index.mdx +++ b/docs/platforms/javascript/common/logs/index.mdx @@ -209,7 +209,7 @@ Sentry.init({ Everything in Sentry is linked by trace. When you're viewing a log, you can jump to the parent trace to see the full request context. When you're viewing a trace, you can see all logs emitted during that operation. This connection makes it easy to move between high-level performance data and detailed diagnostic logs. - **[Traces](/product/trace-explorer/)** — Logs emitted during an active span automatically include `sentry.trace.parent_span_id`. Click through from any log to see the full trace, or filter logs by trace ID to see everything that happened during a specific request. -- **[Session Replay](/product/session-replay/)** — Logs include `sentry.replay_id` when a replay is active. Jump from a log entry directly to the replay to see what the user was doing when the log was emitted. +- **[Session Replay](/product/session-replay/)** — Logs include `sentry.replay_id` when a replay is active. Jump from a log entry directly to the replay to see what the user was doing when the log was emitted. - **[Errors](/product/issues/)** — Logs capture the journey leading up to a failure. When an error occurs, your logs show what data was processed, which code paths executed, and what state the system was in — context that stack traces alone can't provide. ## Best Practices @@ -228,6 +228,6 @@ Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or di ## Related Features - Tracing — Logs are automatically linked to traces, so you can see logs in the context of the request or operation that produced them. -- Session Replay — Logs are automatically linked to replays, letting you jump from a log entry to see what the user was doing. +- Session Replay — Logs are automatically linked to replays, letting you jump from a log entry to see what the user was doing. - Error Monitoring — Use logs to add diagnostic context that helps you understand what led to an error. - Attributes — Set attributes once and have them automatically included on all your logs. diff --git a/docs/platforms/javascript/common/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index 626f8ead3a059..47ed98f9ae6b1 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -8,7 +8,6 @@ supported: - javascript.node - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -42,7 +41,20 @@ Support for `@modelcontextprotocol/server` 2.x requires Sentry JavaScript SDK ve ### Configure Input and Output Recording -MCP inputs and outputs may contain sensitive data. Use `recordInputs` and `recordOutputs` to control collection for a specific server: +By default, the SDK sends the inputs and outputs of your MCP tool calls, prompt retrievals, and resource reads. This gives you rich debugging context. MCP payloads can carry sensitive data, such as tokens, file paths, or private user content. Review what your server handles before you deploy to production. + +The `dataCollection.genAI` option controls this recording globally for both MCP and AI instrumentation: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, +}); +``` + +Use `recordInputs` and `recordOutputs` to control recording for a specific server. These options override the `dataCollection.genAI` settings: ```javascript const server = Sentry.wrapMcpServerWithSentry(mcpServer, { @@ -51,36 +63,17 @@ const server = Sentry.wrapMcpServerWithSentry(mcpServer, { }); ``` -These options override the corresponding `dataCollection.genAI.inputs` and `dataCollection.genAI.outputs` settings and require Sentry JavaScript SDK version `10.33.0` or newer. +The `recordInputs` and `recordOutputs` options require Sentry JavaScript SDK version `10.33.0` or newer. In version 10, the SDK records inputs and outputs only when you set the `dataCollection` option or enable them on the wrapper. Starting with version 11, it records them by default. ## Preserve MCP Spans After the Response -Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. With the static trace lifecycle, Sentry snapshots the request transaction when the response is returned, so MCP spans that finish later may be missing. - -Set `traceLifecycle: "stream"` so the SDK can send each sampled span when it finishes. This changes how spans are delivered; you still need to wrap the MCP server as shown above. Span streaming on Cloudflare requires `@sentry/cloudflare` version `10.49.0` or newer. +Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. The SDK streams spans by default, sending each sampled span as it finishes, so this work is captured without extra configuration. You still need to wrap the MCP server as shown above. -```javascript {filename:index.js} -import * as Sentry from "@sentry/cloudflare"; - -const worker = { - async fetch(request, env, ctx) { - return handleMcpRequest(request, env, ctx); - }, -}; - -export default Sentry.withSentry( - (env) => ({ - dsn: env.SENTRY_DSN, - tracesSampleRate: 1.0, - traceLifecycle: "stream", - }), - worker -); -``` +If you set `traceLifecycle: "static"`, the SDK snapshots the request transaction when the response is returned and MCP spans that finish later are dropped. Remove the option to get them back. -Stream mode sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. See Streamed Spans for the `beforeSendSpan` and `ignoreSpans` configuration. +Streaming sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. Use beforeSendSpan and ignoreSpans instead. If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and wrap the Agent class separately with `instrumentAgentWithSentry` to preserve request and RPC context. Agent instrumentation, MCP server wrapping, and span streaming solve different parts of the setup; none replaces the others. See Agents SDK. @@ -90,7 +83,7 @@ If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and ## Hono on Cloudflare Workers -If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. Set `traceLifecycle: "stream"` in the Hono Sentry middleware so each sampled span is sent when it finishes: +If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. The Hono Sentry middleware uses span streaming by default, so each sampled span can be sent when it finishes: ```javascript {filename:index.js} import { sentry } from "@sentry/hono/cloudflare"; @@ -99,12 +92,11 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, - traceLifecycle: "stream", }) ); ``` -This changes how spans are delivered; it doesn't replace `wrapMcpServerWithSentry`. Stream mode requires `@sentry/hono` and `@sentry/cloudflare` version `10.49.0` or newer. See Streamed Spans for configuration and filtering differences. +You still need `wrapMcpServerWithSentry` to instrument MCP operations. See Streamed Spans for configuration and filtering differences. diff --git a/docs/platforms/javascript/common/metrics/index.mdx b/docs/platforms/javascript/common/metrics/index.mdx index 1e3ad433ef4e9..bbbadb470aeb4 100644 --- a/docs/platforms/javascript/common/metrics/index.mdx +++ b/docs/platforms/javascript/common/metrics/index.mdx @@ -34,13 +34,18 @@ With [Sentry's Application Metrics](/product/metrics/), you can send counters, g ## Integrations - + - `elementTimingIntegration` — Automatically collect render and load timing distribution metrics for key UI elements using the browser's Element Timing API. +- + `bfcacheMetricsIntegration` + + — Track browser back/forward cache (bfcache) hit/miss rate and not-restored + reasons as metrics. diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx index 83aa7dbabd85a..88e22990b520b 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/index.mdx @@ -16,6 +16,8 @@ Make sure to select your framework in the dropdown in the top left corner of the + + Version 11 of the Sentry JavaScript SDK focuses on better OpenTelemetry interoperability, more flexible instrumentation, and better out-of-the-box defaults. The biggest changes are: - **OpenTelemetry interoperability:** The SDK no longer takes over your OpenTelemetry setup. @@ -389,8 +391,24 @@ Whatever the name no longer carries stays on an attribute, in both trace lifecyc | `db` (Mongoose) | `mongoose..` (`mongoose.BlogPost.findOne`) | The operation and collection (`findOne blogposts`), the database namespace, or `mongodb` | | `db` (Supabase) | The query builder call and table (`select(...) from(users)`), or `auth ` | The operation and table (`select users`), or the dotted auth method (`auth.signInWithPassword`) | | `db.query` (Redis, ioredis) | The serialized command with redacted arguments (`set test-key [1 other arguments]`) | The operation and connection (`SET localhost:6379`), the operation and redis function for `FCALL`, or `redis` | - -A few consequences worth checking: +| `browser.*` navigation timing | The document URL | A static phase name, such as `DNS lookup`, `Request`, or `Load event` | +| `function` | Integration-specific, such as `serverAction/updateUser` or `LOADER routes/users.$id` | `code.function.name`, such as `updateUser` or `loader` | +| `function` (Angular `TraceMethod`) | `` or `` | The decorator's `name`, or `Function execution` | +| `function` (SvelteKit) | The route or request path | The wrapped function's name, such as `load` or `GET` | +| `function` (Ember route hooks) | The full route name | The hook name, such as `beforeModel`, `model`, or `setupController` | +| `function` (React Router route hooks) | The route, raw URL path, or fetcher key | The hook name, such as `loader`, `action`, `clientLoader`, or `fetcher` | +| `function` (NestJS `@OnEvent`) | `event user.created` | The event name, such as `user.created` | +| `function` (TanStack Start server functions) | `GET /_serverFn/abc123` | The function name, or `serverFn` until middleware resolves it | +| `function.gcp` | The HTTP method and path, or trigger type | The function name, or `Serverless function execution` | +| `function.aws` | The Lambda function name | Unchanged, with `Serverless function execution` as the fallback | +| `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | ``, `Vue `, `Application Render`, or `init` | The unwrapped component name, or `Component mount`, `Component render`, `Component update`, or `Component unmount` | +| `ui.task` | `runloop` | `UI task` | +| `ui.action.click` | The pageload or navigation span's name | `router.navigation.route.id`, `url.template`, or `http.route`, in that order, or `Click` | +| `ui.interaction.*` | The element's DOM path | The annotated component name, or `Click`, `Hover`, `Drag`, or `Key press` | +| `ui.webvital.lcp` | The LCP element's DOM path | The annotated component name, or `Largest contentful paint` | +| `ui.webvital.cls` | The first layout-shift source's DOM path | The annotated component name, or `Layout shift` | + +In transaction mode, span names remain unchanged. A few consequences worth checking: - `useOperationNameForRootSpan` no longer renames the enclosing root span. The operations stay on that span's `sentry.graphql.operation` attribute. - `graphqlClientIntegration` no longer appends the operation to the outgoing request span name. It's on `graphql.operation.name` and `graphql.operation.type` instead. @@ -404,6 +422,37 @@ A few consequences worth checking: + + +Browser navigation timing spans use these names: + +| Span op | Name | +| ---------------------------------- | ------------------------ | +| `browser.cache` | `Cache lookup` | +| `browser.dns` | `DNS lookup` | +| `browser.connect` | `Connect` | +| `browser.tls_ssl` | `TLS handshake` | +| `browser.redirect` | `Redirect` | +| `browser.request` | `Request` | +| `browser.response` | `Response` | +| `browser.unload_event` | `Unload event` | +| `browser.dom_content_loaded_event` | `DOMContentLoaded event` | +| `browser.load_event` | `Load event` | + +The document URL stays on `url.full` in both trace lifecycles, subject to `dataCollection.urlQueryParams`. Update name-based filters to use that attribute. + +Framework function spans keep the previous name on `sentry.description`. For SvelteKit, this includes `wrapLoadWithSentry`, `wrapServerLoadWithSentry`, `wrapServerRouteWithSentry`, and spans from SvelteKit's own tracing. Match the route on `http.route`, or `url.template` for client-side universal loads, and the request path on `url.path`. + +GCP and Firebase function names come from `FUNCTION_TARGET` or `K_SERVICE`. The function name stays on `faas.name`, trigger details on `gcp.function.context.*`, and HTTP method and path on `http.request.method` and `url.path`. AWS Lambda spans fall back to `Serverless function execution` when neither the invocation context nor `AWS_LAMBDA_FUNCTION_NAME` provides a name. Their `sentry.segment.name.source` is now `component` in both trace lifecycles. + +Component spans keep their original names on `sentry.description`. Vue's `Application Render` becomes `Root`, and Ember's `init` becomes `Component mount`. Update filters matching `` or `Vue ` to use the new name or the description. + +Click idle spans copy `router.navigation.route.id`, `url.template`, `http.route`, `url.path`, and `url.full` from the route span. Event Timing and INP spans keep the DOM path on `browser.web_vital.inp.target` and the annotated component on `ui.component_name`, in both trace lifecycles. Match the target attribute if you previously filtered by DOM path. + +LCP and CLS DOM paths stay on `browser.web_vital.lcp.element` and `browser.web_vital.cls.source.1`. Long task and long animation frame names remain `Main UI thread blocked`. + + + `ignoreSpans` and `tracesSampler` both run when a span **starts**, so a span may not have its final name yet. Match on attributes instead: @@ -439,7 +488,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Area | Before | After | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| Request handlers (Express, Koa, Connect, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | +| Request handlers (Express, Koa, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | | Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | | Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | | Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | @@ -459,7 +508,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Frontend routing | `ui.angular.routing`, `ui.sveltekit.routing`, `ui.ember.transition` | `router` | | React, Vue, and Svelte component lifecycles | `ui.react.mount`/`render`/`update`, `ui.svelte.init`/`update`, Vue `render`/`update`/`mount`/`create`/`activate`/`unmount`/`destroy` | `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | | Angular tracing decorators | `ui.angular.init`, `ui.angular.` | `ui.mount`, `function` | -| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`function`/`ui.mount` | +| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`ui.resolve`/`ui.mount` | | Browser paint entries | `paint` | `browser.paint` | **Databases, cache, and messaging** @@ -541,6 +590,10 @@ Legacy span attributes were replaced by their semantic-convention equivalents. U Transport values change from `ip_tcp` and `ip_udp` to `tcp` and `udp`. HTTP instrumentation reports the protocol as `network.protocol.name` and its version as `network.protocol.version`. +HTTP header attribute names keep their hyphens instead of replacing them with underscores. For example, `http.request.header.user_agent` becomes `http.request.header.user-agent`. Header values are now string arrays, with one entry per value: `['gzip', 'deflate']` replaces `'gzip;deflate'`. + +Cookies are no longer split into attributes per cookie name. `http.request.header.cookie` and `http.request.header.set-cookie` now hold arrays of `name=value` entries in the order sent, such as `['session=[Filtered]', 'theme=dark']`. Sensitive values remain filtered, and Set-Cookie attributes such as `HttpOnly` are still omitted. + On server-side HTTP spans, the `content-length` header is always reported as `http.request.body.size` and `http.response.body.size`, instead of switching to `http.request_body_size_uncompressed` when no encoding was present. @@ -595,9 +648,12 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - On `ui.long_animation_frame` spans, `code.filepath` and `code.function` became `code.file.path` and `code.function.name`. - On `file` spans, `fs_error` became `error.type` and holds the syscall error code (`ENOENT`) instead of the full message. - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. +- Vue Router's `navigation.route.id` became `router.navigation.route.id`, with the same matched route name. +- AWS Lambda spans use `faas.invocation_id` instead of `faas.execution` for the request ID, and `cloud.resource_id` instead of `faas.id` for the invoked function ARN. Lambda `Invoke` spans from `awsIntegration` also use `faas.invocation_id`. +- Koa router and middleware spans no longer set `koa.name`. Use `http.route` for the route and `code.function.name` for the middleware handler. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. -- `SEMANTIC_ATTRIBUTE_SENTRY_SOURCE` (`sentry.source`) was replaced by `SENTRY_SEGMENT_NAME_SOURCE` (`sentry.segment.name.source`), which is only set on the root span. +- `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. @@ -690,6 +746,12 @@ If you used the v10 integration from `@sentry/node-core/light/otlp`: it moved to How the SDK hooks into your app changed, along with the way some frameworks are set up. +### AI Integrations No Longer Trace Non-Inference Operations + +AI integrations now trace model invocations, tool calls, and agent invocations only. They no longer emit spans for Anthropic `messages.countTokens`, `models.retrieve`, or `models.get`, or LangGraph graph compilation with `gen_ai.create_agent`. + +Update dashboards and alerts that reference these spans. LangGraph's `gen_ai.invoke_agent` and `gen_ai.execute_tool` spans are unchanged. + ### Channel-Based Instrumentation Is the Default Instrumentation now runs through diagnostics channels (`orchestrion`) instead of `import-in-the-middle`. It allows instrumentation at run time and build time, which enables tracing on deployment targets like Vercel and Netlify, and on non-Node.js runtimes like Cloudflare, Bun, and Deno. Most setups need no changes. @@ -866,6 +928,8 @@ Sentry.init({ }); ``` +See BrowserSession for lifecycle configuration and session health details. + ### The `DOMException.code` Tag Was Removed Events created from a `DOMException` no longer carry a `DOMException.code` tag, because the `code` property is deprecated in favor of `DOMException.name`, which is already the exception type. Switch searches and alert rules that use the tag to `error.type`. @@ -897,10 +961,10 @@ Several `browserTracingIntegration` options moved to dedicated integrations, or | Removed option | Replacement | | ------------------------------------- | ----------------------------------------------- | -| `_experiments.enableInteractions` | `interactionsIntegration()` | -| `ignorePerformanceApiSpans` | `userTimingIntegration({ ignore: [...] })` | -| `trackFetchStreamPerformance` | `fetchStreamPerformanceIntegration()` | -| `_experiments.enableStandalone*Spans` | Removed, CLS and LCP are no longer configurable | +| `_experiments.enableInteractions` | `interactionsIntegration()` | +| `ignorePerformanceApiSpans` | `userTimingIntegration({ ignore: [...] })` | +| `trackFetchStreamPerformance` | `fetchStreamPerformanceIntegration()` | +| `_experiments.enableStandalone*Spans` | Removed. The trace lifecycle determines how CLS and LCP are sent. | ```js // Before @@ -925,12 +989,17 @@ Sentry.init({ }); ``` -`browserTracingIntegration` no longer captures `performance.mark()` and `performance.measure()` spans by default, and no longer accepts an `_experiments` object at all. The `idleTimeout`, `finalTimeout`, and `childSpanTimeout` options of interaction spans are configured on `interactionsIntegration` now, with the same defaults as before. +`browserTracingIntegration` no longer captures `performance.mark()` and `performance.measure()` spans by default, and no longer accepts an `_experiments` object. Configure `idleTimeout`, `finalTimeout`, and `childSpanTimeout` for interaction spans on `interactionsIntegration`, with the same defaults as before. BrowserTracing's timeout options still control pageload and navigation spans. -Web vitals also changed: +BrowserTracing now automatically adds the WebVitals integration. Web Vitals changed as follows: - CLS and LCP are recorded as measurements on the pageload span, or as dedicated spans in stream mode. -- INP is always sent as a web vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement (built-in dashboards do not need adjustments). +- LCP and CLS spans no longer set `browser.web_vital.lcp.report_event` or `browser.web_vital.cls.report_event`, including when soft-navigation reporting is disabled. Finalization timing is unchanged. Remove filters on these attributes from searches and dashboards. +- When collected, INP is always sent as a Web Vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement. Built-in dashboards do not need adjustments. +- The `enableInp` option is deprecated. To disable INP, use `browserTracingIntegration({ webVitals: { ignore: ["inp"] } })`. The `ignore` array can also contain `"cls"` or `"lcp"` to skip those vitals. +- To configure Web Vitals, pass `webVitals` options to BrowserTracing, or add `webVitalsIntegration()` explicitly. Explicit registration takes precedence over BrowserTracing's `webVitals` and `enableInp` options. +- Soft-navigation vitals are enabled by default in stream mode on browsers that support the Soft Navigations API. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. +- BrowserTracing starts a navigation span after a back/forward-cache restore by default. Set `instrumentBfcacheRestore: false` to disable it. Web Vitals for restores are collected by default in stream mode when `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. Restore vitals carry `browser.navigation.type: bfcache`. Filter by that attribute to analyze restores separately from page loads, since near-instant restores can lower combined aggregates. @@ -942,6 +1011,7 @@ Web vitals also changed: - `denoHttpIntegration` and `denoServeIntegration` honor `ignoreStatusCodes`, using the same default list as `httpIntegration`: incoming requests whose response status falls in `[[401, 404], [301, 303], [305, 399]]` are dropped. Each integration owns the option for the requests it instruments. Pass an empty array to keep everything. The filter only applies in transaction mode, which is why the option is deprecated and will be removed in v12. - The incoming span hooks `onIncomingSpanCreated` and `onIncomingSpanEnd` were renamed to `onSpanCreated` and `onSpanEnd`. `denoHttpIntegration` also accepts `outgoingRequestHook`, `outgoingResponseHook`, and `outgoingRequestApplyCustomAttributes` now. - The default integrations were renamed to match the other SDKs: `DenoAmqplib`, `DenoKoa`, `DenoMongodb`, `DenoMongoose`, `DenoMysql`, and `DenoPostgres` became `Amqplib`, `Koa`, `Mongodb`, `Mongoose`, `Mysql`, and `Postgres`. The old `deno*Integration` exports are kept as deprecated aliases. +- The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now. To disable them, filter out the `Console` integration, and if you set `defaultIntegrations: false`, add `consoleIntegration()` to keep them. @@ -1047,6 +1117,10 @@ The top-level options of `withSentryConfig` that were deprecated in 10.30.0 were | `_experimental.turbopackApplicationKey` | `applicationKey` | | `unstable_sentryWebpackPluginOptions` | Set the plugin options as build options | +### Tunnel Requests Run Through Middleware + +Webpack builds no longer bypass your middleware for `tunnelRoute` requests. If your middleware blocks unauthenticated requests globally, set `tunnelRoute` to a fixed string instead of `true` and exclude that path in your middleware `matcher` so Sentry events can reach the tunnel. + ### Unified `reactComponentAnnotation` Option React component annotation is configured through a single top-level option that applies to webpack and Turbopack builds: @@ -1175,6 +1249,18 @@ The `assets` and `filesToDeleteAfterUpload` fields moved into `sourcemaps`. Deploys that the bundler plugins create on Vercel use `VERCEL_TARGET_ENV` as their environment now, instead of `vercel-production` and `vercel-preview`. That matches the runtime default. If your events use a different environment, set `release.deploy.env` to the same value, or set `release.deploy` to `false` to opt out. +### The webpack Plugin Entry Point Changed + +The Sentry webpack plugin requires webpack **5.1** or newer. The `@sentry/bundler-plugins/webpack5` entry point was removed. Update imports to `@sentry/bundler-plugins/webpack`: + +```js +// Before +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5"; + +// After +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack"; +``` + ### The `unstable_` Bundler Plugin Options Were Removed The `unstable_sentry*PluginOptions` escape hatch was removed from every SDK, because the Sentry bundler plugins now live in the SDK monorepo and release in lockstep. Every supported plugin option is a first-class build option: @@ -1238,12 +1324,33 @@ The generated client snippet always includes the Replay integration with default `public/instrument.server.[ext]` is no longer supported. Move the file next to `nuxt.config.ts` and rename it to `sentry.server.config.[ext]`. Its contents don't change. -After the rename, the SDK emits `.output/server/sentry.server.config.mjs` for you to preload: +After the rename, the SDK [bundles the file](#the-nuxt-server-config-is-bundled) into the Nitro server build. You no longer preload it with `--import`. + +### The Nuxt Server Config Is Bundled + +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. Instrumentation happens at build time, so you no longer preload the config file. Remove the `--import` flag from your start commands: ```bash +# Before node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +node .output/server/index.mjs +nuxt dev ``` +Existing start commands continue to work. The SDK still writes a file to the old path, but this file only prints a reminder to remove the flag. If you preload your own file that calls `Sentry.init()`, that call initializes the SDK and the bundled initialization is skipped. + +The SDK doesn't initialize while Nitro prerenders pages at build time, so builds no longer send events. + +Because a preload is no longer needed, these Nuxt module options are deprecated and will be removed in the next major version. Remove them from the `sentry` options in your `nuxt.config.ts`: + +- `autoInjectServerSentry` (`"top-level-import"` and `"experimental_dynamic-import"`) +- `experimental_entrypointWrappedFunctions` + +While `autoInjectServerSentry` is set, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. To learn more, see [Server-Side Installation](/platforms/javascript/guides/nuxt/install/). + @@ -1302,6 +1409,8 @@ import { sentryRemixVitePlugin } from "@sentry/remix/vite"; The plugin applies the build-time instrumentation transform now. If you added `sentryOrchestrionPlugin()` from `@sentry/server-utils/orchestrion/vite` yourself, remove it. Opt out with `sentryRemixVitePlugin({ buildTimeInstrumentation: false })`. +The plugin also injects debug IDs and uploads source maps when you pass `org`, `project`, and `authToken`. Disable source-map processing with `sentryRemixVitePlugin({ sourcemaps: { disable: true } })`. + `captureActionFormDataKeys` is an integration-level override now, so it opts in on its own and no longer needs `dataCollection.httpBodies` to include `'incomingRequest'`: ```js @@ -1352,7 +1461,7 @@ import type { BrowserClientReplayOptions } from "@sentry/core/browser"; ### Browser -- The `console` option of `breadcrumbsIntegration` was removed. Use `consoleIntegration` to capture console breadcrumbs. +- The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now. To disable them, filter out the `Console` integration, and if you set `defaultIntegrations: false`, add `consoleIntegration()` to keep them. - AI integrations are no longer available in the browser SDK. They remain available in the server-side SDKs. diff --git a/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx b/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx index 5a4a3bb2c4302..3f95c52b9c0b4 100644 --- a/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx +++ b/docs/platforms/javascript/common/migration/v10-to-v11/interactive.mdx @@ -16,6 +16,8 @@ Make sure to select your framework in the dropdown in the top left corner of the + + Version 11 of the Sentry JavaScript SDK focuses on better OpenTelemetry interoperability, more flexible instrumentation, and better out-of-the-box defaults. It raises the minimum versions of Node.js, TypeScript, and several frameworks. We recommend upgrading to the most recent 10.x release first, because most of what v11 removes is already deprecated there. diff --git a/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx b/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx index f2c096e76c4f3..2f5fad72272a7 100644 --- a/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx +++ b/docs/platforms/javascript/common/migration/v7-to-v8/v8-opentelemetry.mdx @@ -9,7 +9,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx index 75417420afe61..3e104a021c163 100644 --- a/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup.mdx @@ -1,6 +1,7 @@ --- -title: Using Your Existing OpenTelemetry Setup -description: "Learn how to use your existing custom OpenTelemetry setup with Sentry." +title: Use Your Own OpenTelemetry Pipeline +description: "Connect your existing OpenTelemetry pipeline to Sentry while keeping control of tracing." +sidebar_order: 1 supported: - javascript.nextjs - javascript.node @@ -9,7 +10,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -27,167 +27,54 @@ supported: - javascript.tanstackstart-react notSupported: - javascript -sidebar_order: 0 --- - +Keep your own provider, context manager, propagator, instrumentation, and exporters when OpenTelemetry manages tracing. Add `Sentry.openTelemetryIntegration()` to associate Sentry errors, logs, metrics, and cron check-ins with the active OpenTelemetry span. -Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry SDK. +Set `enableOpenTelemetrySetup: false` and leave both `tracesSampleRate` and `tracesSampler` unset. This disables Sentry tracing and prevents duplicate spans for the same operations. Sentry's instrumentation still isolates requests and captures errors. -Setting `skipOpenTelemetrySetup: true` disables the Sentry SDK's automatic OpenTelemetry configuration, **requiring** you to perform the setup manually. For example, to ensure errors are correctly associated with their scope, you must add the `SentryContextManager` to your OpenTelemetry setup. You can find details on the required manual setup further down on this page. +Initialize your OpenTelemetry provider before calling `Sentry.init()`. -If you are looking to simply add individual OpenTelemetry instrumentation to your Sentry setup, you should read Adding Additional OpenTelemetry Instrumentation instead. +## Send OpenTelemetry Spans to Sentry - +Add an OTLP exporter to your existing provider. Install `@opentelemetry/exporter-trace-otlp-http` if you do not already use it. `Sentry.getOtlpTracesEndpoint()` supplies the endpoint URL and authentication headers for your DSN. - - +This example uses `NodeTracerProvider`. Add the same span processor to `spanProcessors` if you use `NodeSDK` instead. Keep your existing sampler, propagator, context manager, and instrumentation; do not register a second provider. -If you don't need the full `@sentry/node` SDK and want a simpler way to bridge your existing OpenTelemetry setup with Sentry, consider using lightweight mode with the OTLP integration instead. It requires significantly less manual wiring. +```javascript {filename: instrument.mjs} +import * as Sentry from "___SDK_PACKAGE___"; +import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"; +import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"; +import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"; - - +const dsn = "___PUBLIC_DSN___"; +const endpoint = Sentry.getOtlpTracesEndpoint(dsn); - +if (!endpoint) { + throw new Error("Could not parse the Sentry DSN"); +} -## Using Sentry for Error Monitoring Only - -If you have a custom OpenTelemetry setup and only want to use Sentry for error monitoring, you can skip adding the `SentrySpanProcessor`. You'll still need to add the `SentryContextManager`, `SentryPropagator`, and `SentrySampler` to your setup even if you don't want to send any tracing data to Sentry. Read on to learn why this is needed. - -In order for the Sentry SDK to work as expected, and for it to be in sync with OpenTelemetry, we need a few components to be in place. - -**Components needed for Sentry to work correctly:** - -- **SentryContextManager**: Ensures that the OpenTelemetry context is in sync with Sentry, for example to correctly isolate data between simultaneous requests. -- **SentrySampler**: Ensures that the Sentry `tracesSampleRate` is respected. Even if you don't use Sentry for tracing, you'll still need this in order for trace propagation to work as expected. Read [Using a Custom Sampler](./#using-a-custom-sampler) if you want to use a custom sampler. -- **SentryPropagator**: Ensures that trace propagation works correctly. -- [Required Instrumentation](./#required-instrumentation): Ensures that trace propagation works correctly. - -**Additional components needed to also use Sentry for tracing:** - -- **SentrySpanProcessor**: Ensures that spans are correctly sent to Sentry. - - - Trace propagation is needed for Sentry to automatically connect services - together. (For example, if you want to connect the frontend and backend, or - different backend services.) This makes it possible to see related errors - across services.{" "} - - Learn more about Trace Propagation. - - - -The following code snippet shows how to set up Sentry for error monitoring only: - - - -## Required Instrumentation - -By default, Sentry will register OpenTelemetry instrumentation to automatically capture spans for traces spanning incoming and outgoing HTTP requests, DB queries, and more. - -If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configuration), only a minimal amount of OpenTelemetry instrumentation will be registered. This includes the following: - -{/* prettier-ignore-start */} - -- A Sentry-specific HTTP instrumentation that handles request isolation and trace propagation. This can work in parallel with [@opentelemetry/instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http), if you register it. -- [nativeNodeFetchIntegration](/platforms/javascript/guides/node/configuration/integrations/nodefetch/) registers [opentelemetry-instrumentation-fetch-node](https://www.npmjs.com/package/opentelemetry-instrumentation-fetch-node) which is needed for trace propagation. - -{/* prettier-ignore-end */} - - - - If tracing is not enabled, performance instrumentations will not be - registered but they will still be included in the bundle. If you want to - reduce the bundle size or used dependencies, you can also{" "} - - Set up Sentry without Performance Integrations - - - - -These are needed to make sure that trace propagation works correctly. - -If you want to add your own http/node-fetch instrumentation, you have to follow the following steps: - -### Custom HTTP Instrumentation - - - -You can add your own `@opentelemetry/instrumentation-http` instance in your OpenTelemetry setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`. You can also set `tracePropagation: false` to prevent Sentry from injecting trace headers, letting your OpenTelemetry setup handle propagation instead: - - - ```javascript - const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: [Sentry.httpIntegration({ spans: false, tracePropagation: false })], -}); - ``` - - - -```javascript - const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: (integrations) => - // Also filter out the BunServer integration to avoid emitting duplicated spans from Sentry AND your custom OTel instrumentation - integrations.filter((i) => i.name !== "BunServer") +const provider = new NodeTracerProvider({ + spanProcessors: [ + new BatchSpanProcessor(new OTLPTraceExporter(endpoint)), + // Keep any other span processors you already use. + ], }); -``` - - -It's important that `httpIntegration` is still registered this way to ensure that the Sentry SDK can correctly isolate requests, for example when capturing errors. -### Custom Node Fetch Instrumentation +provider.register(); -If tracing is disabled, the Node Fetch instrumentation will not emit any spans. In this scenario, it will only inject sentry-specific trace propagation headers. You are free to add your own Node Fetch instrumentation on top of this which may emit spans as you like. - -If your OpenTelemetry setup already handles trace propagation for fetch requests, you can set `tracePropagation: false` to prevent Sentry from injecting duplicate trace headers: - -```javascript -const sentryClient = Sentry.init({ - dsn: "___DSN___", - skipOpenTelemetrySetup: true, - integrations: [ - Sentry.nativeNodeFetchIntegration({ tracePropagation: false }), - ], +Sentry.init({ + dsn, + enableOpenTelemetrySetup: false, + // Leave tracesSampleRate and tracesSampler unset. OpenTelemetry owns tracing. + integrations: [Sentry.openTelemetryIntegration()], }); ``` -## Using a Custom Sampler - -While you can use your own sampler, we recommend that you use the `SentrySampler`. This will ensure that the correct subset of traces will be sent to Sentry, based on your `tracesSampleRate`. It will also ensure that all other Sentry features like trace propagation work as expected. If you do need to use your own sampler, make sure to wrap your `SamplingResult` with our `wrapSamplingDecision` method like in the example below: - - - - - -It is recommended registering your own ESM loader hooks when you have a complete custom OpenTelemetry setup, first and foremost because it makes the most sense architecturally. -You likely went through the effort to set up OpenTelemetry by itself and now you want to add Sentry to your application without messing with your OpenTelemetry setup. - -Additionally, there are a few pitfalls that can very simply be avoided by registering your own hooks: +## Use Sentry for Error Monitoring Only -- Registering loader hooks multiple times might result in duplicated spans being created. [More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961) -- OpenTelemetry instrumentation in ESM is very sensitive as to _when_ it is added relative to _when_ the loader hooks are registered. - The control over this should stay with the owner of the OpenTelemetry setup and not the Sentry SDK. +If your traces go elsewhere, keep your existing OpenTelemetry exporter and omit the Sentry OTLP exporter from the example above. The `Sentry.init()` configuration stays the same. `openTelemetryIntegration()` links Sentry errors to the active OpenTelemetry trace without sending spans to Sentry. - +## Configure Sampling - - - - Learn more about ESM installation methods. - - - +Configure sampling on your OpenTelemetry provider. Sentry's `tracesSampleRate` and `tracesSampler` do not control spans exported over OTLP. Use an OpenTelemetry sampler or your own implementation of its `Sampler` interface. diff --git a/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx new file mode 100644 index 0000000000000..772c05e4855cf --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/custom-setup__v10.x.mdx @@ -0,0 +1,201 @@ +--- +title: Using Your Existing OpenTelemetry Setup +description: "Learn how to use your existing custom OpenTelemetry setup with Sentry." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +sidebar_order: 0 +--- + + + +Use this guide when you already have a completely custom OpenTelemetry setup or when you intend to add a custom OpenTelemetry setup next to the Sentry SDK. + +Setting `skipOpenTelemetrySetup: true` disables the Sentry SDK's automatic OpenTelemetry configuration, **requiring** you to perform the setup manually. For example, to ensure errors are correctly associated with their scope, you must add the `SentryContextManager` to your OpenTelemetry setup. You can find details on the required manual setup further down on this page. + +If you are looking to simply add individual OpenTelemetry instrumentation to your Sentry setup, you should read Adding Additional OpenTelemetry Instrumentation instead. + + + + + + + + + + + +## Using Sentry for Error Monitoring Only + +If you have a custom OpenTelemetry setup and only want to use Sentry for error monitoring, you can skip adding the `SentrySpanProcessor`. You'll still need to add the `SentryContextManager`, `SentryPropagator`, and `SentrySampler` to your setup even if you don't want to send any tracing data to Sentry. Read on to learn why this is needed. + +In order for the Sentry SDK to work as expected, and for it to be in sync with OpenTelemetry, we need a few components to be in place. + +**Components needed for Sentry to work correctly:** + +- **SentryContextManager**: Ensures that the OpenTelemetry context is in sync with Sentry, for example to correctly isolate data between simultaneous requests. +- **SentrySampler**: Ensures that the Sentry `tracesSampleRate` is respected. Even if you don't use Sentry for tracing, you'll still need this in order for trace propagation to work as expected. Read [Using a Custom Sampler](#using-a-custom-sampler) if you want to use a custom sampler. +- **SentryPropagator**: Ensures that trace propagation works correctly. +- [Required Instrumentation](#required-instrumentation): Ensures that trace propagation works correctly. + +**Additional components needed to also use Sentry for tracing:** + +- **SentrySpanProcessor**: Ensures that spans are correctly sent to Sentry. + + + Trace propagation is needed for Sentry to automatically connect services + together. (For example, if you want to connect the frontend and backend, or + different backend services.) This makes it possible to see related errors + across services.{" "} + + Learn more about Trace Propagation. + + + +The following code snippet shows how to set up Sentry for error monitoring only: + + + + + + + + + +## Required Instrumentation + +By default, Sentry will register OpenTelemetry instrumentation to automatically capture spans for traces spanning incoming and outgoing HTTP requests, DB queries, and more. + +If tracing is not enabled (no `tracesSampleRate` is defined in the SDK configuration), only a minimal amount of OpenTelemetry instrumentation will be registered. This includes the following: + +{/* prettier-ignore-start */} + +- A Sentry-specific HTTP instrumentation that handles request isolation and trace propagation. This can work in parallel with [@opentelemetry/instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http), if you register it. +- [nativeNodeFetchIntegration](/platforms/javascript/guides/node/configuration/integrations/nodefetch/) registers [opentelemetry-instrumentation-fetch-node](https://www.npmjs.com/package/opentelemetry-instrumentation-fetch-node) which is needed for trace propagation. + +{/* prettier-ignore-end */} + + + + If tracing is not enabled, performance instrumentations will not be + registered but they will still be included in the bundle. If you want to + reduce the bundle size or used dependencies, you can also{" "} + + Set up Sentry without Performance Integrations + + + + +These are needed to make sure that trace propagation works correctly. + +If you want to add your own http/node-fetch instrumentation, you have to follow the following steps: + +### Custom HTTP Instrumentation + + + +You can add your own `@opentelemetry/instrumentation-http` instance in your OpenTelemetry setup. However, in this case, you need to disable span creation in Sentry's `httpIntegration`. You can also set `tracePropagation: false` to prevent Sentry from injecting trace headers, letting your OpenTelemetry setup handle propagation instead: + + + ```javascript + const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: [Sentry.httpIntegration({ spans: false, tracePropagation: false })], +}); + ``` + + + +```javascript + const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: (integrations) => + // Also filter out the BunServer integration to avoid emitting duplicated spans from Sentry AND your custom OTel instrumentation + integrations.filter((i) => i.name !== "BunServer") +}); +``` + + +It's important that `httpIntegration` is still registered this way to ensure that the Sentry SDK can correctly isolate requests, for example when capturing errors. + +### Custom Node Fetch Instrumentation + +If tracing is disabled, the Node Fetch instrumentation will not emit any spans. In this scenario, it will only inject sentry-specific trace propagation headers. You are free to add your own Node Fetch instrumentation on top of this which may emit spans as you like. + +If your OpenTelemetry setup already handles trace propagation for fetch requests, you can set `tracePropagation: false` to prevent Sentry from injecting duplicate trace headers: + +```javascript +const sentryClient = Sentry.init({ + dsn: "___DSN___", + skipOpenTelemetrySetup: true, + integrations: [ + Sentry.nativeNodeFetchIntegration({ tracePropagation: false }), + ], +}); +``` + +## Using a Custom Sampler + +While you can use your own sampler, we recommend that you use the `SentrySampler`. This will ensure that the correct subset of traces will be sent to Sentry, based on your `tracesSampleRate`. It will also ensure that all other Sentry features like trace propagation work as expected. If you do need to use your own sampler, make sure to wrap your `SamplingResult` with our `wrapSamplingDecision` method like in the example below: + + + + + + + + + + + +It is recommended registering your own ESM loader hooks when you have a complete custom OpenTelemetry setup, first and foremost because it makes the most sense architecturally. +You likely went through the effort to set up OpenTelemetry by itself and now you want to add Sentry to your application without messing with your OpenTelemetry setup. + +Additionally, there are a few pitfalls that can very simply be avoided by registering your own hooks: + +- Registering loader hooks multiple times might result in duplicated spans being created. [More details.](https://github.com/getsentry/sentry-javascript/issues/14065#issuecomment-2435546961) +- OpenTelemetry instrumentation in ESM is very sensitive as to _when_ it is added relative to _when_ the loader hooks are registered. + The control over this should stay with the owner of the OpenTelemetry setup and not the Sentry SDK. + + + + + + + Learn more about ESM installation methods. + + + diff --git a/docs/platforms/javascript/common/opentelemetry/index.mdx b/docs/platforms/javascript/common/opentelemetry/index.mdx index fbde8fe769b4c..71ffbb03384e9 100644 --- a/docs/platforms/javascript/common/opentelemetry/index.mdx +++ b/docs/platforms/javascript/common/opentelemetry/index.mdx @@ -11,7 +11,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -29,13 +28,10 @@ supported: - javascript.tanstackstart-react notSupported: - javascript -beta: true --- -The Sentry SDK uses [OpenTelemetry](https://opentelemetry.io/) under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up by Sentry without any further configuration. +The Sentry JavaScript SDK creates and sends spans without an OpenTelemetry pipeline. For the default setup, see Tracing. -To start capturing traces and spans, set up Tracing and Performance Monitoring with your Sentry SDK. If you don't use tracing, Sentry still connects to OpenTelemetry under the hood to ensure that context isolation and trace propagation works correctly. - -By default, Sentry will automatically set up OpenTelemetry for you, but you can also use your own OpenTelemetry setup. Read the guides below to learn how to use a custom OpenTelemetry setup or how to get the most out of the Sentry and OpenTelemetry integration. +If your application also uses OpenTelemetry, choose a setup based on which SDK manages tracing: diff --git a/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx new file mode 100644 index 0000000000000..948294dfcaf6f --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/index__v10.x.mdx @@ -0,0 +1,40 @@ +--- +title: OpenTelemetry Support +description: "Learn how to use OpenTelemetry with Sentry." +sidebar_order: 14 +sidebar_section: configuration +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +beta: true +--- + +The Sentry SDK uses [OpenTelemetry](https://opentelemetry.io/) under the hood. This means that any OpenTelemetry instrumentation that emits spans will automatically be picked up by Sentry without any further configuration. + +To start capturing traces and spans, set up Tracing and Performance Monitoring with your Sentry SDK. If you don't use tracing, Sentry still connects to OpenTelemetry under the hood to ensure that context isolation and trace propagation works correctly. + +By default, Sentry will automatically set up OpenTelemetry for you, but you can also use your own OpenTelemetry setup. Read the guides below to learn how to use a custom OpenTelemetry setup or how to get the most out of the Sentry and OpenTelemetry integration. + +- Using Your Existing OpenTelemetry Setup +- Using OpenTelemetry APIs diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx index 40bc8d5179743..cda9fd03bf032 100644 --- a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis.mdx @@ -1,6 +1,7 @@ --- -title: Using OpenTelemetry APIs -description: "Learn how to use OpenTelemetry APIs with Sentry." +title: Capture Spans from OpenTelemetry APIs +description: "Let Sentry capture and send spans created by OpenTelemetry APIs." +sidebar_order: 0 supported: - javascript.nextjs - javascript.node @@ -9,7 +10,6 @@ supported: - javascript.aws-lambda - javascript.azure-functions - javascript.bun - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -27,127 +27,31 @@ supported: - javascript.tanstackstart-react notSupported: - javascript -sidebar_order: 1 --- -Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any spans started using the Sentry SDK will be automatically propagated to OpenTelemetry. +To capture spans that your code or a library creates through `@opentelemetry/api`, set `enableOpenTelemetrySetup: true`. Sentry registers an OpenTelemetry-compatible tracer provider, context manager, and propagator. Spans created through `@opentelemetry/api` become native Sentry spans. Sentry's tracing configuration controls sampling and export. -## Adding Additional OpenTelemetry Instrumentation - -While the Sentry SDK includes some OpenTelemetry instrumentation out of the box, you may want to add additional instrumentation to your application. This can be done by registering the instrumentation through OpenTelemetry like the example below: - -```javascript {tabTitle: ESM} {12-13} -import * as Sentry from "@sentry/node"; -import { - GenericPoolInstrumentation, -} from "@opentelemetry/instrumentation-generic-pool"; +```javascript +import * as Sentry from "___SDK_PACKAGE___"; +import { trace } from "@opentelemetry/api"; Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample + dsn: "___PUBLIC_DSN___", + enableOpenTelemetrySetup: true, tracesSampleRate: 1.0, - - // Add additional OpenTelemetry instrumentation: - openTelemetryInstrumentations: [new GenericPoolInstrumentation()], -}); -``` -```javascript {tabTitle: CJS} {12-13} -const Sentry = require("@sentry/node"); -const { - GenericPoolInstrumentation, -} = require("@opentelemetry/instrumentation-generic-pool"); - -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, - - // Add additional OpenTelemetry instrumentation: - openTelemetryInstrumentations: [new GenericPoolInstrumentation()], -}); -``` - - - It is possible to add instrumentations via `registerInstrumentations()` from - `@opentelemetry/instrumentation`. However, with ESM (`import`/`export` syntax) - you need to be careful to do so before importing any modules that should be - instrumented. - -As a rule of thumb, `registerInstrumentations()` should be called right after, and in the same context as registering ESM Loaders. - - - -## Using an OpenTelemetry Tracer - -We recommend using `Sentry.startSpan()` and related APIs to create spans, but you can also create spans using native OpenTelemetry APIs. - -You can access the tracer Sentry uses via `client.tracer` and then create spans with OpenTelemetry APIs, as shown below: - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -const tracer = Sentry.getClient()?.tracer; -// Now you can use native APIs on the tracer: -tracer.startActiveSpan("span name", () => { - // measure something -}); -``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); - -const tracer = Sentry.getClient()?.tracer; -// Now you can use native APIs on the tracer: -tracer.startActiveSpan("span name", () => { - // measure something }); -``` - -You can also use any other tracer. All OpenTelemetry spans will be picked up by Sentry automatically. - -## Modifying the default OpenTelemetry TracerProvider - -You can access the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -const provider = Sentry.getClient()?.traceProvider; -``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); - -const provider = Sentry.getClient()?.traceProvider; -``` -## Adding Additional Span Processors +const tracer = trace.getTracer("my-app"); -You can add additional span processors to the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. - -```javascript {tabTitle: ESM} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, - - // Add additional OpenTelemetry SpanProcessors: - openTelemetrySpanProcessors: [new MySpanProcessor()], +tracer.startActiveSpan("process-order", (span) => { + try { + // Your synchronous work here. + } finally { + span.end(); + } }); ``` -```javascript {tabTitle: CJS} -const Sentry = require("@sentry/node"); -Sentry.init({ - dsn: "___DSN___", - - // The SentrySampler will use this to determine which traces to sample - tracesSampleRate: 1.0, +Initialize Sentry before the application creates spans. This setup sends spans through Sentry's transport; it does not create an OTLP exporter. If your application already registers an OpenTelemetry provider, use your own OpenTelemetry pipeline instead. Sentry will not replace an existing provider. - // Add additional OpenTelemetry SpanProcessors: - openTelemetrySpanProcessors: [new MySpanProcessor()], -}); -``` +Most server SDKs leave `enableOpenTelemetrySetup` off by default. The `@sentry/nextjs` and `@sentry/sveltekit` SDKs enable it by default to capture spans emitted by those frameworks. diff --git a/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx new file mode 100644 index 0000000000000..d5238d7e9590a --- /dev/null +++ b/docs/platforms/javascript/common/opentelemetry/using-opentelemetry-apis__v10.x.mdx @@ -0,0 +1,151 @@ +--- +title: Using OpenTelemetry APIs +description: "Learn how to use OpenTelemetry APIs with Sentry." +supported: + - javascript.nextjs + - javascript.node + - javascript.eve + - javascript.aws-lambda + - javascript.azure-functions + - javascript.bun + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.nitro + - javascript.nuxt + - javascript.solidstart + - javascript.sveltekit + - javascript.astro + - javascript.remix + - javascript.react-router + - javascript.tanstackstart-react +notSupported: + - javascript +sidebar_order: 1 +--- + +Sentry supports OpenTelemetry APIs out of the box. Any spans started using OpenTelemetry APIs will be automatically captured by Sentry, while any spans started using the Sentry SDK will be automatically propagated to OpenTelemetry. + +## Adding Additional OpenTelemetry Instrumentation + +While the Sentry SDK includes some OpenTelemetry instrumentation out of the box, you may want to add additional instrumentation to your application. This can be done by registering the instrumentation through OpenTelemetry like the example below: + +```javascript {tabTitle: ESM} {12-13} +import * as Sentry from "@sentry/node"; +import { + GenericPoolInstrumentation, +} from "@opentelemetry/instrumentation-generic-pool"; + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry instrumentation: + openTelemetryInstrumentations: [new GenericPoolInstrumentation()], +}); +``` +```javascript {tabTitle: CJS} {12-13} +const Sentry = require("@sentry/node"); +const { + GenericPoolInstrumentation, +} = require("@opentelemetry/instrumentation-generic-pool"); + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry instrumentation: + openTelemetryInstrumentations: [new GenericPoolInstrumentation()], +}); +``` + + + It is possible to add instrumentations via `registerInstrumentations()` from + `@opentelemetry/instrumentation`. However, with ESM (`import`/`export` syntax) + you need to be careful to do so before importing any modules that should be + instrumented. + +As a rule of thumb, `registerInstrumentations()` should be called right after, and in the same context as registering ESM Loaders. + + + +## Using an OpenTelemetry Tracer + +We recommend using `Sentry.startSpan()` and related APIs to create spans, but you can also create spans using native OpenTelemetry APIs. + +You can access the tracer Sentry uses via `client.tracer` and then create spans with OpenTelemetry APIs, as shown below: + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +const tracer = Sentry.getClient()?.tracer; +// Now you can use native APIs on the tracer: +tracer.startActiveSpan("span name", () => { + // measure something +}); +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +const tracer = Sentry.getClient()?.tracer; +// Now you can use native APIs on the tracer: +tracer.startActiveSpan("span name", () => { + // measure something +}); +``` + +You can also use any other tracer. All OpenTelemetry spans will be picked up by Sentry automatically. + +## Modifying the default OpenTelemetry TracerProvider + +You can access the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +const provider = Sentry.getClient()?.traceProvider; +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +const provider = Sentry.getClient()?.traceProvider; +``` + +## Adding Additional Span Processors + +You can add additional span processors to the tracer provider set up by Sentry when using Sentry's default OpenTelemetry instrumentation. + +```javascript {tabTitle: ESM} +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry SpanProcessors: + openTelemetrySpanProcessors: [new MySpanProcessor()], +}); +``` +```javascript {tabTitle: CJS} +const Sentry = require("@sentry/node"); + +Sentry.init({ + dsn: "___DSN___", + + // The SentrySampler will use this to determine which traces to sample + tracesSampleRate: 1.0, + + // Add additional OpenTelemetry SpanProcessors: + openTelemetrySpanProcessors: [new MySpanProcessor()], +}); +``` diff --git a/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx b/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx index 47620afa80fdd..3a601b12587de 100644 --- a/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx +++ b/docs/platforms/javascript/common/sourcemaps/uploading/hosting-publicly.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx b/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx index 9a0469fb29ebb..c73be7a8d2063 100644 --- a/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx +++ b/docs/platforms/javascript/common/tracing/distributed-tracing/dealing-with-cors-issues/index.mdx @@ -8,7 +8,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/index.mdx b/docs/platforms/javascript/common/tracing/index.mdx index 91064cd58bc00..4e9a5908067a1 100644 --- a/docs/platforms/javascript/common/tracing/index.mdx +++ b/docs/platforms/javascript/common/tracing/index.mdx @@ -95,7 +95,7 @@ You can also manually start spans to instrument specific parts of your code. Thi - Sending Span Metrics: Learn how to capture metrics on your spans - + ## Replay Linking @@ -133,7 +133,7 @@ Instead, neither `tracesSampleRate` nor `tracesSampler` should be defined in you ## Related Features -- Session Replay — Traces appear in the Replay timeline, showing performance data alongside the user's actions. +- Session Replay — Traces appear in the Replay timeline, showing performance data alongside the user's actions. - Logs — Logs emitted during a trace are automatically linked, giving you diagnostic context for each operation. ## Tracing Next Steps diff --git a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx index 1ed43c3321d85..7b17dd9cfd265 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/automatic-instrumentation.mdx @@ -29,7 +29,7 @@ Once you enable tracing, the SDK automatically captures performance data without | **Page loads** | Full page load performance | LCP, CLS, TTFB | | **Navigations** | Client-side route changes | Duration, Web Vitals | | **HTTP requests** | All fetch/XHR calls | Duration, status, URL | -| **User interactions** | Clicks, inputs that trigger work | INP (responsiveness) | +| **Responsiveness** | Interaction to Next Paint | INP | | **Long tasks** | Main thread blocking > 50ms | Duration, attribution | @@ -42,7 +42,7 @@ Once you enable tracing, the SDK automatically captures performance data without ## Disable Automatic Instrumentation -For Astro version `3.5.2` and up, you can optionally disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: +You can optionally disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: ```javascript {filename:astro.config.mjs} import { defineConfig } from "astro/config"; @@ -118,36 +118,56 @@ Exclude requests from tracing, such as health checks or analytics pings: -## Web Vitals & Interactions - -### Interaction to Next Paint (INP) + - + -Automatically captures [INP](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/#interaction-to-next-paint-inp) events to measure responsiveness. Results appear in the [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) module. +## Web Vitals & Interactions -Default: `true` in SDK 8.x+, `false` in 7.x. +BrowserTracing automatically captures Web Vitals. To capture clicks and the work they trigger as spans, add the Interactions integration. - +### Configure Web Vitals -As of SDK version 10.0.0, First Input Delay (FID) is no longer reported. Google deprecated FID in favor of INP, which provides a more comprehensive measure of responsiveness. If you have alerts or dashboards based on FID, update them to use INP instead. + - +Configure which Web Vitals BrowserTracing collects. For example, to disable INP collection: +If you explicitly add `webVitalsIntegration()`, configure these options on that integration instead. See WebVitals for details and browser support requirements. + - +### Interaction to Next Paint (INP) + +BrowserTracing automatically captures [INP](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/#interaction-to-next-paint-inp) to measure responsiveness. Results appear in the [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) module. -Sample rate for INP spans, applied on top of `tracesSampleRate`. For example, `interactionsSampleRate: 0.5` with `tracesSampleRate: 0.1` results in 5% of interactions captured. + + +Enable or disable INP collection. Defaults to `true` in SDK 8 and later, and `false` in SDK 7.x. + +Deprecated in SDK version 11. Use `webVitals: { ignore: ["inp"] }` to disable INP. Explicitly adding `webVitalsIntegration()` takes precedence over this option. + + + + ## Advanced Options +These timeouts control pageload and navigation spans. + + + + +Configure timeouts for click-triggered work on the Interactions integration separately. + + + + Time in ms to wait before finishing a pageload/navigation span when no unfinished child spans remain. @@ -182,6 +202,20 @@ Enable/disable automatic `navigation` span creation on history changes. + + + + + +Start a navigation span when the page is restored from the back/forward cache. This starts a new trace for activity after the restore. It is independent of `instrumentNavigation`. + +Web Vitals for restored pages are collected by default in stream mode. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. See WebVitals for requirements. + + + + + + Enable/disable automatic spans for long tasks (main thread blocking > 50ms). @@ -250,21 +284,24 @@ Sentry.init({ - + + -Ignore spans created from `performance.mark()` and `performance.measure()`: +Use the UserTiming integration to capture `performance.mark()` and `performance.measure()` entries. To ignore entries by name: ```javascript Sentry.init({ integrations: [ - Sentry.browserTracingIntegration({ - ignorePerformanceApiSpans: ["myMeasurement", /myMark/], + Sentry.browserTracingIntegration(), + Sentry.userTimingIntegration({ + ignore: ["myMeasurement", /myMark/], }), ], }); ``` - + + diff --git a/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx index 04cf8593c1dbd..562350449bb05 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/caches-module.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index 3bb8112b3e6ed..d1a0807e2a52e 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -205,14 +205,15 @@ if (span) { ### Adding attributes to all spans To add an attribute to all spans, use the `beforeSendSpan` callback. -Note that the property names differ between transaction mode (the default) and stream mode: +In stream mode, the callback receives span attributes in `span.attributes`. +If you opt into transaction mode with `traceLifecycle: 'static'`, wrap the callback with `Sentry.withStaticSpan()` and use `span.data` instead: -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ // dsn, ... beforeSendSpan(span) { - span.data = { - ...span.data, + span.attributes = { + ...span.attributes, "environment.region": "us-west-2", }; @@ -221,17 +222,18 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ // dsn, ... - beforeSendSpan(span) { - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.data = { + ...span.data, "environment.region": "us-west-2", }; return span; - }, + }), }); ``` @@ -256,12 +258,9 @@ if (span) { } ``` -Prior to v8.39.0, you had to use `span.updateName('New Name')`, which had some limitations in `@sentry/node` and SDKs depending on it (for example, `@sentry/nextjs`): - -- Spans with `http.method` or `http.request.method` attributes would automatically have their name set to the method + the URL path. -- Spans with `db.system` attributes would automatically have their name set to the system + the statement. +Automatically instrumented spans use attributes such as `http.request.method` and `db.system.name` to derive their names. These names are low-cardinality. Raw URL paths, full query statements, and other request-specific details stay in attributes instead of the span name. -Using `Sentry.updateSpanName()` ensures that the name is updated correctly and no longer overwritten in these cases. +Use `Sentry.updateSpanName()` to override the automatically generated name. Choose a name that groups similar operations, and store request-specific details in span attributes. If you use `@sentry/browser`, `@sentry/react`, and so on in browser environments, `span.updateName()` and `Sentry.updateSpanName()` will function identically, so you can use either one of them. diff --git a/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx index 36c4f25dfea89..38e0c447b9e83 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/queues-module.mdx @@ -8,7 +8,6 @@ supported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions diff --git a/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx b/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx index 4701c5aaf7a77..1edce4069f9df 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/requests-module.mdx @@ -36,7 +36,7 @@ async function makeRequest(method, url) { span.setAttribute("http.response.status_code", response.status); span.setAttribute( - "http.response_content_length", + "http.response.body.size", Number(response.headers.get("content-length")) ); diff --git a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx index f86a45e676241..04eb4000295cf 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx @@ -811,7 +811,6 @@ app.post("/api/ai/chat", async (req: Request, res: Response) => { attributes: { "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": toolCall.function.name, - "gen_ai.tool.type": "function", "gen_ai.tool.call.arguments": toolCall.function.arguments, [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: "manual.ai.custom-llm", }, diff --git a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx index d5cdd5beea121..2d84e1a65c313 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx @@ -73,13 +73,14 @@ For detailed examples of how to implement span metrics in common scenarios, see ## Adding Metrics to All Spans To consistently add metrics across all spans in your application, you can use the `beforeSendSpan` callback. -Note that the property names differ between transaction mode (the default) and stream mode: +In stream mode, the callback receives span attributes in `span.attributes`. +If you opt into transaction mode with `traceLifecycle: 'static'`, wrap the callback with `Sentry.withStaticSpan()` and use `span.data` instead: -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ beforeSendSpan(span) { - span.data = { - ...span.data, + span.attributes = { + ...span.attributes, "app.version": "1.2.3", "environment.region": "us-west-2", }; @@ -89,17 +90,18 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ - beforeSendSpan(span) { - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + span.data = { + ...span.data, "app.version": "1.2.3", "environment.region": "us-west-2", }; return span; - }, + }), }); ``` diff --git a/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx b/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx index 7dfa22672121e..8d5d9851b0975 100644 --- a/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx +++ b/docs/platforms/javascript/common/tracing/streamed-spans/index.mdx @@ -1,6 +1,6 @@ --- title: Streamed Spans -description: "Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner." +description: "Learn how the SDK sends spans in batches as they finish, and how to configure span attributes, filtering, and delivery." sidebar_order: 35 new: true notSupported: @@ -8,22 +8,21 @@ notSupported: - javascript.electron --- -By default, the Sentry JavaScript SDKs collect all spans in memory and send them to Sentry as a single transaction once the root span ends. This is called transaction mode. -Stream mode changes this by sending spans to Sentry in batches as they finish. Service spans, which represent a service's entry point, replace transactions as the main grouping for each service. +The Sentry JavaScript SDKs send spans in batches as they finish. This is called stream mode and is the default trace lifecycle. Service spans represent a service's entry point and group its child spans. -- **No 1,000-span limit.** In transaction mode, transactions are capped at 1,000 spans. Stream mode has no upper limit since spans are sent in batches. +- **No 1,000-span limit.** Spans are sent in batches, so a trace can contain more than 1,000 spans. - **Lower memory usage.** Spans are flushed periodically and don't need to be held in memory until the root span ends. This is especially useful for long-running processes like queue consumers or cron jobs. - **Faster visibility.** Span data arrives in Sentry as your application runs, instead of only after the entire operation completes. -- **No data loss from crashes.** If your process terminates unexpectedly, spans that were already flushed are preserved. In transaction mode, a crash before the root span ends means all span data is lost. +- **No data loss from crashes.** If your process terminates unexpectedly, spans that were already flushed are preserved. Spans still buffered in memory can be lost. You can find the following span types mentioned throughout this page: - **Root span**: The topmost span in a trace. It has no parent span and is always a service span. -- **Service span**: A parent-level span at the entry of a service. In transaction mode, this is called a transaction. +- **Service span**: A parent-level span at the entry of a service, identified by `is_segment` in its serialized data. - **Child span**: Any span nested under a parent span within the same trace. This graph shows how these span types relate to each other within a trace: @@ -39,49 +38,13 @@ Trace └── Child span ``` -Span stream mode will be enabled by default in version `11.0.0` of the SDK. -You can already opt into stream mode in version 10 by following the migration guide below. +## Configuration -## Prerequisites +Configure tracing in your +app. The SDK uses `traceLifecycle: 'stream'` by default, with no additional +integration required. -You need: - -- Tracing configured in - your app -- SDK version `>=10.66.0` - -## Migrate from Transaction Mode - -For most users, switching to stream mode requires no code changes beyond the initial opt-in. -If you use `beforeSendSpan` or `beforeSendTransaction`, follow these steps: - -1. [Enable stream mode](#enable-stream-mode) -2. [Wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` to filter spans](#filter-spans) -3. [Replace `beforeSendTransaction` with `ignoreSpans` to drop spans](#drop-spans) -4. [Migrate tags (`Sentry.setTag(s)`) to attributes (`Sentry.setAttribute(s)`)](#shared-attributes) -5. [Verify the migration](#verify-your-setup) - -### Agent-Assisted Migration - -Copy the following prompt and paste it into your AI agent: - -```txt -Follow ___CURRENT_URL___ to enable and migrate to span streaming in the Sentry SDK. -``` - -## Enable Stream Mode - - - - - - - -Tracing modes are scoped per SDK, which means you can use, for example, stream mode in your frontend, and transaction mode in your backend, or vice versa. - - - - +To opt out of span streaming, set `traceLifecycle: 'static'`. With this setting, wrap `beforeSendSpan` with `Sentry.withStaticSpan()` to receive and return `SpanJSON`. Transaction mode also supports transaction filtering with `beforeSendTransaction` and `ignoreTransactions`. @@ -99,340 +62,35 @@ Each flush sends only the spans accumulated since the last flush, grouped into e ## Manual Instrumentation (Optional) -### Start a Span - - - - - -Use `Sentry.startSpan()` to create a span that is automatically ended when the callback completes: - - - - -```javascript -const result = await Sentry.startSpan( - { name: "my-operation", attributes: { "my.attribute": "value" } }, - async () => { - // Your code here - return await doWork(); - } -); -``` - - - - - - - -Child spans created inside the callback are automatically associated with the parent: - - - - -```javascript -await Sentry.startSpan({ name: "parent-operation" }, async () => { - await Sentry.startSpan({ name: "child-step-1" }, async () => { - await stepOne(); - }); - - await Sentry.startSpan({ name: "child-step-2" }, async () => { - await stepTwo(); - }); -}); -``` - - - - - -For more details on span creation APIs, such as `startSpan`, `startSpanManual`, or `startInactiveSpan`, see Instrumentation. +Use the same span creation APIs in stream mode as in transaction mode. To measure operations the SDK does not instrument automatically, see Instrumentation for `startSpan`, `startSpanManual`, and `startInactiveSpan` examples. ## Add Attributes -Attach structured metadata to spans using `attributes`, which can be `string`, `number`, or `boolean`, as well as arrays of these types. - - - - - -You can set attributes when starting a span: - - - - -```javascript -Sentry.startSpan( - { - name: "process-order", - attributes: { - "sentry.op": "queue.process", - "order.id": "abc-123", - "order.item_count": 5, - "order.priority": true, - }, - }, - () => { - // Process the order - } -); -``` - - - - - - - -Or add them to an already running span: - - - - -```javascript -Sentry.startSpan({ name: "handle-request" }, (span) => { - // Set a single attribute - span.setAttribute("http.response.status_code", 200); - - // Set multiple attributes at once - span.setAttributes({ - "http.route": "/api/users", - "user.id": "user-42", - }); -}); -``` - - - - -Find more examples in our Sending Span Metrics documentation. - - +To attach metadata to individual spans, see Adding Span Attributes. ### Shared Attributes -Previously, transaction mode applied shared tags (`Sentry.setTag(s)`) to the service span (transaction). -In Stream mode, tags are no longer applied to spans. -Set shared attributes on a specific scope instead. -You don't need to remove tags from your code, since they still apply to errors. -Instead, add attributes for all data that's relevant for spans, logs metrics. - - - - - -Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all spans (as well as your logs and metrics). -These work just like `Sentry.setTag` and `Sentry.setTags`, but they accept `string`, `number`, and `boolean` values. - -To attach attributes to a broader or narrower context, set them on a specific scope instead. Use the global scope for app-wide attributes and the current scope for a single operation. - -See Attributes for more information. - - - - -```javascript -// Applied to all spans, logs and metrics -Sentry.setAttributes({ - org_id: user.orgId, - user_tier: user.tier, -}); -Sentry.setAttribute("service", "checkout"); - -// Global scope - shared across entire app -Sentry.getGlobalScope().setAttributes({ - service: "checkout", - version: "2.1.0", -}); - -// Current scope - single operation -Sentry.withScope((scope) => { - scope.setAttribute("request_id", req.id); - Sentry.logger.info("Processing order"); -}); -``` - - - - +Use shared attributes to attach the same metadata to spans, logs, and metrics. Scope tags apply to errors and are not included in streamed spans. ## Breadcrumbs -In stream mode, breadcrumbs are no longer sent with spans. -They remain attached to errors, so you don't need to change how you record them. +Breadcrumbs are attached to errors. Streamed spans do not include breadcrumbs. ## Extended Configuration (Optional) -### Filter Spans - - - - - -To modify or redact span data before it's sent, use `beforeSendSpan`. In stream mode, wrap it with `Sentry.withStreamedSpan()` so the SDK applies it to spans as they are flushed rather than only at transaction time. - - - `beforeSendSpan` can only modify span data, and you cannot use it to drop - spans. Use [`ignoreSpans`](#drop-spans) instead. - - -The `span` object also has different property names in stream mode. For example, `span.op` becomes `span.attributes?.["sentry.op"]` and `span.description` becomes `span.name`. See the migration note below for the full list. - - - - - - -```JavaScript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - traceLifecycle: "stream", - beforeSendSpan: Sentry.withStreamedSpan((span) => { - // In stream mode, 'op' is accessed via attributes - if (span.attributes?.["sentry.op"] === "db.query") { - // In stream mode, 'description' is now renamed to 'name' - span.name = "[filtered]"; - } - return span; - }), -}); -``` - - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - // other integrations - Sentry.spanStreamingIntegration(), - ], - beforeSendSpan: Sentry.withStreamedSpan((span) => { - // In stream mode, 'op' is accessed via attributes - if (span.attributes?.["sentry.op"] === "db.query") { - // In stream mode, 'description' is now renamed to 'name' - span.name = "[filtered]"; - } - return span; - }), -}); -``` - - - - - - - - - +Modify span data before sending it or filter out spans you do not need. -If you're using `beforeSendSpan`, wrap it with `Sentry.withStreamedSpan()` as shown above, otherwise the SDK falls back to transaction mode. - -Note that the `span` object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names: +### Filter Spans -| Transaction Mode (`SpanJSON`) | Stream Mode (`StreamedSpanJSON`) | -| ---------------------------------- | ----------------------------------- | -| `span.description` | `span.name` | -| `span.data` (processed attributes) | `span.attributes` (raw attributes) | -| `span.timestamp` (end time) | `span.end_timestamp` | -| `span.status` (optional string) | `span.status` (`'ok'` or `'error'`) | -| `span.op` | `span.attributes['sentry.op']` | +Use `beforeSendSpan` to modify each finished span. In stream mode, the callback receives `StreamedSpanJSON` directly. Check `span.is_segment` to target only service spans. -If you're using `beforeSendTransaction` to drop spans, use [`ignoreSpans`](#drop-spans) instead, since `beforeSendTransaction` is not available in stream mode. - - +The callback cannot return `null` to drop spans. See Filtering Spans for examples of modifying and dropping spans. ### Drop Spans -In stream mode, `ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped. - - - - - -To prevent specific spans from being created, use the `ignoreSpans` option: - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - traceLifecycle: "stream", - ignoreSpans: [ - // Drop spans whose name contains "healthcheck" - "healthcheck", - // Drop spans whose name matches a pattern - /^GET \/api\/v1\/internal/, - // Drop spans matching name and attribute conditions - { - name: /^GET \//, - attributes: { - "http.route": "/api/status", - }, - }, - ], -}); -``` - - - - - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - tracesSampleRate: 1.0, - integrations: [ - // other integrations - Sentry.spanStreamingIntegration(), - ], - ignoreSpans: [ - // Drop spans whose name contains "healthcheck" - "healthcheck", - // Drop spans whose name matches a pattern - /^GET \/api\/v1\/internal/, - // Drop spans matching name and attribute conditions - { - name: /^GET \//, - attributes: { - "http.route": "/api/status", - }, - }, - ], -}); -``` - - - - - - - - +Use `ignoreSpans` to drop spans by name, operation, or attributes. In stream mode, rules are evaluated when a span starts, so later name and attribute updates do not affect matching. -If a matching span is a service span, all of its child spans are dropped as well. If a child span matches, only that span is dropped and its children are reparented to the nearest ancestor. - - - -In transaction mode, `ignoreSpans` is evaluated at transaction end rather than at span start. Review your existing rules to make sure the attributes and names you're matching on are passed when the span is created. - -If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting `debug: true` when initializing the SDK. - - +Ignoring a service span also drops its child spans. Ignoring a child span reparents its children to the nearest ancestor. See Using `ignoreSpans` for matching rules and examples. ## Distributed Tracing (Optional) @@ -441,23 +99,10 @@ when the SDK can't instrument automatically, see - - - -- **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look the same as in transaction mode, but without transactions. -- **Check for fallback warnings in your logs**: If the SDK logs warnings about falling back to transaction mode, your `beforeSendSpan` callback is likely missing the `Sentry.withStreamedSpan()` wrapper. - - - - +Check the Traces view in Sentry for spans shortly after they finish. Enable `debug: true` to see SDK warnings, including callbacks that do not match the configured trace lifecycle. -- **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look similar to transaction mode, but contain only spans and no transactions. -- **Check for fallback warnings in your logs**: If the SDK logs warnings about falling back to transaction mode, your `beforeSendSpan` callback is likely missing the `Sentry.withStreamedSpan()` wrapper. -- **Check the network tab in your browser's DevTools**: Span envelopes should appear as individual requests with content type `application/vnd.sentry.items.span.v2+json` +In your browser's DevTools network tab, look for span envelopes with content type `application/vnd.sentry.items.span.v2+json`. diff --git a/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx b/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx new file mode 100644 index 0000000000000..7dfa22672121e --- /dev/null +++ b/docs/platforms/javascript/common/tracing/streamed-spans/index__v10.x.mdx @@ -0,0 +1,463 @@ +--- +title: Streamed Spans +description: "Learn how to use stream mode to send spans to Sentry as they finish, removing the 1,000-span limit and making trace data visible sooner." +sidebar_order: 35 +new: true +notSupported: + - javascript.cordova + - javascript.electron +--- + +By default, the Sentry JavaScript SDKs collect all spans in memory and send them to Sentry as a single transaction once the root span ends. This is called transaction mode. +Stream mode changes this by sending spans to Sentry in batches as they finish. Service spans, which represent a service's entry point, replace transactions as the main grouping for each service. + + + +- **No 1,000-span limit.** In transaction mode, transactions are capped at 1,000 spans. Stream mode has no upper limit since spans are sent in batches. +- **Lower memory usage.** Spans are flushed periodically and don't need to be held in memory until the root span ends. This is especially useful for long-running processes like queue consumers or cron jobs. +- **Faster visibility.** Span data arrives in Sentry as your application runs, instead of only after the entire operation completes. +- **No data loss from crashes.** If your process terminates unexpectedly, spans that were already flushed are preserved. In transaction mode, a crash before the root span ends means all span data is lost. + + + +You can find the following span types mentioned throughout this page: + +- **Root span**: The topmost span in a trace. It has no parent span and is always a service span. +- **Service span**: A parent-level span at the entry of a service. In transaction mode, this is called a transaction. +- **Child span**: Any span nested under a parent span within the same trace. + +This graph shows how these span types relate to each other within a trace: + +``` +Trace +│ +└── Root span [service A] + ├── Child span + │ └── Child span + └── Service span [service B] + ├── Child span + └── Child span +``` + +Span stream mode will be enabled by default in version `11.0.0` of the SDK. +You can already opt into stream mode in version 10 by following the migration guide below. + +## Prerequisites + +You need: + +- Tracing configured in + your app +- SDK version `>=10.66.0` + +## Migrate from Transaction Mode + +For most users, switching to stream mode requires no code changes beyond the initial opt-in. +If you use `beforeSendSpan` or `beforeSendTransaction`, follow these steps: + +1. [Enable stream mode](#enable-stream-mode) +2. [Wrap `beforeSendSpan` with `Sentry.withStreamedSpan()` to filter spans](#filter-spans) +3. [Replace `beforeSendTransaction` with `ignoreSpans` to drop spans](#drop-spans) +4. [Migrate tags (`Sentry.setTag(s)`) to attributes (`Sentry.setAttribute(s)`)](#shared-attributes) +5. [Verify the migration](#verify-your-setup) + +### Agent-Assisted Migration + +Copy the following prompt and paste it into your AI agent: + +```txt +Follow ___CURRENT_URL___ to enable and migrate to span streaming in the Sentry SDK. +``` + +## Enable Stream Mode + + + + + + + +Tracing modes are scoped per SDK, which means you can use, for example, stream mode in your frontend, and transaction mode in your backend, or vice versa. + + + + + + + +When stream mode is enabled, the SDK maintains an internal buffer that groups spans by trace ID. + +Spans are flushed: + +- On a regular interval (every 5 seconds by default). +- When a trace's buffer reaches 1,000 spans or the maximum size limit of a batch. +- When you call `Sentry.flush()` or `Sentry.close()`. + +Each flush sends only the spans accumulated since the last flush, grouped into envelopes by trace ID. + + + +## Manual Instrumentation (Optional) + +### Start a Span + + + + + +Use `Sentry.startSpan()` to create a span that is automatically ended when the callback completes: + + + + +```javascript +const result = await Sentry.startSpan( + { name: "my-operation", attributes: { "my.attribute": "value" } }, + async () => { + // Your code here + return await doWork(); + } +); +``` + + + + + + + +Child spans created inside the callback are automatically associated with the parent: + + + + +```javascript +await Sentry.startSpan({ name: "parent-operation" }, async () => { + await Sentry.startSpan({ name: "child-step-1" }, async () => { + await stepOne(); + }); + + await Sentry.startSpan({ name: "child-step-2" }, async () => { + await stepTwo(); + }); +}); +``` + + + + + +For more details on span creation APIs, such as `startSpan`, `startSpanManual`, or `startInactiveSpan`, see Instrumentation. + +## Add Attributes + +Attach structured metadata to spans using `attributes`, which can be `string`, `number`, or `boolean`, as well as arrays of these types. + + + + + +You can set attributes when starting a span: + + + + +```javascript +Sentry.startSpan( + { + name: "process-order", + attributes: { + "sentry.op": "queue.process", + "order.id": "abc-123", + "order.item_count": 5, + "order.priority": true, + }, + }, + () => { + // Process the order + } +); +``` + + + + + + + +Or add them to an already running span: + + + + +```javascript +Sentry.startSpan({ name: "handle-request" }, (span) => { + // Set a single attribute + span.setAttribute("http.response.status_code", 200); + + // Set multiple attributes at once + span.setAttributes({ + "http.route": "/api/users", + "user.id": "user-42", + }); +}); +``` + + + + +Find more examples in our Sending Span Metrics documentation. + + + +### Shared Attributes + +Previously, transaction mode applied shared tags (`Sentry.setTag(s)`) to the service span (transaction). +In Stream mode, tags are no longer applied to spans. +Set shared attributes on a specific scope instead. +You don't need to remove tags from your code, since they still apply to errors. +Instead, add attributes for all data that's relevant for spans, logs metrics. + + + + + +Use `Sentry.setAttribute` and `Sentry.setAttributes` to attach attributes that are automatically included in all spans (as well as your logs and metrics). +These work just like `Sentry.setTag` and `Sentry.setTags`, but they accept `string`, `number`, and `boolean` values. + +To attach attributes to a broader or narrower context, set them on a specific scope instead. Use the global scope for app-wide attributes and the current scope for a single operation. + +See Attributes for more information. + + + + +```javascript +// Applied to all spans, logs and metrics +Sentry.setAttributes({ + org_id: user.orgId, + user_tier: user.tier, +}); +Sentry.setAttribute("service", "checkout"); + +// Global scope - shared across entire app +Sentry.getGlobalScope().setAttributes({ + service: "checkout", + version: "2.1.0", +}); + +// Current scope - single operation +Sentry.withScope((scope) => { + scope.setAttribute("request_id", req.id); + Sentry.logger.info("Processing order"); +}); +``` + + + + + +## Breadcrumbs + +In stream mode, breadcrumbs are no longer sent with spans. +They remain attached to errors, so you don't need to change how you record them. + +## Extended Configuration (Optional) + +### Filter Spans + + + + + +To modify or redact span data before it's sent, use `beforeSendSpan`. In stream mode, wrap it with `Sentry.withStreamedSpan()` so the SDK applies it to spans as they are flushed rather than only at transaction time. + + + `beforeSendSpan` can only modify span data, and you cannot use it to drop + spans. Use [`ignoreSpans`](#drop-spans) instead. + + +The `span` object also has different property names in stream mode. For example, `span.op` becomes `span.attributes?.["sentry.op"]` and `span.description` becomes `span.name`. See the migration note below for the full list. + + + + + + +```JavaScript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + traceLifecycle: "stream", + beforeSendSpan: Sentry.withStreamedSpan((span) => { + // In stream mode, 'op' is accessed via attributes + if (span.attributes?.["sentry.op"] === "db.query") { + // In stream mode, 'description' is now renamed to 'name' + span.name = "[filtered]"; + } + return span; + }), +}); +``` + + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + // other integrations + Sentry.spanStreamingIntegration(), + ], + beforeSendSpan: Sentry.withStreamedSpan((span) => { + // In stream mode, 'op' is accessed via attributes + if (span.attributes?.["sentry.op"] === "db.query") { + // In stream mode, 'description' is now renamed to 'name' + span.name = "[filtered]"; + } + return span; + }), +}); +``` + + + + + + + + + + +If you're using `beforeSendSpan`, wrap it with `Sentry.withStreamedSpan()` as shown above, otherwise the SDK falls back to transaction mode. + +Note that the `span` object is `StreamedSpanJSON` instead of `SpanJSON` and has different property names: + +| Transaction Mode (`SpanJSON`) | Stream Mode (`StreamedSpanJSON`) | +| ---------------------------------- | ----------------------------------- | +| `span.description` | `span.name` | +| `span.data` (processed attributes) | `span.attributes` (raw attributes) | +| `span.timestamp` (end time) | `span.end_timestamp` | +| `span.status` (optional string) | `span.status` (`'ok'` or `'error'`) | +| `span.op` | `span.attributes['sentry.op']` | + +If you're using `beforeSendTransaction` to drop spans, use [`ignoreSpans`](#drop-spans) instead, since `beforeSendTransaction` is not available in stream mode. + + + +### Drop Spans + +In stream mode, `ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped. + + + + + +To prevent specific spans from being created, use the `ignoreSpans` option: + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + traceLifecycle: "stream", + ignoreSpans: [ + // Drop spans whose name contains "healthcheck" + "healthcheck", + // Drop spans whose name matches a pattern + /^GET \/api\/v1\/internal/, + // Drop spans matching name and attribute conditions + { + name: /^GET \//, + attributes: { + "http.route": "/api/status", + }, + }, + ], +}); +``` + + + + + + + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + integrations: [ + // other integrations + Sentry.spanStreamingIntegration(), + ], + ignoreSpans: [ + // Drop spans whose name contains "healthcheck" + "healthcheck", + // Drop spans whose name matches a pattern + /^GET \/api\/v1\/internal/, + // Drop spans matching name and attribute conditions + { + name: /^GET \//, + attributes: { + "http.route": "/api/status", + }, + }, + ], +}); +``` + + + + + + + + + +If a matching span is a service span, all of its child spans are dropped as well. If a child span matches, only that span is dropped and its children are reparented to the nearest ancestor. + + + +In transaction mode, `ignoreSpans` is evaluated at transaction end rather than at span start. Review your existing rules to make sure the attributes and names you're matching on are passed when the span is created. + +If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting `debug: true` when initializing the SDK. + + + +## Distributed Tracing (Optional) + +Distributed tracing works out of the box when tracing is enabled and works the same way in stream mode. If you need to manually propagate trace context, for example, +when the SDK can't instrument automatically, see custom instrumentation for distributed tracing. + +## Verify Your Setup + +To make sure you've enabled stream mode successfully: + + + + + +- **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look the same as in transaction mode, but without transactions. +- **Check for fallback warnings in your logs**: If the SDK logs warnings about falling back to transaction mode, your `beforeSendSpan` callback is likely missing the `Sentry.withStreamedSpan()` wrapper. + + + + + + + +- **Check the Sentry dashboard**: Spans should appear in the Traces view shortly after they complete. Traces look similar to transaction mode, but contain only spans and no transactions. +- **Check for fallback warnings in your logs**: If the SDK logs warnings about falling back to transaction mode, your `beforeSendSpan` callback is likely missing the `Sentry.withStreamedSpan()` wrapper. +- **Check the network tab in your browser's DevTools**: Span envelopes should appear as individual requests with content type `application/vnd.sentry.items.span.v2+json` + + diff --git a/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx b/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx index 0024a04c5810c..b4be9f2aa0996 100644 --- a/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/tracing/troubleshooting/index.mdx @@ -9,11 +9,20 @@ If you need help managing transactions or spans, start with this page. If you ne ## Group Transactions -When Sentry captures transactions, they are assigned a transaction name. This name is generally auto-generated by the Sentry SDK based on the framework integrations you are using. If you can't leverage the automatic transaction generation (or want to customize how transaction names are generated) you can use a global event processor that is registered when you initialize the SDK with your configuration. +The SDK groups spans by service span. Integrations usually name these spans automatically. To change a service span's name before it is sent, use `beforeSendSpan` and check `is_segment`: -For example: +```javascript +Sentry.init({ + beforeSendSpan(span) { + if (span.is_segment && span.attributes["http.route"] === "/users/:id") { + span.name = "GET /users/:id"; + } + return span; + }, +}); +``` - +Event processors do not apply to streamed spans. In transaction mode, use `beforeSendTransaction` to change `event.transaction`. See Transaction Name for other ways to set names. ## Control Data Truncation @@ -32,16 +41,16 @@ For example, a 200+ character tag like this: ## Traces Miss Spans, High Memory Usage, or Data Loss After Crashes -If you're hitting the 1,000-span limit, experiencing high memory usage from long-running processes, or losing span data when your process crashes, consider enabling stream mode. Stream mode sends spans to Sentry in batches as they finish rather than holding them in memory until the transaction ends. +With `traceLifecycle: 'static'`, the SDK holds spans in memory until the root span ends. This can cause high memory usage, hit the 1,000-span limit, or lose spans if the process crashes. Use the default `traceLifecycle: 'stream'` to send spans in batches as they finish. In stream mode, pass `beforeSendSpan` directly without a `withStaticSpan` wrapper. See Streamed Spans for more information. -## `ignoreSpans` Rules No Longer Work As Expected After Migrating to Stream Mode +## `ignoreSpans` Rules Do Not Match Spans -In stream mode, `ignoreSpans` is evaluated at span start rather than at transaction end as in transaction mode. This means rules that match on names and attributes added or updated while a span is active may no longer match the intended spans. Review your `ignoreSpans` rules after migrating to make sure the names and attributes you're matching on are available when the span is created. +The SDK evaluates `ignoreSpans` when a span starts. Names and attributes added or updated later do not affect matching. Make sure your rules match values available when the span is created. If you're auto-instrumenting and don't know what the initial name of a span is when it starts, enable SDK debug logging during development by setting `debug: true` when initializing the SDK. -Finally, make sure you've migrated any entries from `ignoreTransactions` to `ignoreSpans`, as `ignoreTransactions` is not applied in stream mode. +Use the object form of `ignoreSpans` to match both name and operation when you need to distinguish service spans from child spans with the same name. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index f68922850512e..63edebae93985 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -171,20 +171,6 @@ To fix this, change the `tracePropagationTargets` option during SDK initializati - - - - When using ESM, by default all packages are wrapped under the hood by - [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle). - `import-in-the-middle` has compatibility issues with some packages and - can throw errors in these situations. - -Check out the ESM Troubleshooting Instrumentation section for more information. - - - - - @@ -517,42 +503,10 @@ Learn more about fixing these caching issues in the - -When using pnpm, you might encounter errors related to packages that can't be external, particularly with packages like `import-in-the-middle` and `require-in-the-middle`. These errors typically occur due to pnpm's strict dependency management and hoisting behavior. - -While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues: - -```bash -pnpm add import-in-the-middle require-in-the-middle -``` - -As a workaround, create or modify `.npmrc` in your project root. First, try to specifically hoist the dependencies in question: - -```ini {filename:.npmrc} -public-hoist-pattern[]=*import-in-the-middle* -public-hoist-pattern[]=*require-in-the-middle* -``` - -If that doesn't work, you can also tell pnpm to hoist all dependencies: - -```ini {filename:.npmrc} -shamefully-hoist=true -``` - - - **Note**: While `shamefully-hoist=true` usually isn't the ideal solution from - a dependency management perspective, it's sometimes necessary for - compatibility with certain packages that expect Node.js module resolution - behavior similar to npm or yarn. - - - - - + This applies to SDK version 10 and earlier. Version 11 and above don't use `import-in-the-middle`. + After adding `sentry.server.config.ts` and building the project, you might get an error like this: `Failed to register ESM hook import-in-the-middle/hook.mjs`. You can add an override (npm/pnpm) or a resolution (yarn) for `@vercel/nft` to fix this. This will add the `hook.mjs` file to your build output. See the [underlying issue in the Nitro project](https://github.com/nitrojs/nitro/issues/2703). @@ -584,6 +538,8 @@ shamefully-hoist=true + This applies to SDK version 10 and earlier. Version 11 and above don't use `import-in-the-middle`. + Sentry injects `import "import-in-the-middle/hook.mjs"` in your server entry. This import acts as a hint for node bundlers to really include this file. As pnpm implements a strict dependency isolation, this import might cause problems. Per default, `shamefully-hoist` is `false` ([pnpm docs here](https://pnpm.io/next/npmrc#shamefully-hoist)) and this prevents accessing non-declared dependencies. @@ -596,14 +552,27 @@ shamefully-hoist=true - Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. - Currently, trace collection is only supported when building and running the application. Development mode (`nuxt dev`) is currently not supported. + The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts, in production and in development mode. + Read more about this in Server-Side Installation. + + If the server side doesn't send events, check the following: - When running the build output, Sentry needs to be initialized before running the rest of the application. This is done automatically, but might not work for your use case. - Read more about this in installation methods. + - The `sentry.server.config.ts` file is in the root of your project, next to `nuxt.config.ts`. + - Enable `debug` in the `sentry` options of your `nuxt.config.ts`. The SDK then prints a message during the build when it bundles the server config. + - Remove the deprecated `autoInjectServerSentry` option, so that the SDK uses the bundled initialization. + - If you're using a Cloudflare Nitro preset, the SDK doesn't use `sentry.server.config.ts`. Use the [Cloudflare Nitro plugin](/platforms/javascript/guides/cloudflare/frameworks/nuxt/) instead. + - The SDK doesn't initialize while Nitro prerenders pages at build time, so builds don't send events. --- + **SDK version 10 and earlier** + + Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. + Trace collection is only supported when building and running the application. Development mode (`nuxt dev`) is not supported. + + When running the build output, Sentry needs to be initialized before running the rest of the application. + Read more about this in the [installation methods for version 10](/platforms/javascript/guides/nuxt/install__v10.x/). + We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application: @@ -675,7 +644,7 @@ shamefully-hoist=true }; // The Sentry plugin should always be applied last - const { withSentryConfig } = require('@sentry/nextjs'); + const { withSentryConfig } = require('@sentry/nextjs/config'); module.exports = withSentryConfig(module.exports) ``` @@ -695,9 +664,9 @@ shamefully-hoist=true Cloudflare's [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) lets work continue after the Worker returns a response. Whether those spans arrive depends on your trace lifecycle. - On the static lifecycle, which is the default, the SDK snapshots the request transaction when the response is returned, so anything finishing later is dropped. Streaming sends each sampled span as it finishes instead, which captures deferred work. + In transaction mode (`traceLifecycle: "static"`), the SDK snapshots the request transaction when the response is returned, so spans that finish later may be missing. Stream mode, the default since SDK version 11.0.0, sends sampled spans in batches as they finish, which captures deferred work. - Set `traceLifecycle: "stream"`, which needs `@sentry/cloudflare` version `10.49.0` or newer: + If you use transaction mode, remove `traceLifecycle: "static"` or set it to `"stream"`. On SDK version 10, explicitly set `traceLifecycle: "stream"`, which requires `@sentry/cloudflare` version `10.49.0` or newer: ```javascript {filename:index.js} export default Sentry.withSentry( @@ -710,7 +679,7 @@ shamefully-hoist=true ); ``` - If you need to keep the static lifecycle, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` isn't available in stream mode. + If you need to keep transaction mode, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` isn't available in stream mode. ```javascript {filename:index.js} ctx.waitUntil( @@ -762,4 +731,63 @@ shamefully-hoist=true + + + The plugin can only rewrite a package that passes through the bundler. Anything left external is resolved at runtime, never reaches the transform, and publishes no channel events, so it records no spans. + + Build without `external`, which is the configuration to start from: + + ```typescript {filename:build.ts} + import { sentryBunPlugin } from "@sentry/bun/plugin"; + + await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], + }); + ``` + + A blanket externalization strategy is the usual cause. Both `packages: "external"` and `"*"` in `external` push your instrumented packages back out of the bundle, and the plugin warns at build time: + + ```typescript {filename:build.ts} {diff} + await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + - packages: "external", + plugins: [sentryBunPlugin()], + }); + ``` + + If you do need `external`, list only packages you don't need traced, and keep your database clients, AI SDKs and instrumented frameworks off the list. + + + + + + + + + +Your app imports a dependency that calls `require()` on a JSON file, and the `@sentry/deno/import` hook is active. Deno compiles the JSON as JavaScript instead, and the process stops before your code runs: + +``` +error: Uncaught SyntaxError: Unexpected token ':' +``` + +This is a Deno bug ([denoland/deno#36240](https://github.com/denoland/deno/issues/36240)): while any module hook is registered, Deno loads `.json` files with the wrong format. Express, Fastify, Hapi, Koa and mysql2 all read a JSON file this way. + +Remove the `@sentry/deno/import` line from your entry file to start your app again: + +```javascript {filename: main.ts} +import * as Sentry from "npm:@sentry/deno"; +``` + +Errors, `Deno.serve` and `node:http` spans, logs and metrics all keep working without the hook. You lose the integrations that depend on it, such as `mysql` 2.x and `pg`. Drivers that publish their own diagnostics channels, among them `mysql2` 3.20.0 and later and `ioredis` 5.11.0 and later, are instrumented either way. + + + + + If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. diff --git a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx index 32a83dd416604..9e11f1868b6f4 100644 --- a/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx +++ b/docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx @@ -9,7 +9,6 @@ notSupported: - javascript.mastra - javascript.aws-lambda - javascript.azure-functions - - javascript.connect - javascript.express - javascript.fastify - javascript.gcp-functions @@ -24,7 +23,7 @@ Sentry's latest JavaScript SDKs require ES2020 compatibility. The minimum suppor - Chrome 80 - Edge 80 -- Safari 14, iOS Safari 14.4 +- Safari 15, iOS Safari 15 - Firefox 74 - Opera 67 - Samsung Internet 13.0 diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx index 26359e0ac6796..6accb538b77bb 100644 --- a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx +++ b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx @@ -8,7 +8,7 @@ notSupported: - javascript.mastra --- - + ## User Feedback Widget diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx index e696f17382cbe..9d0f276ef2091 100644 --- a/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx +++ b/docs/platforms/javascript/common/user-feedback/configuration/index__v7.x.mdx @@ -17,7 +17,7 @@ In version 7 of our JavaScript SDK, User Feedback was released as a Beta integra - + ## User Feedback Widget diff --git a/docs/platforms/javascript/common/user-feedback/index.mdx b/docs/platforms/javascript/common/user-feedback/index.mdx index 55ce4afc68739..d3923369258d4 100644 --- a/docs/platforms/javascript/common/user-feedback/index.mdx +++ b/docs/platforms/javascript/common/user-feedback/index.mdx @@ -18,7 +18,7 @@ The User Feedback feature allows you to collect user feedback from anywhere insi feature. Lower versions may have limited functionality. - + ## User Feedback Widget diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx index 5a6569da961e8..79f9f86d22fd2 100644 --- a/docs/platforms/javascript/guides/astro/index.mdx +++ b/docs/platforms/javascript/guides/astro/index.mdx @@ -13,7 +13,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Astro `3.0.0` or above +- Astro `4.0.0` or above - If you're using Astro's Netlify adapter (`@astrojs/netlify`), you need version `5.0.0` or above diff --git a/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx new file mode 100644 index 0000000000000..0df5798b10387 --- /dev/null +++ b/docs/platforms/javascript/guides/aws-lambda/install/layer__v10.x.mdx @@ -0,0 +1,122 @@ +--- +title: Lambda Layer +description: >- + Learn how to add the Sentry Node Lambda Layer to use Sentry in your Lambda + functions +sidebar_order: 1 +og_image: /og-images/platforms-javascript-guides-aws-lambda-install-layer__v10.x.png +--- + +The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) instead of installing `@sentry/aws-serverless` with a package manager manually. +If you follow this guide, you don't have to worry about deploying Sentry dependencies alongside your function code. + +## Prerequisites + +Before you begin, make sure you have the following: + +- You have a Lambda function deployed in AWS. +- You know the AWS region that your function is deployed to. + +## 1. Add the Sentry Lambda Layer + +Add the Sentry Layer by navigating to your Lambda function. Select **Layers**, then **Add a Layer**. + +![](./img/lambda_view.png) + +**Specify an ARN** tab as illustrated: + +![](./img/add_layer.png) + +Choose the region and SDK version, then copy the provided ARN into the input. + + + +
+ +The Sentry Lambda Layer also bundles a Sentry Lambda extension that automatically handles event delivery. To opt out, see [`useLayerExtension`](/platforms/javascript/guides/aws-lambda/configuration/options/#useLayerExtension) in the configuration options. + +## 2. Setup Options + +### Option A: Automatic Setup (recommended) + +In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). + +Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. + + + +Set the following environment variables in your Lambda function configuration: + +```bash +NODE_OPTIONS="--import @sentry/aws-serverless/awslambda-auto" +SENTRY_DSN="___PUBLIC_DSN___" +# ___PRODUCT_OPTION_START___ performance +SENTRY_TRACES_SAMPLE_RATE="1.0" +# ___PRODUCT_OPTION_END___ performance +``` + +To set environment variables, navigate to your Lambda function, select **Configuration**, then **Environment variables**: + +![](./img/env_vars.png) + +### Option B: Manual Setup + +To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. The benefit of this installation method is that you can fully customize your Sentry SDK setup in a `Sentry.init` call. + +Note that you don't have to actually install an NPM package for this to work, as the package is already included in the Lambda Layer. + +Create a new file, for example `instrument.js` to initialize the SDK: + +```javascript {filename:instrument.js} {tabTitle:CommonJS} +const Sentry = require("@sentry/aws-serverless"); + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ performance + + // Add Tracing by setting tracesSampleRate and adding integration + // Set tracesSampleRate to 1.0 to capture 100% of transactions + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + +```javascript {filename:instrument.mjs} {tabTitle:ESM} +import * as Sentry from "@sentry/aws-serverless"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ performance + + // Add Tracing by setting tracesSampleRate and adding integration + // Set tracesSampleRate to 1.0 to capture 100% of transactions + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + +##### Load the SDK + +To load the SDK before your function starts, you need to preload the `instrument.js` by setting the `NODE_OPTIONS` environment variable: + +```bash +NODE_OPTIONS="--import ./instrument.js" +``` + +That's it — make sure to re-deploy your function and you're all set! + +## 3. Control the Data You Send to Sentry (Optional) + + diff --git a/docs/platforms/javascript/guides/bun/index.mdx b/docs/platforms/javascript/guides/bun/index.mdx index a5cb05c21e83c..310ca7d725565 100644 --- a/docs/platforms/javascript/guides/bun/index.mdx +++ b/docs/platforms/javascript/guides/bun/index.mdx @@ -16,7 +16,7 @@ categories: Choose the features you want to configure, and this guide will show you how: @@ -77,27 +77,53 @@ Sentry.init({ -### Apply Instrumentation to Your App +### Build With the Sentry Plugin (Recommended) -To make sure that Sentry initializes before any other modules, you need to preload your instrumentation file using the [`--preload`](https://bun.com/docs/runtime#param-preload) flag. +We recommend building with the Sentry plugin, because it adds spans from your dependencies, such as database drivers, AI SDKs, and web frameworks like Express, Koa and Hapi. Bun has no runtime hook Sentry can use to instrument those packages, so the plugin rewrites them as `bun build` bundles them. + +Add `sentryBunPlugin` from `@sentry/bun/plugin` to your `Bun.build()` call, then run the output the same way, with `--preload`. Errors, the spans you create yourself, and `Bun.serve`, `node:http` and `fetch` spans work either way. + + + - +```typescript {filename:build.ts} +import { sentryBunPlugin } from "@sentry/bun/plugin"; -Sentry's auto-instrumentation does not work with bundled code, including Bun's single-file executables. This is because auto-instrumentation relies on module loading hooks that are not available when code is bundled. If you need to bundle your application, you'll need to manually instrument your code instead of relying on auto-instrumentation. +await Bun.build({ + entrypoints: ["./app.ts"], + outdir: "./dist", + target: "bun", + plugins: [sentryBunPlugin()], +}); +``` - + + + + +### Apply Instrumentation to Your App + + + + + +Preload your instrumentation file with the [`--preload`](https://bun.com/docs/runtime#param-preload) flag. This is what guarantees that `Sentry.init()` runs before any other module is loaded. -```bash +```bash {tabTitle:From source} bun --preload ./instrument.js app.js ``` +```bash {tabTitle:Built output} +bun --preload ./instrument.js dist/app.js +``` + diff --git a/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx b/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx index 6b229a8142545..6b78e89219c1a 100644 --- a/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx +++ b/docs/platforms/javascript/guides/capacitor/migration/v2-to-v3/index.mdx @@ -115,7 +115,7 @@ This version restores several integrations that were previously missing and adds | `dedupeIntegration` | ✓ | ✓ | | | | | `functionToStringIntegration` | ✓ | | | | | | `globalHandlersIntegration` | ✓ | ✓ | | | | -| `inboundFiltersIntegration` | ✓ | ✓ | | | | +| `inboundFiltersIntegration` | ✓ | ✓ | | | | | `linkedErrorsIntegration` | ✓ | ✓ | | | | | `spotlightIntegration` | | | | | | diff --git a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx index d74c495d47609..50a6f45095517 100644 --- a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx +++ b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx @@ -36,7 +36,7 @@ export const MyAgent = Sentry.instrumentAgentWithSentry( The Worker that calls the agent names its binding in `rpcTracePropagationBindings`. See RPC Trace Propagation. -`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin's `autoInstrumentation`, the plugin detects and wraps Agent classes automatically. +`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin, it detects and wraps Agent classes for you, so you only need this wrapper on a plain Wrangler build. ## Conversation IDs diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx deleted file mode 100644 index adba0ecd9b05b..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Hono -description: "Reports Hono errors to Sentry. (default)" ---- - -_Import name: `Sentry.honoIntegration`_ - - - -**Deprecated**: `honoIntegration` is deprecated. Use the [dedicated `@sentry/hono` SDK](/platforms/javascript/guides/hono/) instead, which supports Hono across Cloudflare Workers, Node.js, and Bun with improved performance and a simpler setup. - - - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -The `honoIntegration` automatically captures errors from Hono's `onError` function and sends them to Sentry. By default, the integration doesn't capture errors that have a 3xx or 4xx HTTP status code. - -## Options - -You can configure the `honoIntegration` by passing an options object to the function. - -### `shouldHandleError` - -This option allows you to provide a function that determines whether an error should be captured, giving you full control over which errors are sent to Sentry. - -The function receives the error as an argument and should return `true` if the error should be reported, and `false` otherwise. - -For example, to report all errors except for 404s, add this to the integrations array when initializing Sentry: - -```javascript -integrations: [ - honoIntegration({ - shouldHandleError(error) { - // return true // Would report all errors - - if (error instanceof HTTPException && error.status === 404) { - // Don't report 404s - return false; - } - // Report all other errors - return true; - }, - }), -] -``` diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx index febbd812a4af1..c6f8ae2472a07 100644 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx @@ -1,22 +1,16 @@ --- title: Prisma -description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers running with Node.js compatibility." +description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers." --- - - -On Cloudflare, the `prismaIntegration` is only available through the `@sentry/cloudflare/nodejs_compat` entrypoint, which requires SDK version `10.64.0` or higher. - - - _Import name: `Sentry.prismaIntegration`_ Sentry supports tracing [Prisma ORM](https://www.prisma.io/) queries with the Prisma integration. The integration creates a span for each query and reports relevant details to Sentry. -To enable it on Cloudflare, import Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint and add the `prismaIntegration` to your `Sentry.init` call: +The integration relies on Node.js APIs, so your Worker must run with the `nodejs_compat` compatibility flag. Add the `prismaIntegration` to your `Sentry.init` call: ```javascript {3,5} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; +import * as Sentry from "@sentry/cloudflare"; Sentry.init({ tracesSampleRate: 1.0, diff --git a/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx b/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx new file mode 100644 index 0000000000000..5b2ea4429a4b5 --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/features/bindings.mdx @@ -0,0 +1,50 @@ +--- +title: Cloudflare Bindings +sidebar_title: Bindings +description: "Learn which Cloudflare bindings Sentry instruments automatically and what each binding captures." +--- + +The Sentry Cloudflare SDK instruments the bindings on your `env` object automatically. You don't have to wrap a binding or call a function. When your code reads a binding from `env`, the SDK detects its type and returns an instrumented version. + +## Supported Bindings + +| Binding | What Sentry captures | +| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| [D1](https://developers.cloudflare.com/d1/) | Database queries | +| [R2](https://developers.cloudflare.com/r2/) | Bucket operations, such as reads and uploads | +| [Queues](https://developers.cloudflare.com/queues/) | Messages that you send to a queue | +| [Workers AI](https://developers.cloudflare.com/workers-ai/) | Model calls, see Workers AI | +| [Durable Objects](https://developers.cloudflare.com/durable-objects/) | Traces that continue in the Durable Object, see Cloudflare Durable Objects | +| [Service bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/) | Traces that continue in the other Worker, if it also uses Sentry | + +For RPC calls to Durable Objects and service bindings, add the binding to `rpcTracePropagationBindings`. + +## Which `env` Is Instrumented + +The SDK instruments the `env` object that Cloudflare gives to the handlers and classes that Sentry wraps, such as your Worker, Durable Objects, and Workflows. + + + +The global `env` that you import from `cloudflare:workers` is not instrumented. Bindings that you read from it don't create spans. Use the `env` argument of your handler or class instead: + +```javascript +import * as Sentry from "@sentry/cloudflare"; +import { env as globalEnv } from "cloudflare:workers"; + +export default Sentry.withSentry( + (env) => ({ dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0 }), + { + async fetch(request, env) { + // Creates a span: `env` is the handler argument + await env.DB.prepare("SELECT * FROM users").all(); + + // Does not create a span: `globalEnv` is the global env + await globalEnv.DB.prepare("SELECT * FROM users").all(); + + return new Response("OK"); + }, + } +); +``` + + diff --git a/docs/platforms/javascript/guides/cloudflare/features/d1.mdx b/docs/platforms/javascript/guides/cloudflare/features/d1.mdx deleted file mode 100644 index f9fa8b301ea63..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/features/d1.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Cloudflare D1 Instrumentation -description: "Learn how to add span instrumentation for Cloudflare D1." ---- - -You can use the `instrumentD1WithSentry` method to instrument [Cloudflare D1](https://developers.cloudflare.com/d1/), -Cloudflare's serverless SQL database with Sentry. - -```javascript -import * as Sentry from "@sentry/cloudflare"; - -// env.DB is the D1 DB binding configured in your `wrangler.jsonc`/`wrangler.toml` config -const db = Sentry.instrumentD1WithSentry(env.DB); -// Now you can use the database as usual -await db.prepare("SELECT * FROM table WHERE id = ?").bind(1).run(); -``` diff --git a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx b/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx deleted file mode 100644 index 79193891a005a..0000000000000 --- a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Node.js Compatibility Entrypoint -description: "Learn how the nodejs_compat entrypoint unlocks additional Node.js SDK features on Cloudflare Workers, such as Prisma instrumentation." ---- - -Cloudflare Workers can run with Node.js APIs enabled through the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). To take advantage of this, the Cloudflare SDK ships a dedicated `@sentry/cloudflare/nodejs_compat` entrypoint that unlocks Node.js SDK features which aren't available in the default Workers runtime. - - - -The `@sentry/cloudflare/nodejs_compat` entrypoint requires SDK version `10.64.0` or higher. It will become the default entrypoint in the next major version (v11). - - - -## What It Unlocks - -The `/nodejs_compat` entrypoint enables Node.js-only integrations and features on Cloudflare, including: - -- The `prismaIntegration` for tracing Prisma ORM queries. -- Vercel AI SDK v7 support for the `vercelAIIntegration`. - -## Usage - -The entrypoint is a drop-in replacement for `@sentry/cloudflare`, so switching over only requires changing your imports: - -```javascript {tabTitle:After} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; -``` - -```javascript {tabTitle:Before} -import * as Sentry from "@sentry/cloudflare"; -``` - -To use the entrypoint, your Worker must set the `nodejs_compat` compatibility flag in your Wrangler configuration: - - -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "compatibility_flags": ["nodejs_compat"], -} -``` - -```toml {tabTitle:Toml} {filename:wrangler.toml} -compatibility_flags = ["nodejs_compat"] -``` - - - -We recommend that you also keep `compatibility_date` and Wrangler up to date. Some instrumentation depends on Node.js APIs that Cloudflare only exposes from a given compatibility date on, and an older date can turn that instrumentation off without an error message. The Vercel AI integration, for example, needs `2026-02-19` or later. - - diff --git a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx index afc7c2d363142..4b73ef8dccd58 100644 --- a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx +++ b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx @@ -82,7 +82,7 @@ If you don't have access to the `onRequest` middleware API, you can use the `wra ```javascript // hooks.server.js -import * as Sentry from "@sentry/cloudflare"; +import { wrapRequestHandler } from "@sentry/cloudflare/request"; export const handle = ({ event, resolve }) => { const requestHandlerOptions = { @@ -93,7 +93,7 @@ export const handle = ({ event, resolve }) => { request: event.request, context: event.platform.ctx, }; - return Sentry.wrapRequestHandler(requestHandlerOptions, () => resolve(event)); + return wrapRequestHandler(requestHandlerOptions, () => resolve(event)); }; ``` diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx index 7e81d4baf69ba..78589df78ec27 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx @@ -180,6 +180,12 @@ On Shopify Oxygen, never import anything directly from `@sentry/cloudflare`. Onl + + +`wrapRequestHandler` doesn't isolate requests from each other. Scope data you set during a request, for example with `setTag` or `setUser`, can show up on events from other concurrent or later requests in the same isolate. Use `wrapRequestHandler` only on runtimes that can't enable `nodejs_compat`, such as Shopify Oxygen. On Cloudflare Workers, wrap your handler with `Sentry.withSentry()` instead, as described in the [Cloudflare guide](/platforms/javascript/guides/cloudflare/). + + + @@ -307,7 +313,7 @@ import { reactRouter } from "@react-router/dev/vite"; import { hydrogen } from "@shopify/hydrogen/vite"; import { oxygen } from "@shopify/mini-oxygen/vite"; import { defineConfig } from "vite"; -import { sentryReactRouter } from "@sentry/react-router"; +import { sentryReactRouter } from "@sentry/react-router/vite"; export default defineConfig((config) => ({ plugins: [ diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx index 0ae565165243d..e56cb7ea4eedd 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-remix.mdx @@ -37,6 +37,12 @@ On Shopify Oxygen, never import anything directly from `@sentry/cloudflare`. Onl + + +`wrapRequestHandler` doesn't isolate requests from each other. Scope data you set during a request, for example with `setTag` or `setUser`, can show up on events from other concurrent or later requests in the same isolate. Use `wrapRequestHandler` only on runtimes that can't enable `nodejs_compat`, such as Shopify Oxygen. For Remix on Cloudflare Workers, follow the [Remix on Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/remix/) instead. + + + ```ts {filename:server.ts} import { wrapRequestHandler } from "@sentry/cloudflare/request"; import { instrumentBuild } from "@sentry/remix/cloudflare"; @@ -140,6 +146,10 @@ Sentry.init({ }); ``` +## Control the Data You Send to Sentry (Optional) + + + ## Trace Propagation diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx index e67065e7a1fcc..87b9c85bf2122 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx @@ -31,21 +31,23 @@ Choose the features you want to configure, and this guide will show you how: -Run the command for your preferred package manager to add the Sentry SDK to your application: +Run the command for your preferred package manager to add the Sentry Remix and Cloudflare SDKs to your application. + +With npm, add `--legacy-peer-deps`: `@remix-run/cloudflare` requires `@cloudflare/workers-types` version 4, while Wrangler 4 requires version 5. ```bash {tabTitle:npm} -npm install @sentry/remix --save +npm install @sentry/remix @sentry/cloudflare --save --legacy-peer-deps ``` ```bash {tabTitle:yarn} -yarn add @sentry/remix +yarn add @sentry/remix @sentry/cloudflare ``` ```bash {tabTitle:pnpm} -pnpm add @sentry/remix +pnpm add @sentry/remix @sentry/cloudflare ``` diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index ee86267841af2..ea39fc1018fe9 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -59,12 +59,6 @@ Run the command for your preferred package manager to add the Sentry SDK to your - - -Importing Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint unlocks additional Node.js SDK features on Cloudflare. It requires SDK version `10.64.0` or higher and will become the default in the next major version. [Learn more](./features/nodejs-compat). - - - ## Configure This guide sets Sentry up through Vite, which is what we recommend for Cloudflare Workers. The plugin does the wiring at build time, so your Worker code stays untouched. @@ -81,9 +75,9 @@ Not using Vite? See the Wrangler setup -Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. Both behaviors are experimental in this version, so turn them on explicitly. +Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. Both of its behaviors are on by default. -`autoInstrumentation` wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. `useDiagnosticsChannelInjection` instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. +`autoInstrumentation` wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. `buildTimeInstrumentation` instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. To see its options, which packages it instruments, and how to opt out of either behavior, see Vite Plugin. @@ -98,12 +92,7 @@ To see its options, which packages it instruments, and how to opt out of either export default defineConfig({ plugins: [ cloudflare(), -+ sentryCloudflareVitePlugin({ -+ _experimental: { -+ autoInstrumentation: true, -+ useDiagnosticsChannelInjection: true, -+ }, -+ }), ++ sentryCloudflareVitePlugin(), ], }); ``` diff --git a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx index f6dbe06fcc132..d5f43e559d5ab 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx @@ -5,17 +5,12 @@ description: "Learn how to use the Sentry Cloudflare Vite plugin to instrument b - - The Sentry Cloudflare Vite plugin has **experimental** stability. - Configuration options and behavior may change or be removed in any release. - - The Sentry Cloudflare Vite plugin (`sentryCloudflareVitePlugin`) instruments your Worker at build time. It can: 1. **Instrument bundled dependencies**: instruments supported packages in your bundle, such as database clients and AI SDKs, giving you more traces out of the box. 2. **Auto-instrument your Worker entry**: wraps your default export with `Sentry.withSentry()`, and Durable Object, Workflow, and Agents SDK classes with the matching `instrument*WithSentry` helper at build time, so you don't need to modify your code. -Both are opt-in while the plugin is experimental. Turn them on with [`_experimental.useDiagnosticsChannelInjection`](#_experimentalusediagnosticschannelinjection) and [`_experimental.autoInstrumentation`](#_experimentalautoinstrumentation). +Both are on by default. Turn either off with [`buildTimeInstrumentation`](#buildtimeinstrumentation) and [`autoInstrumentation`](#autoinstrumentation). The quick start covers adding the plugin and creating `instrument.server.ts`. This page documents what it instruments, its @@ -25,7 +20,7 @@ options, and the details that matter once it's running. The plugin reads your wrangler config (probing `wrangler.json`, `wrangler.jsonc`, and `wrangler.toml` at the Vite root, or the file set with [`wranglerConfigPath`](#wranglerconfigpath)) to find the entry point, Durable Objects, workflows, and Agents SDK classes. It wraps Agents SDK classes (`Agent`, `AIChatAgent`, `McpAgent`) with `instrumentAgentWithSentry`, which also gives them automatic conversation IDs (see Cloudflare Agents SDK). -Any entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the Wrangler setup. +An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. To keep the plugin out of your entry entirely, set [`autoInstrumentation`](#autoinstrumentation) to `false` and wrap it yourself as shown in the Wrangler setup. With auto-instrumentation, you can optionally provide Sentry options via a co-located `instrument.server.*` file (`.ts`, `.mts`, `.js`, `.mjs`, or `.cjs`) next to your Worker entry. The plugin resolves this location from `main` in your wrangler config. For example, if `main` is `src/worker/index.ts`, place the file at `src/worker/instrument.server.ts`, not at the project root. Use `defineCloudflareOptions` for full type-checking: @@ -40,20 +35,7 @@ export default defineCloudflareOptions((env) => ({ If no `instrument.server.*` file exists, the SDK reads all configuration (DSN, release, environment, sample rate, etc.) from the Worker's `env` bindings at runtime. -Configured Durable Object, Workflow, and Agents SDK classes must be declared in the Worker entry for the plugin to wrap them automatically. The plugin cannot rewrite a class that the entry only imports or re-exports from another module. In that case, wrap the imported class in the entry with its matching helper and pass it the options callback from `instrument.server.*`: - -```typescript {filename:src/worker/index.ts} -import * as Sentry from "@sentry/cloudflare"; -import sentryOptions from "./instrument.server"; -import { MyAgent as MyAgentBase } from "./my-agent"; - -export const MyAgent = Sentry.instrumentAgentWithSentry( - sentryOptions, - MyAgentBase -); -``` - -Use `instrumentDurableObjectWithSentry` for a plain Durable Object or `instrumentWorkflowWithSentry` for a Workflow. +Configured classes are wrapped wherever they reach the Worker entry, whether they're declared there, imported from another module and exported by name, or re-exported straight through. A class you wrapped yourself is left as it is. ### Derived RPC Trace Propagation @@ -63,7 +45,7 @@ The plugin knows which bindings point at classes it wrapped itself: Durable Obje Bindings to _other_ Workers stay opt-in, because their receivers may not run Sentry. List those yourself in `instrument.server.*`; whatever you list is added on top of the derived names. -The plugin derives only the classes it wrapped itself. A class you wrapped by hand, or one re-exported from another module, runs on its own options and stays out. +The plugin derives only the classes it wrapped itself. A class you wrapped by hand runs on its own options and stays out. This applies to Vite builds only. At runtime a `DurableObjectNamespace` exposes no origin and a `Fetcher` does not say which service it points at, so a plain wrangler build still has to list its bindings. @@ -79,9 +61,6 @@ export default defineConfig({ cloudflare({ configPath: "./wrangler.agent.jsonc" }), sentryCloudflareVitePlugin({ wranglerConfigPath: "./wrangler.agent.jsonc", - _experimental: { - autoInstrumentation: true, - }, }), ], }); @@ -89,23 +68,17 @@ export default defineConfig({ - - -Experimental options that may change or be removed without notice. - - - - + -Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. +Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. Set to `false` to opt out. A package is only instrumented if it's actually bundled. A dependency you mark as external is resolved at runtime and never passes through the build, so it stays untraced. - + -Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry` (SDK version 10.69.0 or higher). Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). +Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry`. Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings`. Set to `false` to opt out. diff --git a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx index 2ff396ccfc0aa..120d277af1319 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx @@ -17,7 +17,7 @@ Everything else is the same: install, Wrangler configuration, source maps, and t `withSentry` gives you the same errors and request traces as the plugin. What a plain Wrangler build can't do is instrument your bundled dependencies. -The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `_experimental.useDiagnosticsChannelInjection` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. +The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `buildTimeInstrumentation` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. You also have to keep the wrapper in your code, and list your RPC trace propagation bindings by hand, because a plain build can't derive them. See RPC Trace Propagation. diff --git a/docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx b/docs/platforms/javascript/guides/connect/configuration/integrations/contextlines.mdx deleted file mode 100644 index 7b3af58727490..0000000000000 --- a/docs/platforms/javascript/guides/connect/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/connect/index.mdx b/docs/platforms/javascript/guides/connect/index.mdx deleted file mode 100644 index 99fcbef7ffb95..0000000000000 --- a/docs/platforms/javascript/guides/connect/index.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Connect -description: "Learn how to manually set up Sentry in your Connect app and capture your first errors." -sdk: sentry.javascript.node -fallbackGuide: javascript.node -categories: - - server - - server-only ---- - - diff --git a/docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/javascript/guides/connect/tracing/instrumentation/automatic-instrumentation.mdx deleted file mode 100644 index 2f7c38261d7f1..0000000000000 --- a/docs/platforms/javascript/guides/connect/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 Connect SDK." ---- - - diff --git a/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx b/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx index 4ea7e58cefb93..616a821ec58d8 100644 --- a/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx +++ b/docs/platforms/javascript/guides/deno/configuration/integrations/breadcrumbs.mdx @@ -10,15 +10,11 @@ _Import name: `Sentry.breadcrumbsIntegration`_ This integration is enabled by default. You can also [modify default integrations](./../#modifying-default-integrations). The `breadcrumbsIntegration` wraps native APIs to capture breadcrumbs. -By default, the Sentry SDK wraps all APIs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture `console.log` calls as breadcrumbs) via the options below. +By default, the Sentry SDK wraps all APIs. You can opt out of capturing breadcrumbs for specific parts of your application (for example, you could say don't capture outgoing fetch requests as breadcrumbs) via the options below. -## Options - -### `console` - -_Type: `boolean`_ +Console calls are captured by the `consoleIntegration`, which is enabled by default. -Log calls to `console.log`, `console.debug`, and so on. +## Options ### `fetch` @@ -31,4 +27,3 @@ Log HTTP requests done with the Fetch API. _Type: `boolean`_ Log whenever we send an event to the server. - diff --git a/docs/platforms/javascript/guides/deno/index.mdx b/docs/platforms/javascript/guides/deno/index.mdx index 3a7a85c8053af..2b272ca5d4c0f 100644 --- a/docs/platforms/javascript/guides/deno/index.mdx +++ b/docs/platforms/javascript/guides/deno/index.mdx @@ -33,12 +33,13 @@ Choose the features you want to configure, and this guide will show you how: -Import the Sentry Deno SDK directly from the npm registry, before importing any other modules: +Import the Sentry Deno SDK directly from the npm registry, before importing any other modules. The first line registers the hook that instruments your database drivers, message queues, AI libraries and web frameworks. It only works as the first import of your entry file: ```javascript {filename: main.ts} +import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports ``` @@ -47,6 +48,28 @@ import * as Sentry from "___SDK_PACKAGE___"; + + + + +The hook reads your dependencies from a local `node_modules` directory, not from Deno's global npm cache. Set `nodeModulesDir` in your `deno.json`: + + + + +```json {filename: deno.json} +{ + "imports": { + "@sentry/deno": "npm:@sentry/deno" + }, + "nodeModulesDir": "auto" +} +``` + + + + + ## Configure ### Initialize the Sentry SDK @@ -61,6 +84,7 @@ Initialize Sentry as early as possible in your app: ```javascript {filename: main.ts} +import "___SDK_PACKAGE___/import"; import * as Sentry from "___SDK_PACKAGE___"; // your other imports @@ -83,43 +107,42 @@ Sentry.init({ -### Enable Network Access +### Grant Permissions -To make sure the SDK can send events, enable network access for your Sentry ingestion domain: +Deno blocks access to the network, the file system and system information until you grant it. Start your app with all four permissions so that the SDK can send complete events. Add the other hosts your app talks to, separated by commas: ```bash -deno run --allow-net=___ORG_INGEST_DOMAIN___ index.ts +deno run \ + --allow-net=___ORG_INGEST_DOMAIN___ \ + --allow-env \ + --allow-read=. \ + --allow-sys=hostname,osRelease \ + main.ts ``` -### Allow Access to Source Files + - - - - -Grant read access to your source files so that the SDK can include your source code in stack traces: - - - +| Flag | What it gives you | +| -------------------------------- | -------------------------------------------------------------------------------------------- | +| `--allow-net=` | Delivery of events to Sentry. If a host is missing, Deno names it in the error. | +| `--allow-env` | The import hook. Without it, your app stops at start with `NotCapable: Requires env access`. | +| `--allow-read=.` | Source code in stack traces, and `app:///` paths instead of absolute paths. | +| `--allow-sys=hostname,osRelease` | The server name and the operating system version on events. | -```bash -deno run --allow-read=./src index.ts -``` +If you omit `--allow-read` or `--allow-sys`, the SDK sends events without that data and prints no warning. - - - + ### Add Readable Stack Traces With Source Maps (Optional) diff --git a/docs/platforms/javascript/guides/electron/index.mdx b/docs/platforms/javascript/guides/electron/index.mdx index b38197a202d4a..34a498d591133 100644 --- a/docs/platforms/javascript/guides/electron/index.mdx +++ b/docs/platforms/javascript/guides/electron/index.mdx @@ -104,9 +104,6 @@ Initialize the SDK in your Electron renderer processes as early as possible. All import * as Sentry from "@sentry/electron/renderer"; Sentry.init({ - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/javascript/guides/electron/configuration/options/#sendDefaultPii - sendDefaultPii: true, integrations: [ // ___PRODUCT_OPTION_START___ performance Sentry.browserTracingIntegration(), diff --git a/docs/platforms/javascript/guides/elysia/index.mdx b/docs/platforms/javascript/guides/elysia/index.mdx index 06181b77ddab6..a55c7dd5cb74e 100644 --- a/docs/platforms/javascript/guides/elysia/index.mdx +++ b/docs/platforms/javascript/guides/elysia/index.mdx @@ -21,7 +21,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - An Elysia application (`v1.4.0+`) -- Bun or Node.js 18+ (with [@elysiajs/node](https://elysiajs.com/integrations/node) adapter) +- Bun or Node.js 20.19.0+ (with [@elysiajs/node](https://elysiajs.com/integrations/node) adapter) diff --git a/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx b/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx index 75210f3a27173..593a3f32f7578 100644 --- a/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx +++ b/docs/platforms/javascript/guides/ember/configuration/ember-options.mdx @@ -1,90 +1,61 @@ --- title: Ember Options -description: "Additional configuration options for the Ember addon." +description: "Configure tracing for Ember routes, classic components, and the runloop." sidebar_order: 1 --- -All Sentry SDK options can be passed to `init`: +Pass Sentry SDK options, such as `dsn` and `tracesSampleRate`, to `Sentry.init()` in `app/app.ts`. See Set Up Sentry for the complete setup and Basic Options for SDK configuration. +Pass Ember performance options to `instrumentAppInstancePerformance()` as shown below. -```javascript -import * as Sentry from "@sentry/ember"; +## Tracing Considerations -Sentry.init({ - // Sentry options - dsn: "___PUBLIC_DSN___", -}); -``` - -The `@sentry/ember` add-on includes options to manage Ember specific instrumentation; these options are set on the add-on config directly. - -```javascript -ENV["@sentry/ember"] = { - // Ember specific options -}; -``` +To capture page loads, navigation, classic component renders, and runloop timings, call `instrumentAppInstancePerformance()` from an instance initializer. Set `tracesSampleRate` or `tracesSampler` in `Sentry.init()` to enable tracing. -The following documentation is for Ember specific configuration, for Sentry options, [see basic options](/platforms/javascript/guides/ember/configuration/options) +```typescript {filename:app/instance-initializers/sentry-performance.ts} +import type ApplicationInstance from "@ember/application/instance"; +import { instrumentAppInstancePerformance } from "@sentry/ember"; -### Tracing Considerations - -The Sentry tracing integration is already set up via the Ember add on with custom Ember instrumentation for routing, components, and the runloop. It sideloads Sentry tracing as a chunk to instrument your application. If you'd like to disable this automatic instrumentation and stop receiving the associated transactions, set `disablePerformance` in your config. See example below: +export function initialize(appInstance: ApplicationInstance): void { + instrumentAppInstancePerformance(appInstance, { + // These are the defaults. Adjust them for your application. + disableInstrumentComponents: false, + minimumComponentRenderDuration: 2, + disableRunloopPerformance: false, + minimumRunloopQueueDuration: 5, + }); +} -```javascript -ENV["@sentry/ember"] = { - disablePerformance: true, -}; +export default { initialize }; ``` -### Routes +The SDK skips this instrumentation during FastBoot server rendering. To disable automatic Ember performance instrumentation, omit the instance initializer. -If you would like to capture timings for the `beforeModel`, `model`, `afterModel` hooks as well as `setupController` in one of your Routes, `@sentry/ember` exports a `instrumentRoutePerformance` function which can be used by replacing the default export with a wrapped Route. +## Routes -```javascript +To capture timings for a route's `beforeModel`, `model`, `afterModel`, and `setupController` hooks, wrap its default export with `instrumentRoutePerformance()`. + +```typescript {filename:app/routes/my-route.ts} import Route from "@ember/routing/route"; import { instrumentRoutePerformance } from "@sentry/ember"; class MyRoute extends Route { model() { - //... + // Load your model here. } } export default instrumentRoutePerformance(MyRoute); ``` -### Classic Components +## Classic Components -The render times of classic components are also enabled by default, with a setting to capture render timings only above a certain duration. To change this minimum, you can modify `minimumComponentRenderDuration` in your config. +After you call `instrumentAppInstancePerformance()`, the SDK captures classic component render timings by default. Set `minimumComponentRenderDuration` in the initializer's options to change the minimum duration in milliseconds. The default is `2`; set it to `0` to capture all classic component render timings. -```javascript -ENV["@sentry/ember"] = { - minimumComponentRenderDuration: 0, // Setting this to zero will capture all classic components. -}; -``` +Set `disableInstrumentComponents: true` in the same options object to disable component instrumentation. -To disable component instrumentation you can set `disableInstrumentComponents` in your config. +## Runloop -```javascript -ENV["@sentry/ember"] = { - disableInstrumentComponents: true, -}; -``` - -### Runloop +After you call `instrumentAppInstancePerformance()`, the SDK instruments queues in your application's runloop by default. Set `minimumRunloopQueueDuration` in the initializer's options to change the minimum duration in milliseconds. The default is `5`; set it to `0` to capture all runloop queue durations. -The duration of each queue in your application's runloop is instrumented by default, as long as the duration of the queue is longer than a threshold defined in your config by `minimumRunloopQueueDuration` - -```javascript -ENV["@sentry/ember"] = { - minimumRunloopQueueDuration: 0, // Setting this to zero will capture all runloop queue durations -}; -``` - -If you would like to disable runloop instrumentation you can set `disableRunloopPerformance` in your config. - -```javascript -ENV["@sentry/ember"] = { - disableRunloopPerformance: true, -}; -``` +Set `disableRunloopPerformance: true` in the same options object to disable runloop instrumentation. diff --git a/docs/platforms/javascript/guides/ember/index.mdx b/docs/platforms/javascript/guides/ember/index.mdx index c704250dff2ec..63893ca7ba547 100644 --- a/docs/platforms/javascript/guides/ember/index.mdx +++ b/docs/platforms/javascript/guides/ember/index.mdx @@ -51,12 +51,12 @@ Choose the features you want to configure, and this guide will show you how: -Configuration should happen as early as possible in your application's lifecycle. Add the following to your `app/app.js` file: +Call `Sentry.init()` in `app/app.ts` before defining your `Application` class. -```javascript {filename:app.js} +```typescript {filename:app/app.ts} import Application from "@ember/application"; import Resolver from "ember-resolver"; import loadInitializers from "ember-load-initializers"; @@ -103,12 +103,46 @@ export default class App extends Application { podModulePrefix = config.podModulePrefix; Resolver = Resolver; } + +loadInitializers(App, config.modulePrefix); +``` + + + + + + + +### Enable Performance Instrumentation + + + + + +To capture page loads, navigation, classic component renders, and runloop timings, create an instance initializer that calls `instrumentAppInstancePerformance()`. The `tracesSampleRate` option in `Sentry.init()` controls how much tracing data Sentry captures. + +The SDK skips this instrumentation during FastBoot server rendering. To customize it, see Ember Options. + + + + +```typescript {filename:app/instance-initializers/sentry-performance.ts} +import type ApplicationInstance from "@ember/application/instance"; +import { instrumentAppInstancePerformance } from "@sentry/ember"; + +export function initialize(appInstance: ApplicationInstance): void { + instrumentAppInstancePerformance(appInstance); +} + +export default { initialize }; ``` + + ### Add Readable Stack Traces With Source Maps (Optional) diff --git a/docs/platforms/javascript/guides/eve/index.mdx b/docs/platforms/javascript/guides/eve/index.mdx index 1d189e3e8d404..fde9b2967a745 100644 --- a/docs/platforms/javascript/guides/eve/index.mdx +++ b/docs/platforms/javascript/guides/eve/index.mdx @@ -118,7 +118,7 @@ export default defineInstrumentation( With this setup, Sentry captures errors thrown by your agent and AI spans for every turn — model calls, tool executions, token usage, and latency — along with outgoing HTTP and `fetch` requests. It also groups every turn in an Eve session into one Sentry conversation. Prompts and model outputs are recorded on your agent spans by default, so the Agent Tracing transcript shows the full exchange without any extra configuration. -To also instrument the rest of your Node app, see [Instrument Other Dependencies](#instrument-other-dependencies) below. To review what's captured and turn recording of prompts and responses off, see [Privacy Controls](#privacy-controls). +To also instrument the rest of your Node app, see [Instrument Other Dependencies](#instrument-other-dependencies) below. To review what's captured and turn recording of prompts and responses off, see [Control the Data You Send to Sentry](#control-the-data-you-send-to-sentry-optional). ## Verify @@ -133,20 +133,9 @@ If no data appears, confirm that: -## Privacy Controls +## Control the Data You Send to Sentry (Optional) -Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your agent spans by default. Review the data your agent handles and tighten this before production. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: - -```typescript {filename:agent/instrumentation/sentry.ts} -export default defineInstrumentation( - Sentry.eveInstrumentation({ - dsn: "___PUBLIC_DSN___", - dataCollection: { - genAI: { inputs: false, outputs: false }, - }, - }) -); -``` + ## Customize Conversation Grouping diff --git a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx b/docs/platforms/javascript/guides/fastify/features/error-handler.mdx index af18d44139e9d..43e3c0f8cf935 100644 --- a/docs/platforms/javascript/guides/fastify/features/error-handler.mdx +++ b/docs/platforms/javascript/guides/fastify/features/error-handler.mdx @@ -1,34 +1,36 @@ --- title: Fastify Error Handler -description: "Learn about Sentry's Fastify SDK Error Handler and how to configure it." +description: "Learn how Sentry's Fastify integration captures errors and how to configure it." --- -The Fastify error handler integration automatically captures errors in your Fastify application and sends them to Sentry. By default, it captures all errors with status codes 5xx and above, as well as errors with status codes 2xx and below. +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 -You can configure the error handler using the `setupFastifyErrorHandler` function: +To control which errors are captured, pass `shouldHandleError` to `Sentry.fastifyIntegration`: ```javascript import * as Sentry from "@sentry/node"; -import { setupFastifyErrorHandler } from "@sentry/fastify"; - -const app = fastify(); -// Initialize Sentry Sentry.init({ dsn: "your-dsn", + integrations: [ + Sentry.fastifyIntegration({ + shouldHandleError(error, request, reply) { + return reply.statusCode >= 500; + }, + }), + ], }); - -// Setup the error handler -setupFastifyErrorHandler(app); ``` ## Options -The `setupFastifyErrorHandler` function accepts an optional options object that can be used to customize the error handler. +`Sentry.fastifyIntegration` accepts the following options: -- `shouldHandleError` _version 9.9.0+_ +- `shouldHandleError` A function that determines whether an error should be captured. @@ -40,24 +42,16 @@ declare function shouldHandleError( ): boolean; ``` -```javascript -setupFastifyErrorHandler(app, { - shouldHandleError(error, request, reply) { - return reply.statusCode >= 500 || reply.statusCode <= 399; - }, -}); -``` - If using TypeScript, you can cast the request and reply to get full type safety. ```typescript -import { FastifyRequest, FastifyReply } from "fastify"; +import type { FastifyRequest, FastifyReply } from "fastify"; -setupFastifyErrorHandler(app, { +Sentry.fastifyIntegration({ shouldHandleError(error, minimalRequest, minimalReply) { const request = minimalRequest as FastifyRequest; const reply = minimalReply as FastifyReply; - return reply.statusCode >= 500 || reply.statusCode <= 399; + return reply.statusCode >= 500; }, }); ``` diff --git a/docs/platforms/javascript/guides/firebase/index.mdx b/docs/platforms/javascript/guides/firebase/index.mdx index f34b8fadbc14d..3db1029ac534b 100644 --- a/docs/platforms/javascript/guides/firebase/index.mdx +++ b/docs/platforms/javascript/guides/firebase/index.mdx @@ -96,10 +96,20 @@ Create an initialization file (for example, `instrument.js`) that imports and in ```javascript {filename:instrument.js} const Sentry = require("@sentry/node"); +// ___PRODUCT_OPTION_START___ profiling +const { nodeProfilingIntegration } = require("@sentry/profiling-node"); +// ___PRODUCT_OPTION_END___ profiling Sentry.init({ dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ profiling + + integrations: [ + // Add our Profiling integration + nodeProfilingIntegration(), + ], + // ___PRODUCT_OPTION_END___ profiling // ___PRODUCT_OPTION_START___ performance // Add Tracing by setting tracesSampleRate @@ -111,9 +121,12 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ performance // ___PRODUCT_OPTION_START___ profiling - // Set profilesSampleRate to 1.0 to profile 100% of sampled transactions. - // This is relative to tracesSampleRate - profilesSampleRate: 1.0, + // 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 }); ``` diff --git a/docs/platforms/javascript/guides/hono/index.mdx b/docs/platforms/javascript/guides/hono/index.mdx index e8c0afc71400a..a76d157297271 100644 --- a/docs/platforms/javascript/guides/hono/index.mdx +++ b/docs/platforms/javascript/guides/hono/index.mdx @@ -188,10 +188,12 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ performance // ___PRODUCT_OPTION_START___ profiling - // Set profilesSampleRate relative to tracesSampleRate + // 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 }); ``` diff --git a/docs/platforms/javascript/guides/mastra/cloudflare.mdx b/docs/platforms/javascript/guides/mastra/cloudflare.mdx index 4ef25a0cc8bc7..20168aff2ea71 100644 --- a/docs/platforms/javascript/guides/mastra/cloudflare.mdx +++ b/docs/platforms/javascript/guides/mastra/cloudflare.mdx @@ -87,11 +87,16 @@ With the plugin in place, `Sentry.init()` runs automatically — you don't add a -### Privacy Controls +### Control the Data You Send to Sentry (Optional) -The SDK will record generative AI inputs and outputs (the prompts your agent sends and the model responses it receives) by default. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. -```typescript {filename:src/instrument.server.ts} +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option: + +```typescript {filename:src/instrument.server.ts} {3-5} export default (env: Env) => ({ dsn: "___PUBLIC_DSN___", dataCollection: { @@ -100,7 +105,7 @@ export default (env: Env) => ({ }); ``` -See [`dataCollection` documentation](../configuration/options/#dataCollection) for details on privacy control options. +For the full list of categories and their defaults, see the [`dataCollection` options](../configuration/options/#dataCollection). diff --git a/docs/platforms/javascript/guides/mastra/index.mdx b/docs/platforms/javascript/guides/mastra/index.mdx index 49b9a2f2ff122..6e3318bcf5bd0 100644 --- a/docs/platforms/javascript/guides/mastra/index.mdx +++ b/docs/platforms/javascript/guides/mastra/index.mdx @@ -129,20 +129,9 @@ Preload the instrument file when you start Mastra by passing it through `--custo -### Privacy Controls +### Control the Data You Send to Sentry (Optional) -The SDK will record generative AI inputs and outputs (the prompts your agent sends and the model responses it receives) by default. To turn recording off, set `genAI.inputs` and `genAI.outputs` to `false` in `dataCollection`: - -```javascript {filename:src/mastra/public/instrument.mjs} -Sentry.init({ - dsn: "___PUBLIC_DSN___", - dataCollection: { - genAI: { inputs: false, outputs: false }, - }, -}); -``` - -See [`dataCollection` documentation](./configuration/options/#dataCollection) for details on privacy control options. + diff --git a/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx b/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx deleted file mode 100644 index 72438c712846d..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: CommonJS (CJS) -sidebar_order: 9 -description: "Learn about running Sentry in an CJS application." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. -Nest.js, by default, transpiles your TypeScript code into CommonJS. - -You can follow the installation instructions in the SDK's Quick Start guide. diff --git a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx deleted file mode 100644 index 3c31674c680bb..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: ESM Without CLI Flag -sidebar_order: 11 -description: "Learn about running Sentry in an ESM application, without the --import flag." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you'll most likely want to follow the ESM instructions. However, if you want to avoid using the `--import` command line option, for example, if you have no way of configuring a CLI flag, you can also follow an alternative setup that involves importing the `instrument.mjs` file directly in your application. - - - -This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). - -As a result, the Sentry SDK will **not** capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. - -We recommend using this only if the `--import` flag is not an option for you. - - - -**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/nestjs"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -**Step 2:** Import the `instrument.mjs` file before importing any other modules in your in the `main.ts` file of your application. This ensures that Sentry can automatically instrument all modules in your application: - -```javascript {filename: main.ts} -// Import this first! -import "./instrument"; - -// Now import other modules -import { NestFactory } from "@nestjs/core"; -// ... -// Your application code goes here -``` diff --git a/docs/platforms/javascript/guides/nestjs/install/esm.mdx b/docs/platforms/javascript/guides/nestjs/install/esm.mdx deleted file mode 100644 index 7a8297bd04404..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/esm.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: ESM (MJS) -sidebar_order: 10 -description: "Learn about running Sentry in an ESM application." -supported: - - javascript.nestjs ---- - - - Are you unsure if you should use this installation method? Review our - [installation methods](../). - - -When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. - -**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/nestjs"; - -// Ensure to call this before importing any other modules! -Sentry.init({ - dsn: "___PUBLIC_DSN___", - - // Add Tracing by setting tracesSampleRate - // We recommend adjusting this value in production - tracesSampleRate: 1.0, -}); -``` - -**Step 2:** Load `instrument.mjs` with the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter when your application starts. Set it through `NODE_OPTIONS`, which applies to the Node.js process that runs your app: - -```bash -# Note: This is only available for Node v18.19.0 onwards. -NODE_OPTIONS="--import ./instrument.mjs" nest start -``` - -If you run your build output directly, pass the flag to `node` instead: - -```bash -node --import ./instrument.mjs dist/main.js -``` - -We do not support ESM in Node versions before 18.19.0. - -## Troubleshooting ESM Instrumentation - -By default, all packages are automatically wrapped by -[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to -aid instrumenting them. - -If `import-in-the-middle` encounters problems wrapping a package, you may see -syntax errors at runtime or logged errors in your console: - -```logs -SyntaxError: The requested module '...' does not provide an export named '...' -(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js' -``` - -To confirm that these errors are caused by `import-in-the-middle`, -disable it by setting `registerEsmLoaderHooks` to false. Note, this will also -disable tracing instrumentation: - -```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} -import * as Sentry from "@sentry/nestjs"; - -Sentry.init({ - registerEsmLoaderHooks: false, -}); -``` diff --git a/docs/platforms/javascript/guides/nestjs/install/index.mdx b/docs/platforms/javascript/guides/nestjs/install/index.mdx deleted file mode 100644 index eedeb840fe395..0000000000000 --- a/docs/platforms/javascript/guides/nestjs/install/index.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Installation Methods -sidebar_order: 1 -description: "Review our alternate installation methods for Sentry using Nest.js." -supported: - - javascript.nestjs ---- - - - -## How To Decide Which Installation Method To Use - -Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. -Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, this will not work, in which case you can follow the [ESM docs](./esm). - -Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. In this case, you should follow the [CommonJS instructions](./commonjs). - -### My application uses the default Nest.js setup - -Nest.js transpiles to CJS by default, so you should follow the [CommonJS installation instructions](./commonjs). Keep reading if you have a more customized application or build setup. - -### My application uses `require` - -If you're using `require()` in your application, you should follow the [CommonJS instructions](./commonjs). - -### My application uses `import` - -If you're using `import` in your application, your installation method depends on how your application is _run_. If you compile your application (for example, into a `/dist` folder or similar) before running it, you need to check how the compiled code looks like. Is the compiled code using `require`? Then you should follow the [CommonJS instructions](./commonjs). If the compiled code is using `import`, you should follow the [ESM instructions](./esm). - -If you do not compile your code, you'll need to follow the [ESM instructions](./esm). diff --git a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx index 5216a58eb971f..b243a2da237f2 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/build/index.mdx @@ -292,6 +292,72 @@ Excluded routes will appear as raw URLs in transaction names instead of paramete + + +Annotates your React components with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time, so Sentry can identify which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). + +Disabled unless you set a value. Set `enabled: true` to turn it on, and `ignoredComponents` to skip components by name. + +This option drives both Webpack and Turbopack builds. On Turbopack it requires **Next.js 16+**; on an older version the SDK warns at build time. + +```javascript {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], + }, +}); +``` + + + The bundler-specific `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options are deprecated in + favor of this one and will be removed in the next major version. If both a + bundler-specific option and this one are set, the bundler-specific one wins + for that bundler. + + + + + + +Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to tell your code apart from third-party code, so you can drop errors coming from browser extensions, injected scripts, and third-party widgets. + +The value must match an entry in the `filterKeys` array of your `thirdPartyErrorFilterIntegration` configuration. This option works for both Webpack and Turbopack builds. + +```javascript {tabTitle:Config} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + applicationKey: "my-nextjs-app", +}); +``` + +```javascript {tabTitle:Client} {filename:instrumentation-client.ts} +import * as Sentry from "@sentry/nextjs"; + +Sentry.init({ + integrations: [ + Sentry.thirdPartyErrorFilterIntegration({ + filterKeys: ["my-nextjs-app"], + behaviour: "drop-error-if-exclusively-contains-third-party-frames", + }), + ], +}); +``` + + + + + +Automatically instrument server-side dependencies at build time. This is what gives you tracing for libraries that can't be patched at runtime, including on platforms like Vercel and Netlify. + +Set to `false` to turn it off. Turbopack support requires **Next.js 16+**; the Webpack path works on earlier versions. + + + ## Next.js Webpack Options @@ -343,118 +409,32 @@ Automatically create cron monitors in Sentry for your Vercel Cron Jobs if config - - Pass configuration options directly to the [Sentry Webpack - Plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) that ships with - the Sentry Next.js SDK. If `withSentryConfig` doesn't provide the option you - need to modify, you may override the `sentryWebpackPluginOptions` using this - option. - - This option is considered unstable, and its API may change in a breaking way - in any release. - - - - - -Enables React component name tracking. When enabled, it annotates React components with data attributes that allow Sentry to track which components users interacted with in features like Session Replay and breadcrumbs. - - - - - -A list of React component names to exclude from component annotation. - - - Configuration options for tree shaking. Refer to the [tree shaking documentation](/platforms/javascript/guides/nextjs/configuration/tree-shaking) for more details. -## Experimental Turbopack Options +## Experimental Options - These options are experimental and require **Next.js 16+**. Their API may - change in future releases. + These options are experimental. Their API may change in future releases. - - - - -Enables React component name annotation for Turbopack builds. This is the Turbopack equivalent of [`webpack.reactComponentAnnotation`](#webpackreactcomponentannotationenabled). - -When enabled, React components are annotated with `data-sentry-component`, `data-sentry-element`, and `data-sentry-source-file` attributes at build time. These attributes allow Sentry to identify which components users interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). - -```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - }, - }, -}); -``` - - + - +Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons/) in Sentry for the Vercel Cron Jobs configured in your `vercel.json`, by detecting cron requests and emitting check-ins from spans. -A list of React component names to exclude from annotation in Turbopack builds. +Unlike [`webpack.automaticVercelMonitors`](#webpack.automaticVercelMonitors), which wraps route handlers at build time, this works with both Webpack and Turbopack and with both the App Router and the Pages Router. If you enable both, the SDK uses this one and warns that the other is redundant. ```javascript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { _experimental: { - turbopackReactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + vercelCronsMonitoring: true, }, }); ``` - - - - - -Application key used by [`thirdPartyErrorFilterIntegration`](/platforms/javascript/configuration/filtering/#using-thirdpartyerrorfilterintegration) to distinguish first-party code from third-party code in Turbopack builds. This is the Turbopack equivalent of setting `applicationKey` via the Sentry Webpack Plugin. - -When set, a Turbopack loader injects `_sentryModuleMetadata` into every first-party module, enabling the `thirdPartyErrorFilterIntegration` to filter errors from browser extensions, injected scripts, and third-party widgets. - -The value must match the `filterKeys` array in your `thirdPartyErrorFilterIntegration` configuration. - -```javascript {tabTitle:Config} {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; - -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "my-nextjs-app", - }, -}); -``` - -```javascript {tabTitle:Client} {filename:instrumentation-client.ts} -import * as Sentry from "@sentry/nextjs"; - -Sentry.init({ - integrations: [ - Sentry.thirdPartyErrorFilterIntegration({ - filterKeys: ["my-nextjs-app"], - behaviour: "drop-error-if-exclusively-contains-third-party-frames", - }), - ], -}); -``` - - diff --git a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx index 0e1449901922c..d8d95d4d7b710 100644 --- a/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx +++ b/docs/platforms/javascript/guides/nextjs/configuration/tree-shaking.mdx @@ -57,7 +57,7 @@ The following sections cover each available tree-shaking option and how to confi -Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product (controlled by the `enableLogs` option) or your app's logging. +Setting this option to true will remove all Sentry SDK debug logging code (the console logs that appear when you set `debug: true` in your SDK configuration). This doesn't affect Sentry's Logs product or your app's logging. diff --git a/docs/platforms/javascript/guides/nextjs/index.mdx b/docs/platforms/javascript/guides/nextjs/index.mdx index bab538c431b57..761c52c7e23e1 100644 --- a/docs/platforms/javascript/guides/nextjs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/index.mdx @@ -72,6 +72,8 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay ], }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -146,7 +148,7 @@ Your `next.config.ts` is wrapped with `withSentryConfig` to enable source map up ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", diff --git a/docs/platforms/javascript/guides/nextjs/logs/index.mdx b/docs/platforms/javascript/guides/nextjs/logs/index.mdx index 44dba6e642a3c..e97bed7b8d1a3 100644 --- a/docs/platforms/javascript/guides/nextjs/logs/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/logs/index.mdx @@ -26,10 +26,6 @@ Logs work across all Next.js runtimes: - **Server** — Node.js server-side logging - **Edge** — Edge runtime logging - - On SDK versions below `10.71.0`, logs are opt-in. Set `enableLogs: true` in your `Sentry.init` in all three runtime files to send them. - - @@ -386,7 +382,7 @@ Any attributes set via `Sentry.setAttribute()` / `Sentry.setAttributes()` (or di ### Logs not appearing -On SDK versions below `10.71.0`, logs are opt-in. Make sure `enableLogs: true` is set in **all** Sentry config files: +Logs are captured as soon as you call a `Sentry.logger.*` method or add a logging integration. Check that the runtime you're logging from initializes the SDK at all: - `instrumentation-client.ts` (client) - `sentry.server.config.ts` (server) diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx index 9003589af185f..b81d9a1f6f907 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/index.mdx @@ -86,7 +86,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -154,10 +154,7 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay }); -// ___PRODUCT_OPTION_START___ performance -// This export will instrument router navigations export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; -// ___PRODUCT_OPTION_END___ performance ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx index 0f413ffe91036..ebd66d0b4c803 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/pages-router.mdx @@ -81,7 +81,7 @@ Extend your app's default Next.js options by adding `withSentryConfig` into your ```typescript {tabTitle:Webpack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -112,7 +112,7 @@ export default withSentryConfig(nextConfig, { ```typescript {tabTitle:Turbopack} {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // Your existing Next.js configuration @@ -137,7 +137,7 @@ export default withSentryConfig(nextConfig, { Create the following files in your application's root directory (or `src` folder if you have one): -- `sentry.client.config.ts` - Client-side SDK initialization +- `instrumentation-client.ts` - Client-side SDK initialization - `sentry.server.config.ts` - Server-side SDK initialization - `sentry.edge.config.ts` - Edge runtime SDK initialization (if using edge routes) @@ -146,10 +146,16 @@ Create the following files in your application's root directory (or `src` folder variable like `NEXT_PUBLIC_SENTRY_DSN`. + + +Older setups initialized the browser SDK in `sentry.client.config.ts`. That file is deprecated and is **ignored entirely by Turbopack builds**, which leaves your app with no browser SDK and no build error to tell you. Use `instrumentation-client.ts` instead. + + + -```typescript {tabTitle:Client} {mdExpandTabs} {filename:sentry.client.config.ts} +```typescript {tabTitle:Client} {mdExpandTabs} {filename:instrumentation-client.ts} import * as Sentry from "@sentry/nextjs"; Sentry.init({ @@ -174,6 +180,8 @@ Sentry.init({ replaysOnErrorSampleRate: 1.0, // ___PRODUCT_OPTION_END___ session-replay }); + +export const onRouterTransitionStart = Sentry.captureRouterTransitionStart; ``` ```typescript {tabTitle:Server} {filename:sentry.server.config.ts} @@ -218,6 +226,43 @@ Monitor your [usage stats](https://sentry.io/orgredirect/organizations/:orgslug/ +### Register Server-Side SDK + +Create a [Next.js Instrumentation file](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) named `instrumentation.ts` in your project root (or `src` folder) to load it at server startup. + +The `onRequestError` export is what captures server-side errors in the Pages Router, including errors thrown in API routes and `getServerSideProps`. + + + The `onRequestError` hook requires `@sentry/nextjs` version `8.28.0` or higher + and Next.js 15. + + + + + +```typescript {filename:instrumentation.ts} +import * as Sentry from "@sentry/nextjs"; + +export async function register() { + if (process.env.NEXT_RUNTIME === "nodejs") { + await import("./sentry.server.config"); + } + + if (process.env.NEXT_RUNTIME === "edge") { + await import("./sentry.edge.config"); + } +} + +// Capture errors from API routes, getServerSideProps, and middleware +export const onRequestError = Sentry.captureRequestError; +``` + + + + + + + ### Capture Pages Router Errors Create or update `pages/_error.tsx` to capture errors that occur during server-side rendering or in page components. @@ -332,7 +377,7 @@ Session Replay captures video-like reproductions of user sessions. It's configur -```typescript {filename:sentry.client.config.ts} +```typescript {filename:instrumentation-client.ts} Sentry.init({ dsn: "___PUBLIC_DSN___", @@ -453,16 +498,33 @@ Automatically create [Cron Monitors](/product/monitors-and-alerts/monitors/crons ### Enable Automatic Cron Monitoring -Add the `automaticVercelMonitors` option to your `next.config.ts`. +There are two ways to do this, depending on how you build: + +- `_experimental.vercelCronsMonitoring` creates check-ins from spans. It works with both Turbopack and Webpack, and with both routers. Prefer this one. +- `webpack.automaticVercelMonitors` wraps your route handlers at build time. It only works with Webpack and the Pages Router. + +If you enable both, the SDK uses the span-based approach and logs a warning telling you to drop the other one. -```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +```typescript {tabTitle:Span-based} {mdExpandTabs} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - automaticVercelMonitors: true, + _experimental: { + vercelCronsMonitoring: true, + }, +}); +``` + +```typescript {tabTitle:Webpack} {filename:next.config.ts} +import { withSentryConfig } from "@sentry/nextjs/config"; + +export default withSentryConfig(nextConfig, { + webpack: { + automaticVercelMonitors: true, + }, }); ``` diff --git a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx index f3cb732af68c2..c375210378619 100644 --- a/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx +++ b/docs/platforms/javascript/guides/nextjs/manual-setup/webpack-setup.mdx @@ -20,9 +20,10 @@ For a complete reference of all build configuration options, see the [Build Conf | ------------------------------- | ------------------------------- | ---------------------------------------------------- | | Server function instrumentation | Automatic via Next.js telemetry | Build-time code injection | | Middleware instrumentation | Automatic via Next.js telemetry | Build-time code injection | +| Dependency instrumentation | Next.js 16+ | Supported | | Source map upload | Post-compile during build | During build via plugin (default) | | Route exclusion | Not supported | Supported via `webpack.excludeServerRoutes` | -| React component annotation | Experimental (Next.js 16+) | Supported via `webpack.reactComponentAnnotation` | +| React component annotation | Next.js 16+ | Supported | | Logger tree-shaking | Not supported | Supported via `webpack.treeshake.removeDebugLogging` | ## Auto-Instrumentation Options @@ -44,7 +45,7 @@ These options are enabled by default with Webpack. Disable them if you prefer ma ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -92,7 +93,7 @@ Specify routes as URL paths (not file system paths). Routes must have a leading ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { webpack: { @@ -129,7 +130,7 @@ The Sentry Webpack Plugin runs during each webpack compilation and uploads sourc ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -160,7 +161,7 @@ Enable post-build upload for faster builds. All source maps are uploaded once af ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", @@ -182,38 +183,24 @@ export default withSentryConfig(nextConfig, { -### Advanced Webpack Plugin Options +### Control Which Files Are Uploaded -Pass options directly to the underlying Sentry Webpack Plugin for advanced configuration. - - - The `unstable_sentryWebpackPluginOptions` API may change in future releases. - - - - These options only apply when `useRunAfterProductionCompileHook` is `false` - (the default). - +If the defaults pick up too much or too little, narrow the upload with the `sourcemaps` options. These are top-level options and apply to both Webpack and Turbopack builds. See [Build Configuration](/platforms/javascript/guides/nextjs/configuration/build/) for the full list. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, - webpack: { - // Advanced Webpack plugin options - unstable_sentryWebpackPluginOptions: { - sourcemaps: { - assets: ["./build/**/*.js", "./build/**/*.map"], - ignore: ["node_modules/**"], - }, - }, + sourcemaps: { + assets: [".next/**/*.js", ".next/**/*.map"], + ignore: ["**/node_modules/**"], }, }); ``` @@ -265,13 +252,15 @@ export async function submitForm(formData: FormData) { ## React Component Annotation -With Webpack, you can enable React component name tracking. This annotates React components with `data-sentry-*` attributes that allow Sentry to identify which components users interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). +Component annotation adds `data-sentry-*` attributes to your React components at build time, so Sentry can tell you which component a user interacted with in [Session Replay](/platforms/javascript/guides/nextjs/session-replay/) and [breadcrumbs](/platforms/javascript/guides/nextjs/enriching-events/breadcrumbs/). - For Turbopack builds, component annotation is available as an experimental - feature requiring Next.js 16+. See - [`_experimental.turbopackReactComponentAnnotation`](/platforms/javascript/guides/nextjs/configuration/build/#_experimentalturbopackreactcomponentannotationenabled) - in the build options reference. + `reactComponentAnnotation` is a top-level option and drives both Webpack and + Turbopack builds. On Turbopack it requires Next.js 16 or higher, enable it on + an older version and the SDK warns at build time. The bundler-specific + `webpack.reactComponentAnnotation` and + `_experimental.turbopackReactComponentAnnotation` options still work but are + deprecated, and will be removed in the next major version. @@ -287,13 +276,11 @@ Enable `reactComponentAnnotation` to track component names in your application. ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - }, + reactComponentAnnotation: { + enabled: true, }, }); ``` @@ -316,14 +303,12 @@ If you have components you don't want annotated (for privacy or performance reas ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { - webpack: { - reactComponentAnnotation: { - enabled: true, - ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], - }, + reactComponentAnnotation: { + enabled: true, + ignoredComponents: ["SensitiveForm", "InternalDebugPanel"], }, }); ``` @@ -360,7 +345,7 @@ tunnelRoute: true, // Auto-generated random route ```typescript {filename:next.config.ts} -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; export default withSentryConfig(nextConfig, { // Use a fixed route (recommended) @@ -377,20 +362,22 @@ export default withSentryConfig(nextConfig, { If you're upgrading to Turbopack: -1. **Remove webpack-only options** - `excludeServerRoutes` and `unstable_sentryWebpackPluginOptions` have no effect with Turbopack +1. **Drop webpack-only options** - anything under `webpack` has no effect with Turbopack, including `excludeServerRoutes` and `treeshake` 2. **Understand source map changes** - Turbopack always uses post-build upload (no plugin-based upload option) 3. **Test auto-instrumentation** - Turbopack uses Next.js telemetry instead of build-time injection; verify your monitoring still works ```typescript {filename:next.config.ts} // Before (Webpack) export default withSentryConfig(nextConfig, { - excludeServerRoutes: ["/api/health"], + webpack: { + excludeServerRoutes: ["/api/health"], + }, tunnelRoute: "/sentry-tunnel", }); // After (Turbopack) export default withSentryConfig(nextConfig, { - // excludeServerRoutes is not supported with Turbopack + // webpack.excludeServerRoutes is not supported with Turbopack tunnelRoute: "/sentry-tunnel", }); ``` diff --git a/docs/platforms/javascript/guides/nextjs/tracing/index.mdx b/docs/platforms/javascript/guides/nextjs/tracing/index.mdx index 802c9ced62d90..69e895b9905bf 100644 --- a/docs/platforms/javascript/guides/nextjs/tracing/index.mdx +++ b/docs/platforms/javascript/guides/nextjs/tracing/index.mdx @@ -185,7 +185,7 @@ export async function submitForm(formData: FormData) { ## Web Vitals -The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) on every page load. These metrics measure real user experience: +The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboards/frontend/web-vitals/) in the browser. These metrics measure real user experience: | Metric | What It Measures | Threshold (Good) | |--------|------------------|------------------| @@ -195,7 +195,9 @@ The SDK automatically captures [Web Vitals](/product/dashboards/sentry-dashboard | **FCP** | First Contentful Paint — initial render | ≤ 1s | | **TTFB** | Time to First Byte — server response | ≤ 100ms | -Web Vitals appear as measurements on page load transactions and feed into your [Performance Score](/product/dashboards/sentry-dashboards/frontend/web-vitals/#performance-score). See [Web Vitals Concepts](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/) for detailed explanations of each metric. +Web Vitals feed into your [Performance Score](/product/dashboards/sentry-dashboards/frontend/web-vitals/#performance-score). In the default stream mode, LCP, CLS, and INP are sent as Web Vital spans. + +To configure collection, see the WebVitals integration. For metric definitions and differences between SDK versions, see [Web Vitals Concepts](/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts/). ## Custom Instrumentation diff --git a/docs/platforms/javascript/guides/nitro/index.mdx b/docs/platforms/javascript/guides/nitro/index.mdx index 50c232c5ac87b..52c8d5cbeb921 100644 --- a/docs/platforms/javascript/guides/nitro/index.mdx +++ b/docs/platforms/javascript/guides/nitro/index.mdx @@ -20,7 +20,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - A Nitro application (`3.0.260415-beta` or newer) -- Node.js 18.19.0+ +- Node.js 20.19.0+ diff --git a/docs/platforms/javascript/guides/nuxt/index.mdx b/docs/platforms/javascript/guides/nuxt/index.mdx index f28e244552bc4..ce1cc6c33dff3 100644 --- a/docs/platforms/javascript/guides/nuxt/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/index.mdx @@ -48,12 +48,7 @@ To test the server side as well, refer to the "Verify" section in the [Manual se To test Sentry, you can run your Nuxt application in either production or development mode. We **recommend testing in production mode** as it most closely resembles your deployed application's environment. - - By default, the SDK will add the server config as `sentry.server.config.mjs` - to the build. To find the exact path to this file, enable `debug` mode in your - Sentry configuration within `nuxt.config.ts`. Sentry will then print the exact - path during the build process. - +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. To learn more, see Server-Side Installation. ### Run in Production Mode (Recommended) @@ -61,14 +56,14 @@ We **recommend testing in production mode** as it most closely resembles your de -After building with `nuxi build`, run your project and make sure to load Sentry on the server side by explicitly adding it via `--import` (read more about this flag in [Installation Methods](/platforms/javascript/guides/nuxt/install)). +Build your project with `nuxi build`, then start the server. -``` +```bash # Start your app after building your project with `nuxi build` -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +node .output/server/index.mjs ``` @@ -81,16 +76,16 @@ node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs -The server config file is generated in the `.nuxt` directory the first time you run `nuxt dev`. If you delete your `.nuxt` directory, you'll need to run `nuxt dev` once without the `NODE_OPTIONS` variable to regenerate it. +Sentry also monitors the server side during development. Start the dev server as usual. -If you only want to use Sentry on the client-side or only need basic error monitoring on the server side, you can omit the `--import` flag when running your application. +Spans from some libraries, such as database clients, can be missing in development mode. +Errors and request traces always work. To learn more, see Development Mode. -``` -# Run the dev server with the --import flag after running `nuxt dev` once (without the flag) -NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev +```bash +nuxt dev ``` diff --git a/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx new file mode 100644 index 0000000000000..cca2c3cb97831 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/index__v10.x.mdx @@ -0,0 +1,140 @@ +--- +title: Nuxt +description: Learn how to set up and configure Sentry in your Nuxt application using the installation wizard, capture your first errors, and view them in Sentry. +sdk: sentry.javascript.nuxt +categories: + - javascript + - browser + - server +--- + + + + + +## Install + + + + + + + + + +## Avoid Ad Blockers With Tunneling (Optional) + + + +## Control the Data You Send to Sentry (Optional) + + + +## Verify Your Setup + +The `sentry init` command checks the integration files it creates or modifies before it finishes. To confirm runtime events are reaching Sentry, start your Nuxt app, exercise the parts of your app that should send events, and then check your Sentry project. + +If you used the Nuxt installation wizard instead, you can also verify your setup with the example page or component it creates. + + +The wizard creates a `SentryErrorButton` component when it fails to add an example page to your project. This usually happens if you don't have a `app.vue` file or if that file does not contain the `NuxtPage` component. To verify your setup, follow these steps before continuing with the next section, "View Captured Data in Sentry": + +1. Add the `SentryErrorButton` component to a page and open it in your browser. For most Nuxt applications, this will be at localhost. +2. Click the "Throw Sample Error" button, which triggers an error and starts a performance trace on the client side. + +To test the server side as well, refer to the "Verify" section in the [Manual setup guide](/platforms/javascript/guides/nuxt/manual-setup__v10.x/). + + + +To test Sentry, you can run your Nuxt application in either production or development mode. +We **recommend testing in production mode** as it most closely resembles your deployed application's environment. + + + By default, the SDK will add the server config as `sentry.server.config.mjs` + to the build. To find the exact path to this file, enable `debug` mode in your + Sentry configuration within `nuxt.config.ts`. Sentry will then print the exact + path during the build process. + + +### Run in Production Mode (Recommended) + + + + + +After building with `nuxi build`, run your project and make sure to load Sentry on the server side by explicitly adding it via `--import` (read more about this flag in [Installation Methods](/platforms/javascript/guides/nuxt/install__v10.x/)). + + + + +``` +# Start your app after building your project with `nuxi build` +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +``` + + + + + +### Run in Development Mode + + + + + +The server config file is generated in the `.nuxt` directory the first time you run `nuxt dev`. If you delete your `.nuxt` directory, you'll need to run `nuxt dev` once without the `NODE_OPTIONS` variable to regenerate it. + +If you only want to use Sentry on the client-side or only need basic error monitoring on the server side, you can omit the `--import` flag when running your application. + + + + +``` +# Run the dev server with the --import flag after running `nuxt dev` once (without the flag) +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev +``` + + + + + +If you used the Nuxt installation wizard, after building and running your project: + +1. Open the example page `/sentry-example-page` in your browser. For most Nuxt applications, this will be at localhost. +2. Click the "Throw sample error" button. This triggers two errors: + - a frontend error + - an error within the API route + +Sentry captures both of these errors for you. Additionally, the button click starts a performance trace to measure the time it takes for the API request to complete. + + + +### 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 integrated Sentry into your Nuxt application and should already be sending error and performance data to your Sentry project. + +Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/javascript/guides/nuxt/usage/) +- Continue to [customize your configuration](/platforms/javascript/guides/nuxt/configuration/) +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts +- Learn how to [track your Vue components or your Pinia store](/platforms/javascript/guides/nuxt/features/) +- Learn how to [add support for different Nitro deployment presets](/platforms/javascript/guides/nuxt/features/nitro-deployment-presets/) (like Cloudflare) + + + +- If you encountered issues with our installation wizard, try [setting up Sentry manually](/platforms/javascript/guides/nuxt/manual-setup__v10.x/) +- [Get support](https://www.sentry.help/en/) + + + + diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx similarity index 95% rename from docs/platforms/javascript/guides/nuxt/install/cli-import.mdx rename to docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx index c36bd401a2362..12673c5f5e8d8 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import__v10.x.mdx @@ -18,7 +18,7 @@ This will register Sentry's [loader hook](https://nodejs.org/api/module.html#cus - At this time, it isn't possible to properly configure `--import` in **Vercel**. If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side. -Check out the guide for using limited server tracing instead. +Check out the guide for using [limited server tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) instead. ## Initializing Sentry with `--import` diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx similarity index 90% rename from docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx rename to docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx index 8a09ed9890077..935a720fb314c 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x.mdx @@ -9,7 +9,7 @@ description: "Learn about how the Nuxt SDK leverages dynamic input() in the buil This installation method doesn't work with more recent versions of Nuxt/Nitro. - We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + We recommend reading the guide for installing the SDK with the [CLI flag `--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) or [limited server tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. @@ -48,7 +48,7 @@ As a temporary workaround, you can add the following overrides in your applicati } ``` -You can also check out the guide for installing the SDK with the CLI flag `--import` or limited-server-tracing. +You can also check out the guide for installing the SDK with the [CLI flag `--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) or [limited-server-tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/). ## Initializing Sentry with Dynamic `import()` diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx index b9e212e5ae87d..298c08d02db09 100644 --- a/docs/platforms/javascript/guides/nuxt/install/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -1,12 +1,98 @@ --- -title: Installation Methods +title: Server-Side Installation sidebar_order: 1.5 -description: "Review our alternate installation methods." +description: "Learn how the Nuxt SDK initializes Sentry on the server side, and how to upgrade to version 11." --- -Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). -Those customization hooks need to be registered before the rest of the application. + + This page applies to SDK version `11.0.0` and above. Version 10 and earlier + need the Node `--import` flag. For those versions, see the [installation + methods for version 10](/platforms/javascript/guides/nuxt/install__v10.x/). + -To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: +## How the SDK Initializes on the Server - +The SDK bundles your `sentry.server.config.ts` file into the Nitro server build. A Nitro plugin that the SDK generates imports this file, so `Sentry.init()` runs when the server starts. + +The SDK adds its instrumentation at build time. Because of this, Sentry doesn't have to load before the rest of your application. You start your application as usual, in production and in development mode, and on hosts where you can't set Node CLI flags, such as Vercel or Netlify. + +To confirm that the SDK bundled your server config, enable `debug` in the `sentry` options of your `nuxt.config.ts`. The SDK then prints a message during the build. + +### Development Mode + +In `nuxt dev`, spans from some libraries can be missing. Errors and request traces always work, and production builds are not affected. + +In a production build, Sentry prepares your libraries for tracing while Nuxt builds your app. +The dev server has no build step, so Sentry can only prepare a library that loads after Sentry starts. +Nuxt loads most libraries before that, for example your database client. + +Some libraries send tracing data on their own through [tracing channels](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). +Sentry always picks up this data, also in development mode. +This includes recent versions of `ioredis`, `redis`, `mysql2`, and `mongoose`. + +To see all spans, test with a production build: run `nuxi build`, then start your app. + +### Prerendering + +The SDK doesn't initialize Sentry while Nitro prerenders your pages at build time. As a result, builds don't send events to Sentry, and prerendered HTML doesn't contain trace meta tags. + +### Cloudflare + +With a Cloudflare Nitro preset, the SDK doesn't use `sentry.server.config.ts`. Set up the SDK with the [Cloudflare Nitro plugin](/platforms/javascript/guides/cloudflare/frameworks/nuxt/) instead. + +## Upgrade to SDK Version 11 + +### Remove the `--import` Flag + +Remove the `--import` flag from the command that starts your production build: + +```bash +# Before +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs + +# After +node .output/server/index.mjs +``` + +Do the same in development mode: + +```bash +# Before +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +nuxt dev +``` + +Also remove the flag from the `NODE_OPTIONS` environment variable of your hosting provider, if you set it there. + +Existing start commands continue to work. The SDK still writes a file to `.output/server/sentry.server.config.mjs`, but this file only prints a reminder to remove the flag. + +If you preload your own file that calls `Sentry.init()`, that call initializes the SDK. The SDK then skips the bundled initialization and prints a notice. + +### Deprecated Options + +Because a preload is no longer necessary, the following `sentry` module options are deprecated. They continue to work in version 11 and will be removed in the next major version. + +| Option | Replacement | +| ------------------------------------------------------- | ------------------------------------------- | +| `autoInjectServerSentry: "top-level-import"` | Remove the option. The default replaces it. | +| `autoInjectServerSentry: "experimental_dynamic-import"` | Remove the option. The default replaces it. | +| `experimental_entrypointWrappedFunctions` | Remove the option. It has no replacement. | + +If you set `autoInjectServerSentry`, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. Remove the option to use the bundled initialization: + +```typescript {filename:nuxt.config.ts} +// Before +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + sentry: { + autoInjectServerSentry: "top-level-import", + }, +}); + +// After +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], +}); +``` diff --git a/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx new file mode 100644 index 0000000000000..8d30b07ff5253 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/index__v10.x.mdx @@ -0,0 +1,14 @@ +--- +title: Installation Methods +sidebar_order: 1.5 +description: "Review our alternate installation methods." +--- + +Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). +Those customization hooks need to be registered before the rest of the application. + +To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: + +- [`--import` CLI flag (default)](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) +- [Limited Server Tracing](/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x/) +- [Dynamic Import (experimental)](/platforms/javascript/guides/nuxt/install/dynamic-import__v10.x/) diff --git a/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx similarity index 91% rename from docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx rename to docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx index 97665847a8761..7a0f2a0691a33 100644 --- a/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing__v10.x.mdx @@ -7,7 +7,7 @@ description: "Learn how to set up the Nuxt SDK with limited server tracing by ad ## Understanding Limited Server Tracing Sentry needs to be initialized before the rest of the application runs. -If the default way of adding an `--import` CLI flag doesn't work for you, +If the default way of adding an [`--import` CLI flag](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) doesn't work for you, enable the SDK to add a top-level `import`. The automatically added top-level `import` will then import the Sentry server-side config at the top of the Nuxt server entry file. diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx new file mode 100644 index 0000000000000..29eddc1e790d7 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/manual-setup__v10.x.mdx @@ -0,0 +1,525 @@ +--- +title: Manual Setup +sidebar_order: 1 +description: "Learn how to manually set up Sentry in your Nuxt app and capture your first errors." +--- + + + Looking for automatic setup with `sentry init` or the Nuxt wizard? Follow the + [Nuxt quickstart](/platforms/javascript/guides/nuxt__v10.x/) instead. + Continue with this guide to set up Sentry manually. + + +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- Nuxt version `3.7.0` or above (`3.14.0`+ recommended) + + + Add the following overrides: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" + } +} +``` + + + + + +## Install + +Choose the features you want to configure, and this guide will show you how: + + + + + + + +### Install the Sentry SDK + + + + + +Run the command for your preferred package manager to add the Sentry SDK to your application: + + + + +```bash {tabTitle:npm} +npm install @sentry/nuxt --save +``` + +```bash {tabTitle:yarn} +yarn add @sentry/nuxt +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/nuxt +``` + + + + + +## Configure + +### Apply Instrumentation to Your App + + + + + +Add the Sentry Nuxt module to your `nuxt.config.ts` file: + + + + +```javascript {filename:nuxt.config.ts} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], +}); +``` + + + + + +### Configure Client-Side Sentry + + + + + +Add a `sentry.client.config.ts` file to the root of your project (this is probably the same level as the `package.json`). In this file, import and initialize Sentry, specifying any SDK options for the client: + + + + +```javascript {filename:sentry.client.config.ts} +import * as Sentry from "@sentry/nuxt"; + +Sentry.init({ + // If set up, you can use the Nuxt runtime config here + // dsn: useRuntimeConfig().public.sentry.dsn + // modify depending on your custom runtime config + dsn: "___PUBLIC_DSN___", + + // ___PRODUCT_OPTION_START___ session-replay + + // Replay may only be enabled for the client-side + integrations: [ + Sentry.replayIntegration(), + // ___PRODUCT_OPTION_START___ user-feedback + Sentry.feedbackIntegration({ + // Additional SDK configuration goes in here, for example: + colorScheme: "system", + }), + // ___PRODUCT_OPTION_END___ user-feedback + ], + // ___PRODUCT_OPTION_END___ session-replay + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + // ___PRODUCT_OPTION_START___ session-replay + + // Capture Replay for 10% of all sessions, + // plus for 100% of sessions with an error + // Learn more at + // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ session-replay +}); +``` + + + + + + + +We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable and configure it via the Nuxt runtime config. + +This allows you to access the DSN using `useRuntimeConfig().public.sentry.dsn`. + + + + +```javascript {filename:nuxt.config.ts} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + runtimeConfig: { + public: { + sentry: { + dsn: process.env.NUXT_PUBLIC_SENTRY_DSN, // Use a public environment variable for the DSN + }, + }, + }, +}); +``` + + + + + +### Configure Server-Side Sentry + + + + + +Add a `sentry.server.config.ts` file to the root of your project and initialize Sentry in it. + +We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable. + + + + +```javascript {filename:sentry.server.config.ts} +import * as Sentry from "@sentry/nuxt"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance +}); +``` + + + + + + + + + + +Since Sentry on the server side needs to be loaded before `useRuntimeConfig()` is fully available, environment variables are only accessible via `process.env`. To make sure your environment variables are available, use one of these methods: + + + + +Load environment variables from your `.env` file when starting the server: + +```bash {tabTitle: node} +node --env-file=.env .output/server/index.mjs +``` + +or use the `dotenv` package: + +```javascript {tabTitle: Server Config} {filename:sentry.server.config.ts} {1,3} +import dotenv from "dotenv"; + +dotenv.config(); + +// ... rest of the file +``` + + + + + + + + + + +**Sentry's server-side monitoring doesn't work in development mode**. To enable it, you first need to build your application and then load the Sentry server-side config using the `--import` flag when running your application. + +Check out the [`--import` CLI flag](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/) docs for setup instructions. + + + + +``` +# Start your app after building your project with `nuxi build` +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +``` + + + + + + +### Add Readable Stack Traces With Source Maps (Optional) + + + + + +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the `sentry` options inside your configuration file: + +These `sentry` options only affect the **build time** of the SDK. + + + + +```javascript {filename:nuxt.config.ts} {3-10} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + sentry: { + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }, +}); +``` + + + + + + + +To keep your auth token secure, always store it in an environment variable instead of directly in your files: + + + + + + +```bash {filename:.env} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + + + + + +#### Enable Client-Side Source Maps + + + + + +While Nuxt generates source maps on the server side by default, you need to explicitly enable client-side source maps in your Nuxt configuration. + +The `hidden` option enables source map generation while preventing source map reference comments that would normally appear at the end of each generated file in the build output. + + + + +```javascript {filename:nuxt.config.ts} {2} +export default defineNuxtConfig({ + sourcemap: { client: "hidden" }, +}); +``` + + + + + +### Avoid Ad Blockers With Tunneling (Optional) + + + +### Control the Data You Send to Sentry (Optional) + + + +## Verify Your Setup + +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. + +### Issues + + + + + +To verify that Sentry captures errors and creates issues in your Sentry project, create a test page with a button. + + + + + + +```html {tabTitle:Vue} {filename:pages/example-error.vue} + + + +``` + + + + + + +### Tracing + + + + + +To test tracing, create a test API route `server/api/sentry-example.get.ts`: + + + + +```js {tabTitle:Nitro} {filename:server/api/sentry-example.get.ts} +export default defineEventHandler((event) => { + throw new Error("Sentry Example API Route Error"); +}); +``` + + + + + + + +Then update the test page by including a new button that executes a function to fetch your API route: + + + + +```html {tabTitle:Vue} {filename:pages/example-error.vue} + + + +``` + + + + + + + + + + + + + + + + + Once you have your test code in place, open the page in a browser and click + the button to trigger an error. + + + + +Once you have your test code in place, you need to build your project since Sentry's **server-side monitoring doesn't work in development** mode. + + +Then start your app and make sure to load Sentry on the server side by explicitly adding the Sentry server config in the build output via [`--import`](/platforms/javascript/guides/nuxt/install/cli-import__v10.x/). + + +After running your project, open your test page in a browser and click the buttons. + + + +### 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 integrated Sentry into your Nuxt application and should already be sending data to your Sentry project. + +Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: + +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup +- Learn how to [manually capture errors](/platforms/javascript/guides/nuxt/usage/) +- Continue to [customize your configuration](/platforms/javascript/guides/nuxt/configuration/) +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts +- Learn how to [track your Vue components or your Pinia store](/platforms/javascript/guides/nuxt/features/) +- Learn how to [add support for different Nitro deployment presets](/platforms/javascript/guides/nuxt/features/nitro-deployment-presets/) (like Cloudflare) + + + +- If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nuxt__v10.x/) +- Find various support topics in troubleshooting +- Review alternative [installation methods](/platforms/javascript/guides/nuxt/install__v10.x/) +- [Get support](https://www.sentry.help/en/) + + + + + diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index e9e9c5775851a..42544d7303ed5 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -1,6 +1,6 @@ --- title: React Router Framework -description: Learn how to set up and configure Sentry in your React Router application (v7+) using the installation wizard, capture your first errors, and view them in Sentry. +description: Learn how to set up and configure Sentry in your React Router application (v7.15+) using the installation wizard, capture your first errors, and view them in Sentry. sdk: sentry.javascript.react-router categories: - browser @@ -12,13 +12,6 @@ categories: platformName="React Router" /> - - This SDK is currently in **beta**. Beta features are still in progress and may - have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if - you have any feedback or concerns. - - If you're using React Router in data or declarative mode, follow the instructions in our [React guide for v7](/platforms/javascript/guides/react/features/react-router/v7) or [v8](/platforms/javascript/guides/react/features/react-router/v8). diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 1d962a45d25b2..06e808cb7b486 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -1,16 +1,9 @@ --- title: "Manual Setup" sidebar_order: 1 -description: "Learn how to manually set up Sentry in your React Router app (v7+) and capture your first errors." +description: "Learn how to manually set up Sentry in your React Router app (v7.15+) and capture your first errors." --- - - This SDK is currently in **beta**. Beta features are still in progress and may - have bugs. Please reach out on - [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if - you have any feedback or concerns. - - @@ -190,7 +183,7 @@ Sentry's OpenTelemetry-based auto-instrumentation (loaded through `instrument.se - **Node 20:** Version \<20.19 - **Node 22:** Version \<22.12 -This restriction **doesn't** affect tracing for loaders, actions, middleware, and request handlers. Those are instrumented through React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (the `instrumentations` export shown below, React Router 7.15+), which works on all Node versions. +This restriction **doesn't** affect tracing for loaders, actions, middleware, and request handlers. Those are instrumented through React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (the `instrumentations` export shown below), which works on all Node versions. On unsupported Node versions, you'll only lose auto-instrumentation for lower-level operations such as outgoing HTTP requests and database queries. @@ -244,7 +237,7 @@ Sentry.init({ Next, replace the default `handleRequest` and `handleError` functions in your `entry.server.tsx` file with Sentry's wrapped versions, and export `instrumentations` to enable automatic tracing. -Exporting `instrumentations` uses React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) (React Router 7.15+) to automatically create spans for all loaders, actions, middleware, and request handlers — no need to wrap them individually. +Exporting `instrumentations` uses React Router's [instrumentation API](https://reactrouter.com/how-to/instrumentation) to automatically create spans for all loaders, actions, middleware, and request handlers — no need to wrap them individually. @@ -269,7 +262,7 @@ Exporting `instrumentations` uses React Router's [instrumentation API](https://r +}); +// Automatically instruments all server loaders, actions, middleware, -+// and request handlers. Requires React Router 7.15+. ++// and request handlers. +export const instrumentations = [Sentry.createSentryServerInstrumentation()]; // ... rest of your server entry @@ -420,7 +413,7 @@ If you're deploying to platforms where you can't set the `NODE_OPTIONS` flag, im ```tsx {diff} {filename: entry.server.tsx} -+import './instrument.server'; ++import '../instrument.server'; import * as Sentry from '@sentry/react-router'; import { createReadableStreamFromReadable } from '@react-router/node'; import { renderToPipeableStream } from 'react-dom/server'; @@ -452,7 +445,7 @@ First, update `vite.config.ts` to include the `sentryReactRouter` plugin, making ```typescript {filename: vite.config.ts} {diff} import { reactRouter } from '@react-router/dev/vite'; -import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router'; +import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router/vite'; import { defineConfig } from 'vite'; const sentryConfig: SentryReactRouterBuildOptions = { @@ -506,14 +499,14 @@ Next, include the `sentryOnBuildEnd` hook in `react-router.config.ts`: ```typescript {filename: react-router.config.ts} {diff} import type { Config } from "@react-router/dev/config"; -import { sentryOnBuildEnd } from "@sentry/react-router"; +import { sentryOnBuildEnd } from "@sentry/react-router/vite"; export default { ssr: true, buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => { // ... // Call this at the end of the hook - +(await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest })); ++ await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest }); }, } satisfies Config; ``` diff --git a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx index feb69bae2b524..ecdb08f2c42f2 100644 --- a/docs/platforms/javascript/guides/solidstart/features/middleware.mdx +++ b/docs/platforms/javascript/guides/solidstart/features/middleware.mdx @@ -5,11 +5,11 @@ description: "Learn about Sentry's middleware for better instrumentation." The Sentry middleware enhances the data collected by Sentry on the server side by enabling distributed tracing between the client and server. -Add the Sentry middleware to your `middleware.ts` file. If you don't have a `middleware.ts` file yet, create one: +Add the Sentry middleware to your `src/middleware.ts` file. If you don't have a `src/middleware.ts` file yet, create one: -```typescript {filename:middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +```typescript {filename:src/middleware.ts} +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -19,13 +19,28 @@ export default createMiddleware({ }); ``` -And specify `middleware.ts` in `app.config.ts`: +Then register `middleware.ts` in your build config. On SolidStart 2, pass it to the `solidStart` plugin in `vite.config.ts`. On SolidStart 1, specify it in `app.config.ts`: -```typescript {filename:app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { solidStart } from "@solidjs/start/config"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart({ + // ... + middleware: "./src/middleware.ts", + }), + // ... + ], +}); +``` + +```typescript {tabTitle:SolidStart 1} {filename:app.config.ts} +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index aad5f768ad29c..d9c4a20da6f77 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -149,12 +149,32 @@ mount(() => , document.getElementById("app")); -Create a file named `instrument.server.ts` in your `src` folder. In this file, initialize and import Sentry for your server: +Initialize Sentry on the server. On SolidStart 2, do this in a Nitro startup plugin, which runs once when the server starts. On SolidStart 1, create an `instrument.server.ts` file in your `src` folder. -```javascript {filename:src/instrument.server.ts} +```typescript {tabTitle:SolidStart 2} {filename:server/plugins/sentry.ts} {mdExpandTabs} +import * as Sentry from "@sentry/solidstart"; +import { definePlugin } from "nitro"; + +export default definePlugin(() => { + Sentry.init({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + }); +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:src/instrument.server.ts} import * as Sentry from "@sentry/solidstart"; Sentry.init({ @@ -205,13 +225,29 @@ export default createMiddleware({ -Wrap your SolidStart config in `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. -Then, specify the middleware that you've just created: +Add the Sentry plugin to your build config and register the middleware you just created. On SolidStart 2, add `sentrySolidStart` to `vite.config.ts`. On SolidStart 1, wrap your `app.config.ts` with `withSentry` so that the instrumentation file gets included in your build output. -```javascript {filename:app.config.ts} {5-15} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart({ + middleware: "./src/middleware.ts", + }), + sentrySolidStart(), + nitro(), + ], +}); +``` + +```javascript {tabTitle:SolidStart 1} {filename:app.config.ts} {5-15} import { withSentry } from "@sentry/solidstart"; import { defineConfig } from "@solidjs/start/config"; @@ -274,24 +310,35 @@ export default function App() { -Instrumentation needs to happen as early as possible to make sure Sentry works as intended. To do this, add an `--import` flag to the `NODE_OPTIONS` environment variable when you run your application and set it to import the instrumentation file created by the build output: `.output/server/instrument.server.mjs`. +On SolidStart 2, the Vite plugin instruments your dependencies at build time, so the server needs no preload flag. Build with `vite build` and start the output directly. + +On SolidStart 1, instrumentation has to happen as early as possible, so add an `--import` flag pointing at the instrumentation file that the build output creates: `.output/server/instrument.server.mjs`. -Run your build command to generate the `instrument.server.mjs` file before running your app. Depending on your build preset, the location of the file can differ. To find out where the file is located, monitor the build log output for: +On SolidStart 1, run your build command to generate the `instrument.server.mjs` file before running your app. Depending on your build preset, the location of the file can differ. To find out where the file is located, monitor the build log output for: `[Sentry SolidStart withSentry] Successfully created /my/project/path/.output/server/instrument.server.mjs.` -If you're not able to use the `--import` flag, check the alternative installation methods. +If you're not able to use the `--import` flag on SolidStart 1, check the alternative installation methods. For example, update your scripts in `package.json`: -```json {filename:package.json} +```json {tabTitle:SolidStart 2} {filename:package.json} {mdExpandTabs} +{ + "scripts": { + "build": "vite build", + "start": "node .output/server/index.mjs" + } +} +``` + +```json {tabTitle:SolidStart 1} {filename:package.json} { "scripts": { "start:vinxi": "NODE_OPTIONS='--import ./.output/server/instrument.server.mjs ' vinxi start", @@ -327,12 +374,32 @@ To automatically report exceptions from inside a component tree to Sentry, wrap -To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your SolidStart configuration: +To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug to the Sentry plugin in your build config: -```TypeScript {filename:app.config.ts} +```typescript {tabTitle:SolidStart 2} {filename:vite.config.ts} {mdExpandTabs} +import { sentrySolidStart } from "@sentry/solidstart/vite"; +import { solidStart } from "@solidjs/start/config"; +import { nitro } from "nitro/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + solidStart(), + sentrySolidStart({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + // store your auth token in an environment variable + authToken: process.env.SENTRY_AUTH_TOKEN, + }), + nitro(), + ], +}); +``` + +```TypeScript {tabTitle:SolidStart 1} {filename:app.config.ts} import { withSentry } from '@sentry/solidstart'; import { defineConfig } from '@solidjs/start/config'; diff --git a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx index ea23fddb76902..1a179420847cb 100644 --- a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx @@ -4,6 +4,12 @@ sidebar_order: 1 description: "Learn how to use the node --import CLI flag." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `--import` CLI Flag The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a specified module at startup. @@ -54,11 +60,13 @@ Consult your hosting provider's documentation for specific implementation detail Most deployment platforms support this through two primary methods: #### Option 1: Direct CLI Flag + ```bash node --import ./.output/server/instrument.server.mjs your-server-entry.mjs ``` #### Option 2: Environment Variable + ```bash NODE_OPTIONS='--import ./.output/server/instrument.server.mjs' ``` diff --git a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx index a4bd655734da4..9b5d5a79302d6 100644 --- a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx @@ -4,12 +4,19 @@ sidebar_order: 3 description: "Learn about how the SolidStart SDK leverages dynamic input() in the build output." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding the `import()` expression This setting is experimental as it is not guaranteed to work with every setup and the underlying functionality could change. - We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing +We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. @@ -31,15 +38,17 @@ You can also check out the guide for installing the SDK with the + +These installation methods apply to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so the server needs no preload. + + + +SolidStart 1 uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). Those customization hooks need to be registered before the rest of the application. To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: diff --git a/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx index 8e21b35392ade..0a8f1ee3ca0d0 100644 --- a/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx +++ b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx @@ -4,6 +4,12 @@ sidebar_order: 2 description: "Learn how to set up the SolidStart SDK with limited server tracing by adding a top-level import to the build output." --- + + +This installation method applies to SolidStart 1. On SolidStart 2, the Sentry Vite plugin instruments your dependencies at build time, so no preload is needed. See the SolidStart guide. + + + ## Understanding Limited Server Tracing Sentry needs to be initialized before the rest of the application runs. diff --git a/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx b/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx index ad6089b21b8ff..8a4a553643366 100644 --- a/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx +++ b/docs/platforms/javascript/guides/sveltekit/configuration/build/index.mdx @@ -85,7 +85,7 @@ Set `autoInstrument` to `false` to disable auto-instrumentation of any `load` fu ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from '@sveltejs/kit/vite'; -import { sentrySvelteKit } from '@sentry/sveltekit'; +import { sentrySvelteKit } from '@sentry/sveltekit/vite'; export default { plugins: [ @@ -108,7 +108,7 @@ Set to `false` to disable auto-instrumentation of `load` functions inside `+page ```javascript {filename:vite.config.(js|ts)} {7-10} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -131,7 +131,7 @@ Set to `false` to disable auto-instrumentation of server-only `load` functions i ```javascript {filename:vite.config.(js|ts)} {7-10} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ diff --git a/docs/platforms/javascript/guides/wasm/index.mdx b/docs/platforms/javascript/guides/wasm/index.mdx index 7bcc43e5e01f6..594bcf1f9d56e 100644 --- a/docs/platforms/javascript/guides/wasm/index.mdx +++ b/docs/platforms/javascript/guides/wasm/index.mdx @@ -74,10 +74,6 @@ import { wasmIntegration } from "@sentry/wasm"; Sentry.init({ dsn: "___PUBLIC_DSN___", - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/javascript/guides/wasm/configuration/options/#sendDefaultPii - sendDefaultPii: true, - integrations: [ // ___PRODUCT_OPTION_START___ performance Sentry.browserTracingIntegration(), diff --git a/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx b/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx index e76a7f3757d37..0443a344e3a66 100644 --- a/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx +++ b/docs/platforms/react-native/common/enriching-events/identify-user/index.mdx @@ -22,7 +22,7 @@ An alternative, or addition, to the username. Sentry is aware of email addresses ### `ip_address` The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. This requires you to set the `include.ip` option to `true` in the [`RequestData`](/platforms/javascript/guides/connect/configuration/integrations/requestdata/) integration. +Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. This requires you to set the `include.ip` option to `true` in the [`RequestData`](/platforms/javascript/guides/node/configuration/integrations/requestdata/) integration. If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. diff --git a/docs/platforms/react-native/common/integrations/langgraph.mdx b/docs/platforms/react-native/common/integrations/langgraph.mdx index 7cfd989020898..cfb5466715d82 100644 --- a/docs/platforms/react-native/common/integrations/langgraph.mdx +++ b/docs/platforms/react-native/common/integrations/langgraph.mdx @@ -3,9 +3,14 @@ title: LangGraph description: "Manually instrument LangGraph in React Native to capture spans for agent compilation and invocation." --- -_Import name: `Sentry.instrumentLangGraph`_ +_Import names: `Sentry.instrumentStateGraph`, `Sentry.instrumentCreateReactAgent`_ -The `instrumentLangGraph` helper adds instrumentation for [`@langchain/langgraph`](https://www.npmjs.com/package/@langchain/langgraph) by wrapping a `StateGraph` before compilation and recording agent interactions with configurable input/output capture. The OpenTelemetry-based automatic integration available for Node.js does not work in React Native, so calling `instrumentLangGraph` on the graph **before** `.compile()` is the only supported path. +The OpenTelemetry-based automatic integration available for Node.js does not work in React Native, so manual instrumentation is the only supported path. Two helpers are available, depending on how you build your agent: + +- **`instrumentStateGraph`** — for graphs you build yourself with `StateGraph`. Call it on the graph **before** calling `.compile()`. +- **`instrumentCreateReactAgent`** — for LangGraph's prebuilt `createReactAgent`. Wrap the factory, then use the wrapped version exactly like `createReactAgent`. This also captures the model and wraps tools, so you get `execute_tool` spans as well. + +Both accept the same input/output recording options. ## Usage @@ -35,7 +40,7 @@ const agent = new StateGraph(MessagesAnnotation) .addEdge("agent", END); // Instrument the graph BEFORE compiling -Sentry.instrumentLangGraph(agent, { +Sentry.instrumentStateGraph(agent, { recordInputs: true, recordOutputs: true, }); @@ -50,6 +55,18 @@ const result = await graph.invoke({ }); ``` +Or, instrument LangGraph's prebuilt `createReactAgent`: + +```javascript +import * as Sentry from "@sentry/react-native"; +import { createReactAgent } from "@langchain/langgraph/prebuilt"; + +// Instrument createReactAgent, then use the wrapped version in its place +const instrumentedCreateReactAgent = Sentry.instrumentCreateReactAgent(createReactAgent); + +const agent = instrumentedCreateReactAgent({ llm, tools }); +``` + Make sure tracing is enabled for the spans produced by this integration to be captured. ## Configuration diff --git a/docs/pricing/quotas/manage-event-stream-guide.mdx b/docs/pricing/quotas/manage-event-stream-guide.mdx index a7068fe3d4025..52622bdce00b8 100644 --- a/docs/pricing/quotas/manage-event-stream-guide.mdx +++ b/docs/pricing/quotas/manage-event-stream-guide.mdx @@ -210,9 +210,9 @@ The Sentry SDKs have several configuration options that can be used to filter un ### JavaScript -The JavaScript SDK includes multiple integrations: functional plugins that you can configure, enable, or disable. Learn more in [JavaScript SDK Integrations](/platforms/javascript/configuration/integrations/). Several integrations allow you to configure the types of events you want Sentry to monitor; two of them, InboundFilters and GlobalHandlers are explained below: +The JavaScript SDK includes multiple integrations: functional plugins that you can configure, enable, or disable. Learn more in [JavaScript SDK Integrations](/platforms/javascript/configuration/integrations/). Several integrations allow you to configure the types of events you want Sentry to monitor; two of them, EventFilters and GlobalHandlers are explained below: -#### InboundFilters +#### EventFilters The integration is enabled by default and adds the following configuration options to the SDK: diff --git a/docs/product/agents/naming.mdx b/docs/product/agents/naming.mdx index 22cb2a290e958..45a6f05a83fb3 100644 --- a/docs/product/agents/naming.mdx +++ b/docs/product/agents/naming.mdx @@ -149,7 +149,7 @@ const agent = new ToolLoopAgent({ Vercel AI SDK integration docs @@ -180,7 +180,7 @@ const agent = createReactAgent({ LangGraph integration docs @@ -201,7 +201,7 @@ const agent = createAgent({ LangChain integration docs diff --git a/docs/product/agents/privacy.mdx b/docs/product/agents/privacy.mdx index 9d57c79356bba..f3b83d4228d3f 100644 --- a/docs/product/agents/privacy.mdx +++ b/docs/product/agents/privacy.mdx @@ -21,7 +21,7 @@ By default, Sentry agent integrations respect your [SDK's PII settings](/platfor - `sendDefaultPii: false` - Only metadata like model names, token counts, tool names, and execution times are collected - `sendDefaultPii: true` - Full inputs, outputs, prompts, and responses from AI models and tools are captured. -You can override this by configuring it on a function call level. For more details see [Configuration](/platforms/javascript/guides/nextjs/agent-tracing/vercelai/#configuration). +You can override this per integration with `recordInputs` and `recordOutputs`. For more details see [Options](/platforms/javascript/guides/nextjs/configuration/integrations/vercelai/#options). ## Server side PII Scrubbing diff --git a/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx b/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx index a31ad37e5ed37..242fec95080cf 100644 --- a/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx +++ b/docs/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.mdx @@ -9,7 +9,11 @@ og_image: /og-images/product-insights-frontend-web-vitals-web-vitals-concepts.pn [Web Vitals](https://web.dev/vitals/) are a set of metrics defined by Google to measure render time, response time, and layout shift. Each data point provides insights about the overall [performance](/product/dashboards/sentry-dashboards/) of your application. -The in-browser Sentry SDKs collect web vitals information (where supported) and adds that information to frontend [transactions](/product/dashboards/sentry-dashboards/transaction-summary/). These web vitals are then summarized in the [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/) to give you a quick overview of how each page is performing for your users. +Sentry's browser SDKs collect supported Web Vitals and associate them with your application's traces. The [Web Vitals dashboard](/product/dashboards/sentry-dashboards/frontend/web-vitals/) summarizes these metrics to show how each page performs for your users. + +In JavaScript SDK version 11's default stream mode, LCP, CLS, and INP are sent as Web Vital spans. Earlier SDK versions and static mode can report vitals as measurements on pageload spans. In version 11, INP uses a Web Vital span in both modes. + +To configure collection, see the [WebVitals integration](/platforms/javascript/configuration/integrations/webvitals/). If your custom dashboards or alerts use INP measurements, see the [v11 migration guide](/platforms/javascript/migration/v10-to-v11/). ![Visualization of Web Vitals](../../img/diagram-transaction-vitals.png) @@ -24,7 +28,7 @@ Google considers Core Web Vitals to be the most important metrics for measuring ### Interaction to Next Paint (INP) -On March 12, 2024, Interaction to Next Paint (INP) replaced First Input Delay (FID) as a Core Web Vital. Prior to this, INP was an experimental metric that Sentry did not collect. To begin collecting INP measurements, make sure your JavaScript SDK version is [7.104.0](https://github.com/getsentry/sentry-javascript/releases/tag/7.104.0) or higher and that the option [`enableInp`](/platforms/javascript/tracing/instrumentation/automatic-instrumentation/#enableinp) is on (starting with version `8.0.0`, `enableInp` is enabled by default). +INP replaced First Input Delay (FID) as a Core Web Vital on March 12, 2024. Sentry supports INP starting with JavaScript SDK version 7.104.0. It is enabled by default with BrowserTracing in version 8 and later. In version 11, configure collection through the [WebVitals integration](/platforms/javascript/configuration/integrations/webvitals/). The older `enableInp` option is deprecated. [Interaction to Next Paint (INP)](https://web.dev/articles/inp) measures the time from when a user interacts with a page (through a click, tap, or keyboard input) to when the next paint (rendering of content on the screen) occurs. INP aims to assess how quickly users see a response from the website after taking an action, which is crucial for providing a smooth and responsive user experience. diff --git a/docs/product/logs/getting-started/index.mdx b/docs/product/logs/getting-started/index.mdx index c1a6d6ab9795b..be078b92f6c2a 100644 --- a/docs/product/logs/getting-started/index.mdx +++ b/docs/product/logs/getting-started/index.mdx @@ -53,12 +53,6 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s url="/platforms/javascript/guides/cloudflare/logs/" skill="sentry-cloudflare-sdk" /> -- - -- - @@ -26,17 +57,21 @@ For supported AI libraries, Sentry provides manual instrumentation helpers that -Each integration page includes a manual-instrumentation example with options like `recordInputs` and `recordOutputs`. +Each integration page documents its options, like `recordInputs` and `recordOutputs`. @@ -113,9 +148,7 @@ This span represents a request to an LLM model or service that generates a respo const messages = [ { role: "user", parts: [{ type: "text", content: "Tell me a joke" }] }, ]; -const tools = [ - { name: "get_weather", description: "Get weather for a city" }, -]; +const tools = [{ name: "get_weather", description: "Get weather for a city" }]; await Sentry.startSpan( { @@ -367,7 +400,6 @@ When the model streams tokens, keep the span open until the stream finishes (inc Use `Sentry.startInactiveSpan` if the span outlives the function that starts the stream, and `Sentry.withActiveSpan` when work within the stream needs the model span as its parent. End the span when the stream completes or fails. See Streamed Spans for span lifecycle patterns. - Sentry derives [model cost](/product/agents/costs/) from the model name and token counts. You do not need to set `gen_ai.cost.*` attributes. Pass the raw provider model string unchanged so pricing can resolve. If your provider reports costs or you use custom pricing, see [Send Custom Costs](/product/agents/costs/#send-custom-costs). diff --git a/includes/docs-changelog.mdx b/includes/docs-changelog.mdx index b8d83c957349a..41db359c9e4cc 100644 --- a/includes/docs-changelog.mdx +++ b/includes/docs-changelog.mdx @@ -118,7 +118,7 @@ - [ESM (MJS)](/platforms/javascript/guides/node/install/esm/) - [Installation Methods](/platforms/javascript/install/) - [Late Initialization (ESM or CJS)](/platforms/javascript/guides/node/install/late-initialization/) -- [Lightweight Mode](/platforms/javascript/guides/node/install/lightweight/) +- [Lightweight Mode](/platforms/javascript/guides/node/configuration/integrations/opentelemetry/) - [Set Up MCP Monitoring](/platforms/javascript/guides/node/mcp-monitoring/) - [Configuration](/platforms/javascript/user-feedback/configuration/) - [Set Up User Feedback](/platforms/javascript/user-feedback/) diff --git a/includes/javascript-v11-agent-migration.mdx b/includes/javascript-v11-agent-migration.mdx new file mode 100644 index 0000000000000..c680f40487ba0 --- /dev/null +++ b/includes/javascript-v11-agent-migration.mdx @@ -0,0 +1,5 @@ + diff --git a/includes/mastra/captured-summary.mdx b/includes/mastra/captured-summary.mdx index 653845bed99ed..f04e0c2cf2e3f 100644 --- a/includes/mastra/captured-summary.mdx +++ b/includes/mastra/captured-summary.mdx @@ -1,3 +1,3 @@ With this setup, Sentry captures errors thrown by your agents and AI spans for every run (agent runs, model generations, tool calls, workflows, token usage, and latency) along with outgoing HTTP and `fetch` requests. Prompts and model outputs are recorded on your AI spans by default. -To review what's captured and turn recording of prompts and responses off, see [Privacy Controls](#privacy-controls) below. +To review what's captured and turn recording of prompts and responses off, see [Control the Data You Send to Sentry](#control-the-data-you-send-to-sentry-optional) below. diff --git a/includes/metrics/javascript-quick-start-verify-metrics-splitlayout.mdx b/includes/metrics/javascript-quick-start-verify-metrics-splitlayout.mdx index ee6011fa08dec..843027e8f6bcc 100644 --- a/includes/metrics/javascript-quick-start-verify-metrics-splitlayout.mdx +++ b/includes/metrics/javascript-quick-start-verify-metrics-splitlayout.mdx @@ -8,7 +8,7 @@ Send test metrics from your app to verify that metrics are arriving in Sentry: - + In a Node.js runtime, you can use the [NodeRuntimeMetrics](/platforms/javascript/guides/node/configuration/integrations/noderuntimemetrics/) integration to automatically collect Node.js runtime health metrics. diff --git a/includes/migration/javascript-v11/ai-non-inference-spans.mdx b/includes/migration/javascript-v11/ai-non-inference-spans.mdx new file mode 100644 index 0000000000000..79e90171a9840 --- /dev/null +++ b/includes/migration/javascript-v11/ai-non-inference-spans.mdx @@ -0,0 +1,14 @@ +--- +id: ai-non-inference-spans +title: "AI integrations no longer trace non-inference operations" +phase: verify +category: behavior +severity: behavior-change +frameworks: all +platformCategory: server +order: 96 +--- + +AI integrations now trace model invocations, tool calls, and agent invocations only. They no longer emit spans for Anthropic `messages.countTokens`, `models.retrieve`, or `models.get`, or LangGraph graph compilation with `gen_ai.create_agent`. + +Update dashboards and alerts that reference these spans. LangGraph's `gen_ai.invoke_agent` and `gen_ai.execute_tool` spans are unchanged. diff --git a/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx b/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx index 8da8a9aecd729..0545f0a4f3b2d 100644 --- a/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx +++ b/includes/migration/javascript-v11/browser-session-lifecycle-page.mdx @@ -17,3 +17,5 @@ Sentry.init({ integrations: [Sentry.browserSessionIntegration({ lifecycle: "route" })], }); ``` + +See BrowserSession for lifecycle configuration and session health details. diff --git a/includes/migration/javascript-v11/browser-session-unhandled.mdx b/includes/migration/javascript-v11/browser-session-unhandled.mdx index 1827622d318bb..5ff4021d42066 100644 --- a/includes/migration/javascript-v11/browser-session-unhandled.mdx +++ b/includes/migration/javascript-v11/browser-session-unhandled.mdx @@ -10,3 +10,5 @@ order: 20 --- Sessions affected by an uncaught error are recorded as `unhandled` instead of `crashed`. If you track crash-free session rates or have alerts built on them, expect the rate to shift. + +See BrowserSession for session health details. diff --git a/includes/migration/javascript-v11/browser-user-timing.mdx b/includes/migration/javascript-v11/browser-user-timing.mdx index 45106aad2700e..6897a55acc1b9 100644 --- a/includes/migration/javascript-v11/browser-user-timing.mdx +++ b/includes/migration/javascript-v11/browser-user-timing.mdx @@ -29,3 +29,5 @@ Sentry.init({ ], }); ``` + +See UserTiming for configuration and CDN loading instructions. diff --git a/includes/migration/javascript-v11/browser-web-vital-options.mdx b/includes/migration/javascript-v11/browser-web-vital-options.mdx index f7b759a6e913a..ac4f3693a8dfa 100644 --- a/includes/migration/javascript-v11/browser-web-vital-options.mdx +++ b/includes/migration/javascript-v11/browser-web-vital-options.mdx @@ -1,6 +1,6 @@ --- id: browser-web-vital-options -title: "Standalone CLS and LCP span options were removed" +title: "Web Vitals moved to a dedicated integration" phase: code-changes category: removed-api severity: action-required @@ -9,6 +9,14 @@ platformCategory: browser order: 220 --- -The `_experiments.enableStandalone*Spans` options were removed. CLS and LCP are no longer configurable, and `browserTracingIntegration` no longer accepts an `_experiments` object at all. +The `_experiments.enableStandalone*Spans` options were removed, and `browserTracingIntegration` no longer accepts an `_experiments` object. BrowserTracing automatically adds `webVitalsIntegration` to collect Web Vitals. CLS and LCP are recorded as measurements on the pageload span, or as dedicated spans in stream mode. + +Configure collection through `browserTracingIntegration({ webVitals: { ... } })`. The `enableInp` option is deprecated. Use `webVitals: { ignore: ["inp"] }` to disable INP, or include `"cls"` or `"lcp"` in `ignore` to skip those vitals. If you explicitly add `webVitalsIntegration()`, its options take precedence. + +Soft-navigation vitals are enabled by default in stream mode on supporting browsers. Set `webVitals: { softNavigations: false }` to keep one set of vitals for the page lifetime. Back/forward-cache vitals are also enabled by default in stream mode when BrowserTracing's `instrumentBfcacheRestore` is enabled. Set `webVitals: { bfcacheNavigations: false }` to disable collection for restores. See WebVitals for requirements. + +LCP and CLS spans no longer set `browser.web_vital.lcp.report_event` or `browser.web_vital.cls.report_event`, including when soft-navigation reporting is disabled. Finalization timing is unchanged. Remove filters on these attributes from searches and dashboards. + +Restore vitals carry `browser.navigation.type: bfcache`. Filter by that attribute to analyze restores separately from page loads, since near-instant restores can lower combined aggregates. diff --git a/includes/migration/javascript-v11/child-process-worker-split.mdx b/includes/migration/javascript-v11/child-process-worker-split.mdx index cf7909a5d14a2..33cd9ce101ee9 100644 --- a/includes/migration/javascript-v11/child-process-worker-split.mdx +++ b/includes/migration/javascript-v11/child-process-worker-split.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx b/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx index 3b2d1f1e09c1f..76545ea915bf1 100644 --- a/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx +++ b/includes/migration/javascript-v11/cloudflare-instrument-d1.mdx @@ -9,4 +9,4 @@ platformCategory: serverless order: 430 --- -`instrumentD1WithSentry` was removed. `withSentry()` instruments all D1 bindings on `env` automatically. +`instrumentD1WithSentry` was removed. `withSentry()` instruments all D1 bindings on `env` automatically. Remove the call and use the binding directly. For the list of bindings that the SDK instruments, see [Cloudflare Bindings](/platforms/javascript/guides/cloudflare/features/bindings/). diff --git a/includes/migration/javascript-v11/console-breadcrumbs.mdx b/includes/migration/javascript-v11/console-breadcrumbs.mdx index 00d8eb6ca3414..3e3001f39c65c 100644 --- a/includes/migration/javascript-v11/console-breadcrumbs.mdx +++ b/includes/migration/javascript-v11/console-breadcrumbs.mdx @@ -9,4 +9,15 @@ platformCategory: browser order: 205 --- -The `console` option of `breadcrumbsIntegration` was removed. Use `consoleIntegration` to capture console breadcrumbs. +The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now, which matches the server SDKs. + +To disable console breadcrumbs, filter out the `Console` integration: + +```js +Sentry.init({ + integrations: (integrations) => + integrations.filter((integration) => integration.name !== "Console"), +}); +``` + +If you set `defaultIntegrations: false`, add `Sentry.consoleIntegration()` to keep capturing them. diff --git a/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx b/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx new file mode 100644 index 0000000000000..e29a4cf67b4a1 --- /dev/null +++ b/includes/migration/javascript-v11/deno-console-breadcrumbs.mdx @@ -0,0 +1,23 @@ +--- +id: deno-console-breadcrumbs +title: "Deno console breadcrumbs moved to `consoleIntegration`" +phase: code-changes +category: removed-api +severity: action-required +frameworks: [deno] +platformCategory: server +order: 311 +--- + +The `console` option of `breadcrumbsIntegration` was removed. Console breadcrumbs come from the default `consoleIntegration` now, which matches the other server SDKs. + +To disable console breadcrumbs, filter out the `Console` integration: + +```js +Sentry.init({ + integrations: integrations => + integrations.filter(integration => integration.name !== "Console"), +}); +``` + +If you set `defaultIntegrations: false`, add `Sentry.consoleIntegration()` to keep capturing them. diff --git a/includes/migration/javascript-v11/express-error-handler.mdx b/includes/migration/javascript-v11/express-error-handler.mdx index e94fc957c1823..6e2e4e9e9a85c 100644 --- a/includes/migration/javascript-v11/express-error-handler.mdx +++ b/includes/migration/javascript-v11/express-error-handler.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/fastify-error-handler.mdx b/includes/migration/javascript-v11/fastify-error-handler.mdx index d40238427f165..d549797964117 100644 --- a/includes/migration/javascript-v11/fastify-error-handler.mdx +++ b/includes/migration/javascript-v11/fastify-error-handler.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/hono-integration-removed.mdx b/includes/migration/javascript-v11/hono-integration-removed.mdx index 977035bd6e5fc..a13418fd78ed9 100644 --- a/includes/migration/javascript-v11/hono-integration-removed.mdx +++ b/includes/migration/javascript-v11/hono-integration-removed.mdx @@ -11,7 +11,6 @@ frameworks: azure-functions, bun, cloudflare, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/http-integration-options.mdx b/includes/migration/javascript-v11/http-integration-options.mdx index 1e0c130dc6627..d7a59260e07d9 100644 --- a/includes/migration/javascript-v11/http-integration-options.mdx +++ b/includes/migration/javascript-v11/http-integration-options.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/inp-web-vital-span.mdx b/includes/migration/javascript-v11/inp-web-vital-span.mdx index 5e1eaaabe848e..b46f2b2b6d09c 100644 --- a/includes/migration/javascript-v11/inp-web-vital-span.mdx +++ b/includes/migration/javascript-v11/inp-web-vital-span.mdx @@ -9,4 +9,6 @@ platformCategory: browser order: 80 --- -INP is always sent as a web vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement (built-in dashboards do not need adjustments). +When collected, INP is always sent as a Web Vital span, carrying its value in the `browser.web_vital.inp.value` attribute instead of as a span measurement. Update custom dashboards and alerts that read it as a measurement. Built-in dashboards do not need adjustments. + +See WebVitals for collection options and the attributes sent with each vital. diff --git a/includes/migration/javascript-v11/interaction-spans-integration.mdx b/includes/migration/javascript-v11/interaction-spans-integration.mdx index 2abf543870bde..2f814c16d7901 100644 --- a/includes/migration/javascript-v11/interaction-spans-integration.mdx +++ b/includes/migration/javascript-v11/interaction-spans-integration.mdx @@ -30,4 +30,4 @@ Sentry.init({ }); ``` -The `idleTimeout`, `finalTimeout`, and `childSpanTimeout` options of interaction spans are configured on `interactionsIntegration` now, with the same defaults as before. +Configure `idleTimeout`, `finalTimeout`, and `childSpanTimeout` for interaction spans on `interactionsIntegration`, with the same defaults as before. BrowserTracing's timeout options still control pageload and navigation spans. See Interactions for configuration and CDN loading instructions. diff --git a/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx b/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx index ffcba16027333..5b773dbd569b1 100644 --- a/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx +++ b/includes/migration/javascript-v11/koa-hapi-error-handlers.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx b/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx new file mode 100644 index 0000000000000..e343d22a890e8 --- /dev/null +++ b/includes/migration/javascript-v11/nextjs-tunnel-middleware.mdx @@ -0,0 +1,12 @@ +--- +id: nextjs-tunnel-middleware +title: "Tunnel requests now run through Next.js middleware" +phase: code-changes +category: behavior +severity: action-required +frameworks: [nextjs] +platformCategory: all +order: 335 +--- + +Webpack builds no longer bypass your middleware for `tunnelRoute` requests. If your middleware blocks unauthenticated requests globally, set `tunnelRoute` to a fixed string instead of `true` and exclude that path in your middleware `matcher` so Sentry events can reach the tunnel. diff --git a/includes/migration/javascript-v11/node-loader-entry-points.mdx b/includes/migration/javascript-v11/node-loader-entry-points.mdx index 936dffaa3e7c4..cb2a6e0c8ec01 100644 --- a/includes/migration/javascript-v11/node-loader-entry-points.mdx +++ b/includes/migration/javascript-v11/node-loader-entry-points.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/node-removed-apis.mdx b/includes/migration/javascript-v11/node-removed-apis.mdx index c65e804a36d7e..e2b779bb94d57 100644 --- a/includes/migration/javascript-v11/node-removed-apis.mdx +++ b/includes/migration/javascript-v11/node-removed-apis.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx b/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx new file mode 100644 index 0000000000000..23f975213a8af --- /dev/null +++ b/includes/migration/javascript-v11/nuxt-auto-inject-deprecated.mdx @@ -0,0 +1,17 @@ +--- +id: nuxt-auto-inject-deprecated +title: "`autoInjectServerSentry` and `experimental_entrypointWrappedFunctions` are deprecated" +phase: cleanup +category: behavior +severity: informational +frameworks: [nuxt] +platformCategory: all +order: 60 +--- + +The SDK [bundles the server config](#nuxt-server-config-bundled) by default, so the Nuxt module options that inject it are no longer needed. They are deprecated and will be removed in the next major version. Remove them from the `sentry` options in your `nuxt.config.ts`: + +- `autoInjectServerSentry` (`"top-level-import"` and `"experimental_dynamic-import"`) +- `experimental_entrypointWrappedFunctions` + +While `autoInjectServerSentry` is set, the SDK uses that mode instead of the bundled initialization and prints a deprecation warning during the build. diff --git a/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx b/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx new file mode 100644 index 0000000000000..8e1d1bd761c67 --- /dev/null +++ b/includes/migration/javascript-v11/nuxt-server-config-bundled.mdx @@ -0,0 +1,26 @@ +--- +id: nuxt-server-config-bundled +title: "The Nuxt server config is bundled, `--import` is no longer needed" +phase: packages +category: behavior +severity: behavior-change +frameworks: [nuxt] +platformCategory: all +order: 87 +--- + +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. Instrumentation happens at build time, so you no longer preload the config file. Remove the `--import` flag from your start commands: + +```bash +# Before +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +NODE_OPTIONS='--import ./.nuxt/dev/sentry.server.config.mjs' nuxt dev + +# After +node .output/server/index.mjs +nuxt dev +``` + +Existing start commands continue to work. The SDK still writes a file to the old path, but this file only prints a reminder to remove the flag. If you preload your own file that calls `Sentry.init()`, that call initializes the SDK and the bundled initialization is skipped. + +The SDK doesn't initialize while Nitro prerenders pages at build time, so builds no longer send events. diff --git a/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx b/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx index 60f4db28168c5..81f957f844b95 100644 --- a/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx +++ b/includes/migration/javascript-v11/nuxt-server-instrument-file.mdx @@ -11,8 +11,4 @@ order: 85 `public/instrument.server.[ext]` is no longer supported. Move the file next to `nuxt.config.ts` and rename it to `sentry.server.config.[ext]`. Its contents don't change. -After the rename, the SDK emits `.output/server/sentry.server.config.mjs` for you to preload: - -```bash -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs -``` +After the rename, the SDK [bundles the file](#nuxt-server-config-bundled) into the Nitro server build. You no longer preload it with `--import`. diff --git a/includes/migration/javascript-v11/remix-vite-subpath.mdx b/includes/migration/javascript-v11/remix-vite-subpath.mdx index 65288da8dc23c..ce997529a4f43 100644 --- a/includes/migration/javascript-v11/remix-vite-subpath.mdx +++ b/includes/migration/javascript-v11/remix-vite-subpath.mdx @@ -20,3 +20,5 @@ import { sentryRemixVitePlugin } from "@sentry/remix/vite"; ``` The plugin applies the build-time instrumentation transform now. If you added `sentryOrchestrionPlugin()` from `@sentry/server-utils/orchestrion/vite` yourself, remove it. Opt out with `sentryRemixVitePlugin({ buildTimeInstrumentation: false })`. + +The plugin also injects debug IDs and uploads source maps when you pass `org`, `project`, and `authToken`. Disable source-map processing with `sentryRemixVitePlugin({ sourcemaps: { disable: true } })`. diff --git a/includes/migration/javascript-v11/require-to-import.mdx b/includes/migration/javascript-v11/require-to-import.mdx index accc72bb4aec4..6867a78ae04a9 100644 --- a/includes/migration/javascript-v11/require-to-import.mdx +++ b/includes/migration/javascript-v11/require-to-import.mdx @@ -9,7 +9,6 @@ frameworks: astro, aws-lambda, azure-functions, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/span-attribute-changes.mdx b/includes/migration/javascript-v11/span-attribute-changes.mdx index 4c070d672cb27..78831ab1c8db6 100644 --- a/includes/migration/javascript-v11/span-attribute-changes.mdx +++ b/includes/migration/javascript-v11/span-attribute-changes.mdx @@ -42,6 +42,10 @@ Legacy span attributes were replaced by their semantic-convention equivalents. U Transport values change from `ip_tcp` and `ip_udp` to `tcp` and `udp`. HTTP instrumentation reports the protocol as `network.protocol.name` and its version as `network.protocol.version`. +HTTP header attribute names keep their hyphens instead of replacing them with underscores. For example, `http.request.header.user_agent` becomes `http.request.header.user-agent`. Header values are now string arrays, with one entry per value: `['gzip', 'deflate']` replaces `'gzip;deflate'`. + +Cookies are no longer split into attributes per cookie name. `http.request.header.cookie` and `http.request.header.set-cookie` now hold arrays of `name=value` entries in the order sent, such as `['session=[Filtered]', 'theme=dark']`. Sensitive values remain filtered, and Set-Cookie attributes such as `HttpOnly` are still omitted. + On server-side HTTP spans, the `content-length` header is always reported as `http.request.body.size` and `http.response.body.size`, instead of switching to `http.request_body_size_uncompressed` when no encoding was present. @@ -96,8 +100,11 @@ The Anthropic integration no longer sets `gen_ai.prompt`. The legacy Completions - On `ui.long_animation_frame` spans, `code.filepath` and `code.function` became `code.file.path` and `code.function.name`. - On `file` spans, `fs_error` became `error.type` and holds the syscall error code (`ENOENT`) instead of the full message. - The TanStack Router integration reports path parameters as `url.path.parameter.` instead of `url.path.params.`. +- Vue Router's `navigation.route.id` became `router.navigation.route.id`, with the same matched route name. +- AWS Lambda spans use `faas.invocation_id` instead of `faas.execution` for the request ID, and `cloud.resource_id` instead of `faas.id` for the invoked function ARN. Lambda `Invoke` spans from `awsIntegration` also use `faas.invocation_id`. +- Koa router and middleware spans no longer set `koa.name`. Use `http.route` for the route and `code.function.name` for the middleware handler. - The Cloudflare-specific `sentry.cloudflare_tracer` attribute is no longer set. - Import attribute constants from `@sentry/core` directly. The `semanticAttributes` re-export was removed. -- `SEMANTIC_ATTRIBUTE_SENTRY_SOURCE` (`sentry.source`) was replaced by `SENTRY_SEGMENT_NAME_SOURCE` (`sentry.segment.name.source`), which is only set on the root span. +- `sentry.source` (`SEMANTIC_ATTRIBUTE_SENTRY_SOURCE`) was replaced by `sentry.segment.name.source`, which is only set on the root span. diff --git a/includes/migration/javascript-v11/span-name-changes.mdx b/includes/migration/javascript-v11/span-name-changes.mdx index 137a5055e9261..89653cdaa5532 100644 --- a/includes/migration/javascript-v11/span-name-changes.mdx +++ b/includes/migration/javascript-v11/span-name-changes.mdx @@ -51,8 +51,24 @@ Whatever the name no longer carries stays on an attribute, in both trace lifecyc | `db` (Mongoose) | `mongoose..` (`mongoose.BlogPost.findOne`) | The operation and collection (`findOne blogposts`), the database namespace, or `mongodb` | | `db` (Supabase) | The query builder call and table (`select(...) from(users)`), or `auth ` | The operation and table (`select users`), or the dotted auth method (`auth.signInWithPassword`) | | `db.query` (Redis, ioredis) | The serialized command with redacted arguments (`set test-key [1 other arguments]`) | The operation and connection (`SET localhost:6379`), the operation and redis function for `FCALL`, or `redis` | +| `browser.*` navigation timing | The document URL | A static phase name, such as `DNS lookup`, `Request`, or `Load event` | +| `function` | Integration-specific, such as `serverAction/updateUser` or `LOADER routes/users.$id` | `code.function.name`, such as `updateUser` or `loader` | +| `function` (Angular `TraceMethod`) | `` or `` | The decorator's `name`, or `Function execution` | +| `function` (SvelteKit) | The route or request path | The wrapped function's name, such as `load` or `GET` | +| `function` (Ember route hooks) | The full route name | The hook name, such as `beforeModel`, `model`, or `setupController` | +| `function` (React Router route hooks) | The route, raw URL path, or fetcher key | The hook name, such as `loader`, `action`, `clientLoader`, or `fetcher` | +| `function` (NestJS `@OnEvent`) | `event user.created` | The event name, such as `user.created` | +| `function` (TanStack Start server functions) | `GET /_serverFn/abc123` | The function name, or `serverFn` until middleware resolves it | +| `function.gcp` | The HTTP method and path, or trigger type | The function name, or `Serverless function execution` | +| `function.aws` | The Lambda function name | Unchanged, with `Serverless function execution` as the fallback | +| `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | ``, `Vue `, `Application Render`, or `init` | The unwrapped component name, or `Component mount`, `Component render`, `Component update`, or `Component unmount` | +| `ui.task` | `runloop` | `UI task` | +| `ui.action.click` | The pageload or navigation span's name | `router.navigation.route.id`, `url.template`, or `http.route`, in that order, or `Click` | +| `ui.interaction.*` | The element's DOM path | The annotated component name, or `Click`, `Hover`, `Drag`, or `Key press` | +| `ui.webvital.lcp` | The LCP element's DOM path | The annotated component name, or `Largest contentful paint` | +| `ui.webvital.cls` | The first layout-shift source's DOM path | The annotated component name, or `Layout shift` | -A few consequences worth checking: +In transaction mode, span names remain unchanged. A few consequences worth checking: - `useOperationNameForRootSpan` no longer renames the enclosing root span. The operations stay on that span's `sentry.graphql.operation` attribute. - `graphqlClientIntegration` no longer appends the operation to the outgoing request span name. It's on `graphql.operation.name` and `graphql.operation.type` instead. @@ -66,6 +82,37 @@ A few consequences worth checking: + + +Browser navigation timing spans use these names: + +| Span op | Name | +| ---------------------------------- | ------------------------ | +| `browser.cache` | `Cache lookup` | +| `browser.dns` | `DNS lookup` | +| `browser.connect` | `Connect` | +| `browser.tls_ssl` | `TLS handshake` | +| `browser.redirect` | `Redirect` | +| `browser.request` | `Request` | +| `browser.response` | `Response` | +| `browser.unload_event` | `Unload event` | +| `browser.dom_content_loaded_event` | `DOMContentLoaded event` | +| `browser.load_event` | `Load event` | + +The document URL stays on `url.full` in both trace lifecycles, subject to `dataCollection.urlQueryParams`. Update name-based filters to use that attribute. + +Framework function spans keep the previous name on `sentry.description`. For SvelteKit, this includes `wrapLoadWithSentry`, `wrapServerLoadWithSentry`, `wrapServerRouteWithSentry`, and spans from SvelteKit's own tracing. Match the route on `http.route`, or `url.template` for client-side universal loads, and the request path on `url.path`. + +GCP and Firebase function names come from `FUNCTION_TARGET` or `K_SERVICE`. The function name stays on `faas.name`, trigger details on `gcp.function.context.*`, and HTTP method and path on `http.request.method` and `url.path`. AWS Lambda spans fall back to `Serverless function execution` when neither the invocation context nor `AWS_LAMBDA_FUNCTION_NAME` provides a name. Their `sentry.segment.name.source` is now `component` in both trace lifecycles. + +Component spans keep their original names on `sentry.description`. Vue's `Application Render` becomes `Root`, and Ember's `init` becomes `Component mount`. Update filters matching `` or `Vue ` to use the new name or the description. + +Click idle spans copy `router.navigation.route.id`, `url.template`, `http.route`, `url.path`, and `url.full` from the route span. Event Timing and INP spans keep the DOM path on `browser.web_vital.inp.target` and the annotated component on `ui.component_name`, in both trace lifecycles. Match the target attribute if you previously filtered by DOM path. + +LCP and CLS DOM paths stay on `browser.web_vital.lcp.element` and `browser.web_vital.cls.source.1`. Long task and long animation frame names remain `Main UI thread blocked`. + + + `ignoreSpans` and `tracesSampler` both run when a span **starts**, so a span may not have its final name yet. Match on attributes instead: @@ -83,7 +130,7 @@ Sentry.init({ { attributes: { "db.query.text": "SELECT * FROM health_check" } }, ], tracesSampler: ({ attributes, inheritOrSampleWith }) => - inheritOrSampleWith(attributes["url.path"] === "/health" ? 0 : 1), + inheritOrSampleWith(attributes?.["url.path"] === "/health" ? 0 : 1), }); ``` diff --git a/includes/migration/javascript-v11/span-op-changes.mdx b/includes/migration/javascript-v11/span-op-changes.mdx index 0e1fcd1747467..757e1b28aece4 100644 --- a/includes/migration/javascript-v11/span-op-changes.mdx +++ b/includes/migration/javascript-v11/span-op-changes.mdx @@ -17,14 +17,14 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic **Backend HTTP, handlers, middleware, and routers** -| Area | Before | After | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| Request handlers (Express, Koa, Connect, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | -| Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | -| Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | -| Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | -| Hapi server extensions | `server.ext.hapi` | `middleware` | -| NestJS setup and lifecycle handlers | `app_creation.nestjs`, `request_context.nestjs`, `event.nestjs` | `function` | +| Area | Before | After | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| Request handlers (Express, Koa, Fastify, Elysia, NestJS) | `request_handler.`, `handler.nestjs` | `handler` | +| Hono `app.request()` in-process dispatch | `hono.request` | `http.server` | +| Web-server middleware | `middleware.express`, `middleware.koa`, `middleware.hono`, `middleware.elysia`, `middleware.nestjs`, `middleware.nuxt`, `middleware.nitro`, `middleware.tanstackstart`, `hook.fastify`, `http.server.middleware` (Next.js) | `middleware` | +| Backend router layers | `router.express`, `router.koa`, `router.hapi` | `router` | +| Hapi server extensions | `server.ext.hapi` | `middleware` | +| NestJS setup and lifecycle handlers | `app_creation.nestjs`, `request_context.nestjs`, `event.nestjs` | `function` | **Framework functions** @@ -39,7 +39,7 @@ Update anything that filters, groups, or alerts on span ops: dashboards, dynamic | Frontend routing | `ui.angular.routing`, `ui.sveltekit.routing`, `ui.ember.transition` | `router` | | React, Vue, and Svelte component lifecycles | `ui.react.mount`/`render`/`update`, `ui.svelte.init`/`update`, Vue `render`/`update`/`mount`/`create`/`activate`/`unmount`/`destroy` | `ui.mount`, `ui.render`, `ui.update`, `ui.unmount` | | Angular tracing decorators | `ui.angular.init`, `ui.angular.` | `ui.mount`, `function` | -| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`function`/`ui.mount` | +| Ember route hooks, runloop, and components | `ui.ember.route.`, `ui.ember.runloop.`, `ui.ember.component.render`/`definition`/`init` | `function`, `ui.task`, `ui.render`/`ui.resolve`/`ui.mount` | | Browser paint entries | `paint` | `browser.paint` | **Databases, cache, and messaging** diff --git a/includes/migration/javascript-v11/track-fetch-stream-performance.mdx b/includes/migration/javascript-v11/track-fetch-stream-performance.mdx index c2dd1eedf5538..167aecfba86c8 100644 --- a/includes/migration/javascript-v11/track-fetch-stream-performance.mdx +++ b/includes/migration/javascript-v11/track-fetch-stream-performance.mdx @@ -29,3 +29,5 @@ Sentry.init({ ], }); ``` + +See FetchStreamPerformance for supported response types and setup instructions. diff --git a/includes/migration/javascript-v11/unhandled-rejection-warning.mdx b/includes/migration/javascript-v11/unhandled-rejection-warning.mdx index fd58dc05c9a11..66bda3b963ce3 100644 --- a/includes/migration/javascript-v11/unhandled-rejection-warning.mdx +++ b/includes/migration/javascript-v11/unhandled-rejection-warning.mdx @@ -10,7 +10,6 @@ frameworks: aws-lambda, azure-functions, bun, - connect, effect, elysia, express, diff --git a/includes/migration/javascript-v11/webpack-plugin-entry.mdx b/includes/migration/javascript-v11/webpack-plugin-entry.mdx new file mode 100644 index 0000000000000..5fbd4c05f6a8a --- /dev/null +++ b/includes/migration/javascript-v11/webpack-plugin-entry.mdx @@ -0,0 +1,20 @@ +--- +id: webpack-plugin-entry +title: "The webpack plugin requires webpack 5.1 and a new import path" +phase: packages +category: removed-api +severity: action-required +frameworks: all +platformCategory: all +order: 68 +--- + +The Sentry webpack plugin requires webpack **5.1** or newer. The `@sentry/bundler-plugins/webpack5` entry point was removed. Update imports to `@sentry/bundler-plugins/webpack`: + +```js +// Before +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack5"; + +// After +import { sentryWebpackPlugin } from "@sentry/bundler-plugins/webpack"; +``` diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index 8ee5e2d2aef86..2ba4813cab311 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -27,7 +27,7 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; - + - + -By default, the JavaScript Browser SDKs are sending sessions. -We create a session for every page load. For single-page applications, we will create a new session for every navigation change (History API). +JavaScript Browser SDKs track sessions by default. A session starts on page load and continues across client-side navigations. A hard reload or navigation starts a new session. + +Before SDK version 11, the SDK started a new session on each client-side navigation by default. To configure this behavior, see BrowserSession lifecycle. To disable the default sessions handling, disable the `BrowserSession` integration: @@ -22,13 +23,13 @@ Sentry.init({ By default, the Node.js-based SDKs are sending sessions. Sessions are created for every incoming request. -To disable the default sessions handling, set `trackIncomingRequestsAsSessions: false` in the `httpIntegration`: +To disable the default sessions handling, set `sessions: false` in the `httpIntegration`: ```javascript import * as Sentry from "@sentry/node"; Sentry.init({ - integrations: [httpIntegration({ trackIncomingRequestsAsSessions: false })], + integrations: [Sentry.httpIntegration({ sessions: false })], }); ``` @@ -37,7 +38,18 @@ Sentry.init({ Sessions are marked as: -- `crashed` if an _unhandled error_ or _unhandled promise rejection_ bubbled up to the global handler. + + +- `unhandled` in the browser if an _unhandled error_ or _unhandled promise rejection_ bubbles up to the global handler. Before SDK version 11, browser sessions used `crashed` for these errors. + + + + + +- `crashed` on the server if an _unhandled error_ or _unhandled promise rejection_ bubbles up to the global handler. + + + - `errored` if the SDK captures an event that contains an exception (this includes manually captured errors). To receive data on user adoption, such as users crash free rate percentage, and the number of users that have adopted a specific release, set the user on the [`initialScope`](/platforms/javascript/configuration/options/#initial-scope) when initializing the SDK. diff --git a/platform-includes/configuration/auto-session-tracking/javascript.node.mdx b/platform-includes/configuration/auto-session-tracking/javascript.node.mdx index 7ed83295e2e2e..a6bb37d4bcea7 100644 --- a/platform-includes/configuration/auto-session-tracking/javascript.node.mdx +++ b/platform-includes/configuration/auto-session-tracking/javascript.node.mdx @@ -7,12 +7,12 @@ We mark the session as crashed if an _unhandled error_ reached our `errorHandler We mark the session as an error if the SDK captures an event that contains an exception (this includes manually captured exceptions). -By default, the SDK is sending sessions, to disable this configure the `httpIntegration` with the `trackIncomingRequestsAsSessions` option set to `false`. +By default, the SDK is sending sessions, to disable this configure the `httpIntegration` with the `sessions` option set to `false`. ```javascript Sentry.init({ integrations: [Sentry.httpIntegration({ - trackIncomingRequestsAsSessions: false, // default: true + sessions: false, // default: true })] }); ``` diff --git a/platform-includes/configuration/before-send-span/javascript.mdx b/platform-includes/configuration/before-send-span/javascript.mdx index 13b5f9623a3f7..cd707dd185d10 100644 --- a/platform-includes/configuration/before-send-span/javascript.mdx +++ b/platform-includes/configuration/before-send-span/javascript.mdx @@ -1,11 +1,11 @@ -```javascript {tabTitle:Transaction Mode (Default)} +```javascript {tabTitle:Stream Mode (Default)} {mdExpandTabs} Sentry.init({ dsn: "___PUBLIC_DSN___", beforeSendSpan(span) { - if (span.description === "should be renamed") { - span.description = "renamed span"; - span.data = { - ...span.data, + if (span.name === "should be renamed") { + span.name = "renamed span"; + span.attributes = { + ...span.attributes, myExtraAttribute: true, }; } @@ -15,14 +15,15 @@ Sentry.init({ }); ``` -```javascript {tabTitle:Stream Mode} +```javascript {tabTitle:Transaction Mode} Sentry.init({ dsn: "___PUBLIC_DSN___", - beforeSendSpan: Sentry.withStreamedSpan((span) => { - if (span.name === "should be renamed") { - span.name = "renamed span"; - span.attributes = { - ...span.attributes, + traceLifecycle: "static", + beforeSendSpan: Sentry.withStaticSpan((span) => { + if (span.description === "should be renamed") { + span.description = "renamed span"; + span.data = { + ...span.data, myExtraAttribute: true, }; } diff --git a/platform-includes/configuration/before-send-transaction/javascript.mdx b/platform-includes/configuration/before-send-transaction/javascript.mdx index c1d1a05093a2c..d49e4d6eab7de 100644 --- a/platform-includes/configuration/before-send-transaction/javascript.mdx +++ b/platform-includes/configuration/before-send-transaction/javascript.mdx @@ -1,9 +1,9 @@ ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", + traceLifecycle: "static", beforeSendTransaction(event) { if (event.transaction === "/unimportant/route") { - // Don't send the event to Sentry return null; } return event; diff --git a/platform-includes/configuration/featureflags/javascript.connect.mdx b/platform-includes/configuration/featureflags/javascript.connect.mdx deleted file mode 100644 index bc6e647338a26..0000000000000 --- a/platform-includes/configuration/featureflags/javascript.connect.mdx +++ /dev/null @@ -1,16 +0,0 @@ -```typescript -import * as Sentry from '@sentry/connect'; - -Sentry.init({ - dsn: '___PUBLIC_DSN___', - integrations: [Sentry.featureFlagsIntegration()] -}); - -const flagsIntegration = Sentry.getClient()?.getIntegrationByName('FeatureFlags'); -if (flagsIntegration) { - flagsIntegration.addFeatureFlag('test-flag', false); -} else { - // Something went wrong, check your DSN and/or integrations -} -Sentry.captureException(new Error('Something went wrong!')); -``` diff --git a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx index 5eca495abeaf2..9641067ed53c8 100644 --- a/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx +++ b/platform-includes/configuration/filter-application-key/javascript.nextjs.mdx @@ -1,27 +1,13 @@ -**Webpack:** - -```javascript {tabTitle:CJS} {filename:next.config.js} {3} -module.exports = withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, -}); -``` - -```javascript {tabTitle:ESM} {filename:next.config.mjs} {3} +```javascript {tabTitle:ESM} {filename:next.config.mjs} {2} export default withSentryConfig(nextConfig, { - unstable_sentryWebpackPluginOptions: { - applicationKey: "your-custom-application-key", - }, + applicationKey: "your-custom-application-key", }); ``` -**Turbopack (Next.js 16+, experimental):** - -```javascript {filename:next.config.ts} {3} -export default withSentryConfig(nextConfig, { - _experimental: { - turbopackApplicationKey: "your-custom-application-key", - }, +```javascript {tabTitle:CJS} {filename:next.config.js} {2} +module.exports = withSentryConfig(nextConfig, { + applicationKey: "your-custom-application-key", }); ``` + +This works for both Webpack and Turbopack builds. diff --git a/platform-includes/configuration/ignore-transactions/javascript.mdx b/platform-includes/configuration/ignore-transactions/javascript.mdx index 1aa8541e84719..d1728e2f5bc5a 100644 --- a/platform-includes/configuration/ignore-transactions/javascript.mdx +++ b/platform-includes/configuration/ignore-transactions/javascript.mdx @@ -1,6 +1,7 @@ ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", + traceLifecycle: "static", ignoreTransactions: ["partial/match", /^Exact Transaction Name$/], }); ``` diff --git a/platform-includes/configuration/integrations/javascript.astro.mdx b/platform-includes/configuration/integrations/javascript.astro.mdx index 5d44264f8c76d..305ea4bd3cbee 100644 --- a/platform-includes/configuration/integrations/javascript.astro.mdx +++ b/platform-includes/configuration/integrations/javascript.astro.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -71,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -81,10 +85,14 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx index d9faf15d2a6ca..daf01fb6677d3 100644 --- a/platform-includes/configuration/integrations/javascript.aws-lambda.mdx +++ b/platform-includes/configuration/integrations/javascript.aws-lambda.mdx @@ -7,9 +7,9 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`modulesIntegration`](./modules) | ✓ | | | ✓ | | [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | @@ -17,11 +17,15 @@ | [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | | [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`amqplibIntegration`](./amqplib) | | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.bun.mdx b/platform-includes/configuration/integrations/javascript.bun.mdx index 9a05e62814063..30c3ec00901c1 100644 --- a/platform-includes/configuration/integrations/javascript.bun.mdx +++ b/platform-includes/configuration/integrations/javascript.bun.mdx @@ -7,11 +7,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | @@ -29,11 +29,15 @@ | [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`bunRuntimeMetricsIntegration`](./bunruntimemetrics) | | | | ✓ | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.capacitor.mdx b/platform-includes/configuration/integrations/javascript.capacitor.mdx index dde93c2b4c7d0..bf592b4487b67 100644 --- a/platform-includes/configuration/integrations/javascript.capacitor.mdx +++ b/platform-includes/configuration/integrations/javascript.capacitor.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.cloudflare.mdx b/platform-includes/configuration/integrations/javascript.cloudflare.mdx index deddfb8faa9f7..a4c0a16fb41bf 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -3,9 +3,9 @@ | | **Auto Enabled** | **Errors** | **Tracing** | **Cron** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`fetchIntegration`](./fetchIntegration) | ✓ | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`requestDataIntegration`](./requestdata) | ✓ | | | | ✓ | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | @@ -14,6 +14,7 @@ | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`prismaIntegration`](./prisma) | | | ✓ | | | -| [`honoIntegration`](./hono) | ✓ | ✓ | | | | -The [`prismaIntegration`](./prisma) is only available through the [`@sentry/cloudflare/nodejs_compat`](../../features/nodejs-compat) entrypoint. +[Mistral AI](./mistral) is automatically instrumented when built with the Sentry Cloudflare Vite plugin. Without the plugin, use `instrumentMistralAiClient`. + +The [`prismaIntegration`](./prisma) needs the `nodejs_compat` compatibility flag on your Worker. diff --git a/platform-includes/configuration/integrations/javascript.connect.mdx b/platform-includes/configuration/integrations/javascript.connect.mdx deleted file mode 100644 index b2ce33a4e7010..0000000000000 --- a/platform-includes/configuration/integrations/javascript.connect.mdx +++ /dev/null @@ -1,51 +0,0 @@ -### Integrations - -| | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | -| --------------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | -| [`amqplibIntegration`](./amqplib) | ✓ | | ✓ | | -| [`consoleIntegration`](./console) | ✓ | | | ✓ | -| [`connectIntegration`](./connect) | ✓ | | ✓ | | -| [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | -| [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | -| [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | -| [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | -| [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | -| [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | -| [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | -| [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | -| [`modulesIntegration`](./modules) | ✓ | | | ✓ | -| [`mongoIntegration`](./mongo) | ✓ | | ✓ | | -| [`mongooseIntegration`](./mongoose) | ✓ | | ✓ | | -| [`mysqlIntegration`](./mysql) | ✓ | | ✓ | | -| [`mysql2Integration`](./mysql2) | ✓ | | ✓ | | -| [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | -| [`nativeNodeFetchIntegration`](./nodefetch) | ✓ | | ✓ | ✓ | -| [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | -| [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | -| [`postgresIntegration`](./postgres) | ✓ | | ✓ | | -| [`redisIntegration`](./redis) | ✓ | | ✓ | | -| [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | -| [`tediousIntegration`](./tedious) | ✓ | | ✓ | | -| [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`rewriteFramesIntegration`](./rewriteframes) | ✓ | ✓ | | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | -| [`anrIntegration`](./anr) | | ✓ | | | -| [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | -| [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | -| [`dataloaderIntegration`](./dataloader) | | | ✓ | | -| [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | -| [`fsIntegration`](./fs) | | | ✓ | | -| [`knexIntegration`](./knex) | | | ✓ | | -| [`localVariablesIntegration`](./localvariables) | | ✓ | | | -| [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | -| [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | -| [`prismaIntegration`](./prisma) | | | ✓ | | -| [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | -| [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.cordova.mdx b/platform-includes/configuration/integrations/javascript.cordova.mdx index b018d5a58ec4a..d02c879125bb8 100644 --- a/platform-includes/configuration/integrations/javascript.cordova.mdx +++ b/platform-includes/configuration/integrations/javascript.cordova.mdx @@ -5,10 +5,10 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.deno.mdx b/platform-includes/configuration/integrations/javascript.deno.mdx index 4aab5d17afbf3..bc060c536aaf5 100644 --- a/platform-includes/configuration/integrations/javascript.deno.mdx +++ b/platform-includes/configuration/integrations/javascript.deno.mdx @@ -3,12 +3,13 @@ | | **Auto Enabled** | **Errors** | **Tracing** | **Cron** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :------: | :--------------------: | | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | | [`denoContextIntegration`](./denocontext) | ✓ | | | | ✓ | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`denoCronIntegration`](./denocron) | | | | ✓ | | @@ -19,3 +20,4 @@ | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | | ✓ | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.fastify.mdx b/platform-includes/configuration/integrations/javascript.fastify.mdx index 807d522390215..c928ec5d0d60d 100644 --- a/platform-includes/configuration/integrations/javascript.fastify.mdx +++ b/platform-includes/configuration/integrations/javascript.fastify.mdx @@ -5,12 +5,12 @@ | [`amqplibIntegration`](./amqplib) | ✓ | | ✓ | | | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`fastifyIntegration`](./fastify) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | @@ -29,11 +29,15 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.gatsby.mdx b/platform-includes/configuration/integrations/javascript.gatsby.mdx index 5aff5b73147a2..e66be97928127 100644 --- a/platform-includes/configuration/integrations/javascript.gatsby.mdx +++ b/platform-includes/configuration/integrations/javascript.gatsby.mdx @@ -4,15 +4,20 @@ |-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:| | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx index 61e464d853018..5914b98376820 100644 --- a/platform-includes/configuration/integrations/javascript.gcp-functions.mdx +++ b/platform-includes/configuration/integrations/javascript.gcp-functions.mdx @@ -5,11 +5,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`googleCloudGrpcIntegration`](./googlecloudgrpc) | ✓ | | ✓ | | | [`googleCloudHttpIntegration`](./googlecloudhttp) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`modulesIntegration`](./modules) | ✓ | | | ✓ | | [`nodeContextIntegration`](./nodecontext) | ✓ | | | ✓ | @@ -17,11 +17,15 @@ | [`onUncaughtExceptionIntegration`](./onuncaughtexception) | ✓ | ✓ | | | | [`onUnhandledRejectionIntegration`](./unhandledrejection) | ✓ | ✓ | | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`amqplibIntegration`](./amqplib) | | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.hapi.mdx b/platform-includes/configuration/integrations/javascript.hapi.mdx index 7ed14e4ceef24..40090a1bf4908 100644 --- a/platform-includes/configuration/integrations/javascript.hapi.mdx +++ b/platform-includes/configuration/integrations/javascript.hapi.mdx @@ -6,12 +6,12 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`hapiIntegration`](./hapi) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | @@ -30,11 +30,15 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index 9ce918e102f78..9a1d0fe9b87f1 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -5,14 +5,20 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | +| [`bfcacheMetricsIntegration`](./bfcache) | | | | | | | [`elementTimingIntegration`](./elementtiming) | | | | | | | [`captureConsoleIntegration`](./captureconsole) | | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | diff --git a/platform-includes/configuration/integrations/javascript.nestjs.mdx b/platform-includes/configuration/integrations/javascript.nestjs.mdx index 00b3a8bf1614c..1c0a32c016555 100644 --- a/platform-includes/configuration/integrations/javascript.nestjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nestjs.mdx @@ -6,11 +6,11 @@ | [`consoleIntegration`](./console) | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`lruMemoizerIntegration`](./lrumemoizer) | ✓ | | ✓ | | @@ -30,7 +30,7 @@ | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | @@ -44,9 +44,13 @@ | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nextjs.mdx b/platform-includes/configuration/integrations/javascript.nextjs.mdx index 58b03e0ad63ff..e5fbd3eb908cd 100644 --- a/platform-includes/configuration/integrations/javascript.nextjs.mdx +++ b/platform-includes/configuration/integrations/javascript.nextjs.mdx @@ -12,8 +12,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -27,6 +27,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -87,11 +91,15 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | ✓ | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | @@ -100,4 +108,4 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`winterCGFetchIntegration`](./wintercgfetch) | ✓ | | ✓ | ✓ | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | | | ✓ | | diff --git a/platform-includes/configuration/integrations/javascript.node.mdx b/platform-includes/configuration/integrations/javascript.node.mdx index 5973f59e60b12..489437d96bed0 100644 --- a/platform-includes/configuration/integrations/javascript.node.mdx +++ b/platform-includes/configuration/integrations/javascript.node.mdx @@ -11,13 +11,13 @@ | [`contextLinesIntegration`](./contextlines) | ✓ | ✓ | | | | [`dataloaderIntegration`](./dataloader) | | | ✓ | | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | | [`fsIntegration`](./fs) | | | ✓ | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | [`genericPoolIntegration`](./genericpool) | ✓ | | ✓ | | | [`graphqlIntegration`](./graphql) | ✓ | | ✓ | | | [`httpIntegration`](./http) | ✓ | ✓ | ✓ | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`kafkaIntegration`](./kafka) | ✓ | | ✓ | | | [`knexIntegration`](./knex) | | | ✓ | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | @@ -38,15 +38,19 @@ | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | | [`redisIntegration`](./redis) | ✓ | | ✓ | | | [`requestDataIntegration`](./requestdata) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`rewriteFramesIntegration`](./rewriteframes) | | ✓ | | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`tediousIntegration`](./tedious) | ✓ | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`firebaseIntegration`](./firebase) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.nuxt.mdx b/platform-includes/configuration/integrations/javascript.nuxt.mdx index 299722eb63186..45e809cc438e3 100644 --- a/platform-includes/configuration/integrations/javascript.nuxt.mdx +++ b/platform-includes/configuration/integrations/javascript.nuxt.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -71,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -81,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.remix.mdx b/platform-includes/configuration/integrations/javascript.remix.mdx index b7e2d2dc2a8ab..0a099873775dd 100644 --- a/platform-includes/configuration/integrations/javascript.remix.mdx +++ b/platform-includes/configuration/integrations/javascript.remix.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -71,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -81,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.solidstart.mdx b/platform-includes/configuration/integrations/javascript.solidstart.mdx index a33bc442497a4..a71907c8ea8f8 100644 --- a/platform-includes/configuration/integrations/javascript.solidstart.mdx +++ b/platform-includes/configuration/integrations/javascript.solidstart.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -71,7 +75,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -81,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeRuntimeMetricsIntegration`](./noderuntimemetrics) | | | | ✓ | | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.sveltekit.mdx b/platform-includes/configuration/integrations/javascript.sveltekit.mdx index 5f9b60c65be93..031724444dab9 100644 --- a/platform-includes/configuration/integrations/javascript.sveltekit.mdx +++ b/platform-includes/configuration/integrations/javascript.sveltekit.mdx @@ -11,8 +11,8 @@ Depending on whether an integration enhances the functionality of a particular r | | **Auto Enabled** | **Errors** | **Tracing** | **Additional Context** | | --------------------------------------------------- | :--------------: | :--------: | :---------: | :--------------------: | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | ✓ | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -26,6 +26,10 @@ Depending on whether an integration enhances the functionality of a particular r | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | ✓ | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | @@ -70,7 +74,7 @@ Depending on whether an integration enhances the functionality of a particular r | [`childProcessIntegration`](./childProcess) | ✓ | | | ✓ | | [`dataloaderIntegration`](./dataloader) | ✓ | | ✓ | | | [`prismaIntegration`](./prisma) | ✓ | | ✓ | | -| [`vercelAiIntegration`](../../agent-tracing/vercelai) | ✓ | | ✓ | | +| [`vercelAiIntegration`](./vercelai) | ✓ | | ✓ | | | [`anrIntegration`](./anr) | | ✓ | | | | [`eventLoopBlockIntegration`](./event-loop-block) | | ✓ | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | ✓ | @@ -81,9 +85,13 @@ Depending on whether an integration enhances the functionality of a particular r | [`nodeProfilingIntegration`](./nodeprofiling) | | | ✓ | | | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | [`trpcMiddleware`](./trpc) | | ✓ | ✓ | ✓ | -| [`openAIIntegration`](../../agent-tracing/openai) | ✓ | | ✓ | | -| [`anthropicAIIntegration`](../../agent-tracing/anthropic) | ✓ | ✓ | ✓ | | -| [`googleGenAIIntegration`](../../agent-tracing/google-genai) | ✓ | ✓ | ✓ | | -| [`langChainIntegration`](../../agent-tracing/langchain) | ✓ | ✓ | ✓ | | +| [`openAIIntegration`](./openai) | ✓ | | ✓ | | +| [`anthropicAIIntegration`](./anthropic) | ✓ | ✓ | ✓ | | +| [`googleGenAIIntegration`](./google-genai) | ✓ | ✓ | ✓ | | +| [`langChainIntegration`](./langchain) | ✓ | ✓ | ✓ | | +| [`langGraphIntegration`](./langgraph) | ✓ | ✓ | ✓ | | +| [`mistralAIIntegration`](./mistral) | ✓ | | ✓ | | +| [`groqIntegration`](./groq) | ✓ | | ✓ | | +| [`togetherAIIntegration`](./together-ai) | ✓ | | ✓ | | | [`zodErrorsIntegration`](./zodErrors) | | | | ✓ | | [`pinoIntegration`](./pino) | | ✓ | | | diff --git a/platform-includes/configuration/integrations/javascript.vue.mdx b/platform-includes/configuration/integrations/javascript.vue.mdx index ecbd989aa0f01..bcb1b45943bec 100644 --- a/platform-includes/configuration/integrations/javascript.vue.mdx +++ b/platform-includes/configuration/integrations/javascript.vue.mdx @@ -5,15 +5,20 @@ | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`vueIntegration`](./vue) | ✓ | ✓ | ✓ | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/configuration/integrations/javascript.wasm.mdx b/platform-includes/configuration/integrations/javascript.wasm.mdx index ac3c8c7eab56d..8fde95e686b5d 100644 --- a/platform-includes/configuration/integrations/javascript.wasm.mdx +++ b/platform-includes/configuration/integrations/javascript.wasm.mdx @@ -4,15 +4,20 @@ |-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:| | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | +| [`consoleIntegration`](./console) | ✓ | | | | ✓ | | [`dedupeIntegration`](./dedupe) | ✓ | ✓ | | | | +| [`eventFiltersIntegration`](./eventfilters) | ✓ | ✓ | | | | | [`functionToStringIntegration`](./functiontostring) | ✓ | | | | | | [`globalHandlersIntegration`](./globalhandlers) | ✓ | ✓ | | | | | [`httpContextIntegration`](./httpcontext) | ✓ | | | | ✓ | -| [`inboundFiltersIntegration`](./inboundfilters) | ✓ | ✓ | | | | | [`linkedErrorsIntegration`](./linkederrors) | ✓ | ✓ | | | | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`fetchStreamPerformanceIntegration`](./fetchstreamperformance) | | | ✓ | | | +| [`interactionsIntegration`](./interactions) | | | ✓ | | | +| [`userTimingIntegration`](./usertiming) | | | ✓ | | | +| [`webVitalsIntegration`](./webvitals) | With BrowserTracing | | ✓ | | | | [`captureConsoleIntegration`](./captureconsole) | | | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | diff --git a/platform-includes/crons/requirements/javascript.connect.mdx b/platform-includes/crons/requirements/javascript.connect.mdx deleted file mode 100644 index ee5931db169fd..0000000000000 --- a/platform-includes/crons/requirements/javascript.connect.mdx +++ /dev/null @@ -1,2 +0,0 @@ -- Use our getting started guide to install and configure the Sentry SDK (version `7.51.1` or newer) for your recurring job. -- [Create and configure](https://sentry.io/issues/alerts/new/crons/) your first Monitor. diff --git a/platform-includes/crons/setup/javascript.deno.mdx b/platform-includes/crons/setup/javascript.deno.mdx index 27ea5ba8dc7c1..d6073a862ceb3 100644 --- a/platform-includes/crons/setup/javascript.deno.mdx +++ b/platform-includes/crons/setup/javascript.deno.mdx @@ -1,9 +1,25 @@ -## Automatic Check-Ins (Recommended) +## Job Monitoring + + + +## Check-Ins + + + +## Automatic Check-Ins With `Deno.cron` + + + +The `DenoCron` integration does not work on Deno 2.9.0 and later. On these versions `Deno.cron` is a read-only property, so `Sentry.init` stops with `TypeError: Cannot set property cron of # which has only a getter` and your app does not start. Use `Sentry.withMonitor` or `Sentry.captureCheckIn` instead. -_requires SDK version 7.88.0 or higher_ + + +_requires SDK version 7.88.0 or higher, and Deno 2.8.3 or earlier_ Use the `DenoCron` integration to monitor your [`Deno.cron`](https://deno.com/blog/cron) calls and get notified when a schedule job is missed (or doesn't start when expected), if it fails due to a problem in the runtime (such as an error), or if it fails by exceeding its maximum runtime. +The integration is not part of the default set, so you must add it to `integrations` yourself: + ```TypeScript import * as Sentry from "___SDK_PACKAGE___"; @@ -13,14 +29,6 @@ Sentry.init({ }); ``` -## Job Monitoring - - - -## Check-Ins - - - ## Upserting Cron Monitors diff --git a/platform-includes/crons/setup/javascript.nextjs.mdx b/platform-includes/crons/setup/javascript.nextjs.mdx index 0f6442a455cb3..1032edf4a9242 100644 --- a/platform-includes/crons/setup/javascript.nextjs.mdx +++ b/platform-includes/crons/setup/javascript.nextjs.mdx @@ -5,10 +5,12 @@ Cron monitoring is only supported in Server and Edge runtimes for Next.js If you are hosting your Next.js application on Vercel and you are using [Vercel's Cron Jobs feature](https://vercel.com/docs/cron-jobs), you can configure the Next.js SDK to automatically create Check-Ins for you. Instrumented cron jobs are decided at runtime by examining the `crons` field in your `vercel.json` file. -Set the `automaticVercelMonitors` option to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. +Set `_experimental.vercelCronsMonitoring` to `true` in your Sentry settings in `next.config.js`. See Manual Setup for more details. -Automatic instrumentation of Vercel cron jobs currently only works for the Pages Router. App Router route handlers are not yet supported. + The older `webpack.automaticVercelMonitors` option only works with Webpack and + the Pages Router. `_experimental.vercelCronsMonitoring` works with both + bundlers and both routers. ## Automatic Crons Instrumentation diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx index 7073f9ba97de6..805bb88f317ec 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx @@ -11,7 +11,11 @@ By default, traces are not propagated across [RPC calls](https://developers.clou That trailing argument is why propagation is opt-in per binding: only a Sentry-instrumented receiver strips it again. List the bindings whose receiver you know runs Sentry in `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). Setting the option also turns on the receiver side, so a Worker that both calls and receives needs nothing else. - If you build with the Sentry Cloudflare Vite plugin and its `autoInstrumentation` option, the plugin configures the bindings that point at classes in the same Worker. You only need to list bindings to other Workers. + If you build with the Sentry + Cloudflare Vite plugin, it derives the bindings that point at + classes in this Worker, so you only need to list bindings to other Workers. + See Derived + RPC Trace Propagation. **Worker Side (Caller):** diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx index 02a15881625cc..81a950c32070e 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.solidstart.mdx @@ -3,8 +3,8 @@ To set up distributed tracing, use Sentry's middleware to inject tracing informa Create or modify the `middleware.ts` file and import and add `sentryBeforeResponseMiddleware` ```typescript {filename: middleware.ts} -import { sentryBeforeResponseMiddleware } from '@sentry/solidstart/middleware'; -import { createMiddleware } from '@solidjs/start/middleware'; +import { sentryBeforeResponseMiddleware } from "@sentry/solidstart"; +import { createMiddleware } from "@solidjs/start/middleware"; export default createMiddleware({ onBeforeResponse: [ @@ -12,16 +12,16 @@ export default createMiddleware({ // Add your other middleware handlers after `sentryBeforeResponseMiddleware` ], }); -```` +``` If you didn't use a middleware before, don't forget to specify it in `app.config.ts` ```typescript {filename: app.config.ts} -import { defineConfig } from '@solidjs/start/config'; +import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ // ... - middleware: './src/middleware.ts', + middleware: "./src/middleware.ts", }); ``` @@ -66,8 +66,8 @@ Sentry.init({ This tells Sentry to pass trace headers across the following paths: -* Your main API server (where product data comes from) -* Your authentication server (where logins happen) +- Your main API server (where product data comes from) +- Your authentication server (where logins happen) This way, if a customer experiences an error during checkout, or you want to check the performance of a specific endpoint, you can see the complete path their request took across these different services. @@ -81,16 +81,16 @@ Sentry.init({ tracePropagationTargets: [ "https://api.myapp.com", "https://media.myapp.com", - /^\/local-api\// + /^\/local-api\//, ], }); ``` This configuration lets your app track user actions across: -* Your main API server (handles most app functions) -* Your media server (handles images, videos, etc.) -* Any local API endpoints in your app +- Your main API server (handles most app functions) +- Your media server (handles images, videos, etc.) +- Any local API endpoints in your app If your app crashes while a user is uploading a photo, you can trace exactly where the problem occurred - in the app itself, the main API, or the media service. diff --git a/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx b/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx deleted file mode 100644 index bba2907e90464..0000000000000 --- a/platform-includes/feature-flags/evaluation-tracking-index/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -The generic `featureFlagsIntegration` allows you to manually track feature flag evaluations. Read the documentation to learn more. diff --git a/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx b/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx deleted file mode 100644 index c4a235b1ddad3..0000000000000 --- a/platform-includes/feature-flags/integrations/js-featureflags/min-version/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -This integration is available in Sentry SDK **versions 9.31.0 or higher.** diff --git a/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx b/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx deleted file mode 100644 index e54c7a3135529..0000000000000 --- a/platform-includes/getting-started-add-top-level-import/javascript.connect.mdx +++ /dev/null @@ -1,29 +0,0 @@ -```javascript {tabTitle:CommonJS} -// Ensure to require this before requiring any other modules! -require('./instrument.js') - -const connect = require('connect'); -const Sentry = require("@sentry/node"); -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` - -```javascript {tabTitle:ESM} -// Ensure to import this before importing any other modules! -import './instrument.js' - -import connect from 'connect'; -import * as Sentry from "@sentry/node"; -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` diff --git a/platform-includes/getting-started-add-top-level-import/javascript.express.mdx b/platform-includes/getting-started-add-top-level-import/javascript.express.mdx index 4843de736705e..3747f6fd492f5 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.express.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.express.mdx @@ -3,15 +3,10 @@ require('./instrument.js') const express = require("express"); -const Sentry = require("@sentry/node"); const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` @@ -20,14 +15,9 @@ app.listen(3000); import './instrument.js' import express from "express"; -import * as Sentry from "@sentry/node"; const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` diff --git a/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx b/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx index c588a37961fe7..d10287bc4e075 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.fastify.mdx @@ -3,11 +3,8 @@ require('./instrument.js') const Fastify = require("fastify"); -const Sentry = require("@sentry/node"); const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); @@ -18,11 +15,8 @@ app.listen({ port: 3030 }); import './instrument.js' import Fastify from "fastify"; -import * as Sentry from "@sentry/node"; const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); diff --git a/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx b/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx index 2d050160d4794..cba9dc32f4745 100644 --- a/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx +++ b/platform-includes/getting-started-add-top-level-import/javascript.koa.mdx @@ -4,13 +4,10 @@ require('./instrument.js') const Koa = require('koa'); const Router = require('@koa/router'); -const Sentry = require("@sentry/node"); const router = new Router(); const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030); @@ -22,13 +19,10 @@ import './instrument.js' import Koa from 'koa'; import Router from '@koa/router'; -import * as Sentry from "@sentry/node"; const router = new Router(); const app = new Koa(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.listen(3030) diff --git a/platform-includes/getting-started-capture-errors/javascript.express.mdx b/platform-includes/getting-started-capture-errors/javascript.express.mdx new file mode 100644 index 0000000000000..9d86eeb45f304 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.express.mdx @@ -0,0 +1,22 @@ +### Report Unhandled Exceptions + +`expressIntegration` captures errors from your routes and middleware automatically, so you don't need to register a Sentry error handler. 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()`. Return `true` to capture an error or `false` to skip it: + +```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/platform-includes/getting-started-capture-errors/javascript.fastify.mdx b/platform-includes/getting-started-capture-errors/javascript.fastify.mdx new file mode 100644 index 0000000000000..f8b66c63d354f --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.fastify.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`fastifyIntegration` captures errors from your routes and hooks automatically, so you don't need to register a Sentry error handler. Errors with a 3xx or 4xx status code are skipped. To change which errors are captured, use the `shouldHandleError` option. diff --git a/platform-includes/getting-started-capture-errors/javascript.hapi.mdx b/platform-includes/getting-started-capture-errors/javascript.hapi.mdx new file mode 100644 index 0000000000000..d70bebcfdb131 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.hapi.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`hapiIntegration` registers an error handler when your Hapi server starts, so errors are captured automatically. No additional configuration is needed. diff --git a/platform-includes/getting-started-capture-errors/javascript.hono.mdx b/platform-includes/getting-started-capture-errors/javascript.hono.mdx index 806df42b477ef..1ea3d3dfb14a9 100644 --- a/platform-includes/getting-started-capture-errors/javascript.hono.mdx +++ b/platform-includes/getting-started-capture-errors/javascript.hono.mdx @@ -1,3 +1,3 @@ ### Report Unhandled Exceptions -By default, Sentry captures exceptions from Hono's `onError` handler. Errors with a 3xx or 4xx status code are excluded. You can customize this behavior through the `honoIntegration`'s `shouldHandleError` option. +By default, Sentry captures exceptions from Hono's `onError` handler. Errors with a 3xx or 4xx status code are excluded. You can customize this behavior through the `sentry()` middleware's `shouldHandleError` option. diff --git a/platform-includes/getting-started-capture-errors/javascript.koa.mdx b/platform-includes/getting-started-capture-errors/javascript.koa.mdx new file mode 100644 index 0000000000000..948fcf206fe18 --- /dev/null +++ b/platform-includes/getting-started-capture-errors/javascript.koa.mdx @@ -0,0 +1,3 @@ +### Report Unhandled Exceptions + +`koaIntegration` registers an error handler when your Koa app starts, so errors are captured automatically. No additional configuration is needed. diff --git a/platform-includes/getting-started-complete/javascript.astro.mdx b/platform-includes/getting-started-complete/javascript.astro.mdx index 64031453f1e2d..6e359cabaf134 100644 --- a/platform-includes/getting-started-complete/javascript.astro.mdx +++ b/platform-includes/getting-started-complete/javascript.astro.mdx @@ -296,12 +296,6 @@ export default defineConfig({ Create a `sentry.server.config.(ts|js)` file in the root of your project. In this file, import and initialize Sentry for the server: - - -For Astro versions below `3.5.2`, you need to manually add server instrumentation via the Sentry middleware as explained on our APIs page. - - - diff --git a/platform-includes/getting-started-complete/javascript.nuxt.mdx b/platform-includes/getting-started-complete/javascript.nuxt.mdx index 46bb9bfabe540..9ca4d128758db 100644 --- a/platform-includes/getting-started-complete/javascript.nuxt.mdx +++ b/platform-includes/getting-started-complete/javascript.nuxt.mdx @@ -234,16 +234,16 @@ dotenv.config(); -**Sentry's server-side monitoring doesn't work in development mode**. To enable it, you first need to build your application and then load the Sentry server-side config using the `--import` flag when running your application. +The SDK bundles `sentry.server.config.ts` into the Nitro server build and initializes Sentry when the server starts. This works in production and in development mode. -Check out the `--import` CLI flag docs for setup instructions. +To learn more, see [Server-Side Installation](/platforms/javascript/guides/nuxt/install/). -``` +```bash # Start your app after building your project with `nuxi build` -node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +node .output/server/index.mjs ``` @@ -509,11 +509,15 @@ Then update the test page by including a new button that executes a function to -Once you have your test code in place, you need to build your project since Sentry's **server-side monitoring doesn't work in development** mode. + + +Once you have your test code in place, build and run your project. + + -Then start your app and make sure to load Sentry on the server side by explicitly adding the Sentry server config in the build output via{" "} `--import`. +Once you have your test code in place, run your project in production mode (`nuxi build`, then `node .output/server/index.mjs`) or in development mode (`nuxt dev`). @@ -555,7 +559,7 @@ Now's a good time to customize your setup and look into more advanced topics. Ou - If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nuxt/) - Find various support topics in troubleshooting -- Review alternative installation methods +- Learn how the SDK initializes on the server side - [Get support](https://www.sentry.help/en/) diff --git a/platform-includes/getting-started-complete/javascript.remix.mdx b/platform-includes/getting-started-complete/javascript.remix.mdx index 373689d8ec566..5bda03ffc0b23 100644 --- a/platform-includes/getting-started-complete/javascript.remix.mdx +++ b/platform-includes/getting-started-complete/javascript.remix.mdx @@ -186,8 +186,8 @@ Sentry.init({ profileSessionSampleRate: 1.0, // ___PRODUCT_OPTION_END___ profiling - // Optionally capture action formData attributes with errors. - // This requires `sendDefaultPii` set to true as well. + // Optionally limit which action formData fields are captured. + // Without this option, all fields are captured. captureActionFormDataKeys: { key_x: true, key_y: true, @@ -208,8 +208,6 @@ Then run your Remix server using the `--import` command line option and point it ```bash NODE_OPTIONS='--import=./instrument.server.mjs' remix-serve build -# or -NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build ``` @@ -227,10 +225,9 @@ If you use the Express server instead of the built-in Remix server, you can impo -```typescript {filename: server.(mjs|cjs)} +```typescript {filename: server.mjs} // import the Sentry instrumentation file before anything else. import "./instrument.server.mjs"; -// alternatively `require('./instrument.server.cjs')` // ... @@ -253,6 +250,59 @@ const app = express(); +Create a Worker entry file, for example `server.ts` in your project's root folder, and set it as `main` in your wrangler config. + +In this file, instrument your Remix server build with `instrumentBuild` from `@sentry/remix/cloudflare`, pass it to `createRequestHandler`, and wrap the exported handler with `Sentry.withSentry()` from `@sentry/cloudflare`. `withSentry` isolates each request, so scope data like tags and users stays on the request that set it. + + + +Don't also wrap `createRequestHandler` with `makeWrappedCreateRequestHandler`. Combined with `withSentry`, it reports every request twice, as two `http.server` transactions in two different traces. + + + + + + +```typescript {filename:server.ts} +import { createRequestHandler } from "@remix-run/cloudflare"; +import * as Sentry from "@sentry/cloudflare"; +import { instrumentBuild } from "@sentry/remix/cloudflare"; +// The server build produced by `remix vite:build` +import * as remixBuild from "./build/server/index.js"; + +const handleRequest = createRequestHandler(instrumentBuild(remixBuild)); + +export default Sentry.withSentry( + (env) => ({ + dsn: "___PUBLIC_DSN___", + // ___PRODUCT_OPTION_START___ performance + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for tracing. + // We recommend adjusting this value in production + // Learn more at + // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + tracesSampleRate: 1.0, + // ___PRODUCT_OPTION_END___ performance + }), + { + async fetch(request, env, ctx) { + return handleRequest(request, { env, ctx }); + }, + } +); +``` + + + + + + + + + + + @@ -276,8 +326,8 @@ export const onRequest = [ tracesSampleRate: 1.0, // ___PRODUCT_OPTION_END___ performance - // Optionally capture action formData attributes with errors. - // This requires `sendDefaultPii` set to true as well. + // Optionally limit which action formData fields are captured. + // Without this option, all fields are captured. captureActionFormDataKeys: { key_x: true, key_y: true, @@ -291,15 +341,22 @@ export const onRequest = [ + + ### Capture Server-Side Errors + + -To automatically capture server-side errors, instrument the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function in your server entry point (`entry.server.tsx`). You can wrap your custom error handler with `wrapHandleErrorWithSentry` or directly use `sentryHandleError`: +To automatically capture server-side errors, export a [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function from your server entry point (`entry.server.tsx`). Choose one of the two options: + +- Wrap your custom error handler with `wrapHandleErrorWithSentry`. +- Use `sentryHandleError` directly if you don't have a custom error handler. @@ -310,7 +367,7 @@ Sentry's Remix SDK automatically records your [`action`](https://remix.run/docs/ -```typescript {filename: entry.server.tsx} +```typescript {tabTitle:Custom Error Handler} {filename: entry.server.tsx} import * as Sentry from "@sentry/remix"; export const handleError = Sentry.wrapHandleErrorWithSentry( @@ -318,8 +375,11 @@ export const handleError = Sentry.wrapHandleErrorWithSentry( // Custom handleError implementation } ); +``` + +```typescript {tabTitle:Default Error Handler} {filename: entry.server.tsx} +import * as Sentry from "@sentry/remix"; -// Alternative: Use the Sentry utility function if you don't need to wrap a custom function export const handleError = Sentry.sentryHandleError; ``` @@ -327,6 +387,37 @@ export const handleError = Sentry.sentryHandleError; + + + + + + + + +To automatically capture server-side errors, export `sentryHandleError` as the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function from your server entry point (`entry.server.tsx`). Without this export, Remix handles errors thrown in loaders and actions itself, and Sentry doesn't receive them. + + + +Import from `@sentry/remix/cloudflare`, not from `@sentry/remix`. In a Cloudflare server build, `sentryHandleError` from `@sentry/remix` is `undefined`, and no errors are captured. + + + + + + +```typescript {filename: entry.server.tsx} +import { sentryHandleError } from "@sentry/remix/cloudflare"; + +export const handleError = sentryHandleError; +``` + + + + + + + ### Configure Cloudflare for Sentry @@ -338,13 +429,116 @@ export const handleError = Sentry.sentryHandleError; +### Configure Vite + + + + + + + +Add `sentryRemixVitePlugin` from `@sentry/remix/vite` to your `vite.config.ts`. The plugin: + +- Parameterizes client-side transaction names with your route patterns, for example `/users/:id`. +- Instruments supported server-side dependencies, such as database clients, at build time. + + + +You can skip this step. Client-side transaction names then use the URL instead of the route pattern. + + + + + + +```typescript {filename:vite.config.ts} {2, 10} +import { vitePlugin as remix } from "@remix-run/dev"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + remix({ + // ... your Remix plugin options + }), + sentryRemixVitePlugin(), + ], +}); +``` + + + + + + + + + + + + + +Add two Sentry plugins to your `vite.config.ts`, next to the Remix plugin: + +- `sentryRemixVitePlugin` from `@sentry/remix/vite` parameterizes transaction names with your route patterns, for example `/users/:id`. +- `sentryCloudflareVitePlugin` from `@sentry/cloudflare/vite` instruments supported bundled dependencies at build time, so you get spans for database clients like `mysql`. Without it, database calls produce no spans and no warning. + +Set `ssr.target` to `webworker` and bundle the Sentry packages and any database client you want traced with `ssr.noExternal`. Setting `noExternal: true` bundles every dependency, which works too. + + + + +```typescript {filename:vite.config.ts} {2-3, 11-12, 14-17} +import { vitePlugin as remix } from "@remix-run/dev"; +import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; + +export default defineConfig({ + plugins: [ + remix({ + // ... your Remix plugin options + }), + sentryRemixVitePlugin(), + sentryCloudflareVitePlugin(), + ], + ssr: { + target: "webworker", + noExternal: ["mysql", /^@sentry\//, "@opentelemetry/api"], + }, +}); +``` + + + + + + + +Build your app with `remix vite:build`. Under Vite 6, a plain `vite build` only builds the client and skips `build/server`, without an error. + + + + +```bash +npx remix vite:build +``` + + + + + + + ### Add Readable Stack Traces With Source Maps (Optional) -To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your `vite.config.ts` file: +To upload source maps for clear error stack traces, pass your Sentry organization, project, and auth token to `sentryRemixVitePlugin` from the previous step. It injects debug IDs, uploads the source maps during your production build, and deletes them from your build output afterwards. + +The plugin also turns on hidden source maps for you, unless you set `build.sourcemap` yourself. @@ -356,30 +550,26 @@ alternative setup options. -```javascript {filename:vite.config.ts} {3, 10-17,20-23} -import { defineConfig } from "vite"; +```javascript {filename:vite.config.ts} {10-16} import { vitePlugin as remix } from "@remix-run/dev"; -import { sentryVitePlugin } from "@sentry/vite-plugin"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; export default defineConfig({ plugins: [ remix({ // ... your Remix plugin options }), - sentryVitePlugin({ - // If you use .sentryclirc or environment variables, + sentryRemixVitePlugin({ + // If you use environment variables, // you don't need to specify these options org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", // store your auth token in an environment variable authToken: process.env.SENTRY_AUTH_TOKEN, }), + // ... other plugins ], - - build: { - sourcemap: "hidden", - // ... rest of your Vite build options - }, }); ``` diff --git a/platform-includes/getting-started-complete/javascript.sveltekit.mdx b/platform-includes/getting-started-complete/javascript.sveltekit.mdx index 8fc48c3b2cd35..77369e45d7452 100644 --- a/platform-includes/getting-started-complete/javascript.sveltekit.mdx +++ b/platform-includes/getting-started-complete/javascript.sveltekit.mdx @@ -362,7 +362,7 @@ Add the `sentrySvelteKit` plugin **before** `sveltekit` in your `vite.config.(js ```javascript {filename:vite.config.(js|ts)} {2,6} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; import { defineConfig } from "vite"; export default defineConfig({ @@ -400,7 +400,7 @@ To upload source maps for clear error stack traces, add your Sentry auth token, ```javascript {filename:vite.config.(js|ts)} {6-13} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -455,7 +455,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ diff --git a/platform-includes/getting-started-config/javascript.node.mdx b/platform-includes/getting-started-config/javascript.node.mdx index c66e3af06ee26..334bd8776680e 100644 --- a/platform-includes/getting-started-config/javascript.node.mdx +++ b/platform-includes/getting-started-config/javascript.node.mdx @@ -4,10 +4,8 @@ const Sentry = require("@sentry/node"); const { nodeProfilingIntegration } = require("@sentry/profiling-node"); // ___PRODUCT_OPTION_END___ profiling -// Ensure to call this before requiring any other modules! Sentry.init({ dsn: "___PUBLIC_DSN___", - // ___PRODUCT_OPTION_START___ profiling integrations: [ diff --git a/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx b/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx new file mode 100644 index 0000000000000..a5db4c83c07c3 --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.aws-lambda__v10.x.mdx @@ -0,0 +1,32 @@ + + + + +When you set the `dataCollection` option, you opt into the SDK's new data collection behavior, which is the default in version 11. +The SDK then sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. +This will give you rich debugging context. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {3-8} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: + // https://docs.sentry.io/platforms/javascript/guides/aws-lambda/configuration/options/#dataCollection + // userInfo: false, + // httpBodies: [], + }, +}); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.eve.mdx b/platform-includes/getting-started-data-collection/javascript.eve.mdx new file mode 100644 index 0000000000000..5b5abf0dca45e --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.eve.mdx @@ -0,0 +1,30 @@ + + + + +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```typescript {filename:agent/instrumentation/sentry.ts} {4-6} +export default defineInstrumentation( + Sentry.eveInstrumentation({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, + }) +); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.mastra.mdx b/platform-includes/getting-started-data-collection/javascript.mastra.mdx new file mode 100644 index 0000000000000..521f25e282159 --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.mastra.mdx @@ -0,0 +1,28 @@ + + + + +By default, the SDK sends the inputs and outputs of your LLM and tool calls, such as prompts, responses, and tool arguments. +This will give you rich debugging context. Review the data your agent handles before you deploy to production. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {filename:src/mastra/public/instrument.mjs} {3-5} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + genAI: { inputs: false, outputs: false }, + }, +}); +``` + + + + diff --git a/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx b/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx new file mode 100644 index 0000000000000..025b60e9029ea --- /dev/null +++ b/platform-includes/getting-started-data-collection/javascript.nuxt__v10.x.mdx @@ -0,0 +1,32 @@ + + + + +When you set the `dataCollection` option, you opt into the SDK's new data collection behavior, which is the default in version 11. +The SDK then sends user identity data (IP address, ID, and similar) and other data like HTTP bodies and URL query parameters. +This will give you rich debugging context. + +The SDK always filters sensitive values whose keys match a built-in denylist, such as `auth` or `password`, and sends `[Filtered]` instead. + +To send less data, turn off the categories you don't need in the `dataCollection` option. +For the full list of categories and their defaults, see the `dataCollection` options. + + + + + +```javascript {3-8} +Sentry.init({ + dsn: "___PUBLIC_DSN___", + dataCollection: { + // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: + // https://docs.sentry.io/platforms/javascript/guides/nuxt/configuration/options/#dataCollection + // userInfo: false, + // httpBodies: [], + }, +}); +``` + + + + diff --git a/platform-includes/getting-started-node/javascript.mdx b/platform-includes/getting-started-node/javascript.mdx index f3feb0922de7d..81903833422b8 100644 --- a/platform-includes/getting-started-node/javascript.mdx +++ b/platform-includes/getting-started-node/javascript.mdx @@ -33,71 +33,21 @@ Run the command for your preferred package manager to add the Sentry SDK to your ### Initialize the Sentry SDK - - - - To import and initialize Sentry, create a file named `instrument.(js|mjs)` in the root directory of your project and add the following code: - - - - - - - -### Apply Instrumentation to Your App - - - -Import `instrument.js` before any other modules to ensure Sentry initializes early. If you initialize later, auto-instrumentation and modules like database monitoring, agent tracing, tracing may not work. - - - - - -The method for applying instrumentation depends on whether your application uses CommonJS (CJS) or ECMAScript Modules (ESM). If you're unsure which system you're using or if you're looking for alternative installation methods, see here. - - - -#### CommonJS - - - - +Then, use the [--import](https://nodejs.org/api/cli.html#--importmodule) command line option and point it to your `instrument.(js|mjs)` file to load the module before the application starts: -Require the `instrument.js` file before any other modules: - - - - - - - - - - -#### ESM - - - - - -When running your application in ESM mode, use the [--import](https://nodejs.org/api/cli.html#--importmodule) command line option and point it to `instrument.mjs` to load the module before the application starts: - - - +```bash {tabTitle:CommonJS} +node --import ./instrument.js app.js +``` -```bash -# Note: This is only available for Node v18.19.0 onwards. +```bash {tabTitle:ESM} node --import ./instrument.mjs app.mjs ``` - - - +If you are using a bundler like vite, you can also follow the bundler setup docs instead. diff --git a/platform-includes/getting-started-prerequisites/javascript.deno.mdx b/platform-includes/getting-started-prerequisites/javascript.deno.mdx index ceb8920ff89a1..4709c0f194eb2 100644 --- a/platform-includes/getting-started-prerequisites/javascript.deno.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.deno.mdx @@ -4,4 +4,4 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Deno version >= `2.0.0` +- Deno version >= `2.8.3` diff --git a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx index bcb8b05780126..5b4b58a004bbc 100644 --- a/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.nextjs.mdx @@ -2,5 +2,6 @@ You need: -- A Next.js application +- A Next.js application on version 14 or higher +- Node.js 20.19.0 or higher - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) diff --git a/platform-includes/getting-started-prerequisites/javascript.node.mdx b/platform-includes/getting-started-prerequisites/javascript.node.mdx index 76c8644590648..921938957f024 100644 --- a/platform-includes/getting-started-prerequisites/javascript.node.mdx +++ b/platform-includes/getting-started-prerequisites/javascript.node.mdx @@ -4,13 +4,4 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- Node version `18.0.0` or above (>= `19.9.0` or `18.19.0` recommended) - - - The required Node version will increase in the next major release of the SDK (v11) to support features that rely on [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel). - - - We strongly recommend upgrading to at least Node `18.19.0` or `19.9.0` to get the best support. - - While we may add features relying on `TracingChannel` in v10.x releases, they will have backwards compatibility for older Node versions. - - See the following [issue on GitHub](https://github.com/getsentry/sentry-javascript/issues/17585) for more details. - +- Node version `20.19.0` or above. Node.js 22 needs `22.12` or higher, while Node.js 23 needs `23.2` or higher (`>=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0`). diff --git a/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx b/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx new file mode 100644 index 0000000000000..2d7cc44809687 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.nuxt__v10.x.mdx @@ -0,0 +1,35 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- Nuxt version `3.7.0` or above (`3.14.0`+ recommended) + + + Add the following overrides: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "ofetch": "^1.4.0", + "@vercel/nft": "^0.27.4" + } +} +``` + + diff --git a/platform-includes/getting-started-prerequisites/javascript.react-router.mdx b/platform-includes/getting-started-prerequisites/javascript.react-router.mdx new file mode 100644 index 0000000000000..5de5e376f5010 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.react-router.mdx @@ -0,0 +1,7 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- React Router version `7.15.0` or above (framework mode) diff --git a/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx new file mode 100644 index 0000000000000..2aad75db297c4 --- /dev/null +++ b/platform-includes/getting-started-prerequisites/javascript.solidstart.mdx @@ -0,0 +1,15 @@ +## Prerequisites + +You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- Your application up and running +- SolidStart version `1.0.0`+ or `2.0.0`+ + + + +SolidStart 2 dropped vinxi and `app.config.ts`, so the two versions are set up differently. Check the `@solidjs/start` version in your `package.json`; a new project installs SolidStart 2. + +Where this guide shows **SolidStart 2** and **SolidStart 1** tabs, pick the one that matches your version. The installation methods apply to SolidStart 1 only. + + diff --git a/platform-includes/getting-started-run/javascript.mdx b/platform-includes/getting-started-run/javascript.mdx index 3b891ce87d7a1..f9859c4ffc7e7 100644 --- a/platform-includes/getting-started-run/javascript.mdx +++ b/platform-includes/getting-started-run/javascript.mdx @@ -1,14 +1,13 @@ ```bash # If you are using CommonJS (CJS) -node --require ./instrument.js app.js +node --import ./instrument.js app.js # If you are using ECMAScript Modules (ESM) -# Note: This is only available for Node v18.19.0 onwards. node --import ./instrument.mjs app.mjs ``` -If you can't run node with `--require` or `--import`, import the Sentry Initialization file directly. +If you can't run node with `--import`, import the Sentry Initialization file directly. diff --git a/platform-includes/getting-started-use/javascript.connect.mdx b/platform-includes/getting-started-use/javascript.connect.mdx deleted file mode 100644 index 4d9ae89376dcb..0000000000000 --- a/platform-includes/getting-started-use/javascript.connect.mdx +++ /dev/null @@ -1,33 +0,0 @@ -```javascript {tabTitle:CommonJS} -// Require this first! -require("./instrument"); - -// Now require other modules -const connect = require("connect"); -const Sentry = require("@sentry/node"); - -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` - -```javascript {tabTitle:ESM} -// Import this first! -import "./instrument"; - -// Now import other modules -import connect from "connect"; -import * as Sentry from "@sentry/node"; - -const app = connect(); - -Sentry.setupConnectErrorHandler(app); - -// Add your routes, etc. - -app.listen(3030); -``` diff --git a/platform-includes/getting-started-use/javascript.express.mdx b/platform-includes/getting-started-use/javascript.express.mdx index 5e13b651c0bf3..e738883598f50 100644 --- a/platform-includes/getting-started-use/javascript.express.mdx +++ b/platform-includes/getting-started-use/javascript.express.mdx @@ -4,34 +4,24 @@ require("./instrument"); // Now require other modules const express = require("express"); -const Sentry = require("@sentry/node"); const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import express from "express"; -import * as Sentry from "@sentry/node"; const app = express(); // Add your routes, etc. -// Add this after all routes, -// but before any and other error-handling middlewares are defined -Sentry.setupExpressErrorHandler(app); - app.listen(3000); ``` diff --git a/platform-includes/getting-started-use/javascript.fastify.mdx b/platform-includes/getting-started-use/javascript.fastify.mdx index 2f9c72bf25bec..a7e5092519192 100644 --- a/platform-includes/getting-started-use/javascript.fastify.mdx +++ b/platform-includes/getting-started-use/javascript.fastify.mdx @@ -4,12 +4,9 @@ require("./instrument"); // Now require other modules const Fastify = require("fastify"); -const Sentry = require("@sentry/node"); const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); @@ -17,16 +14,13 @@ app.listen({ port: 3030 }); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules import Fastify from "fastify"; -import * as Sentry from "@sentry/node"; const app = Fastify(); -Sentry.setupFastifyErrorHandler(app); - // Add your routes, etc. app.listen({ port: 3030 }); diff --git a/platform-includes/getting-started-use/javascript.hapi.mdx b/platform-includes/getting-started-use/javascript.hapi.mdx index bfbdfbbe9deab..652945b1f78cb 100644 --- a/platform-includes/getting-started-use/javascript.hapi.mdx +++ b/platform-includes/getting-started-use/javascript.hapi.mdx @@ -3,7 +3,6 @@ require("./instrument"); // Now require other modules -const Sentry = require("@sentry/node"); const Hapi = require('@hapi/hapi'); const init = async () => { @@ -14,8 +13,6 @@ const init = async () => { // All your routes etc. - await Sentry.setupHapiErrorHandler(server); - await server.start(); console.log('Server running on %s', server.info.uri); }; @@ -25,10 +22,9 @@ init(); ```javascript {tabTitle:ESM} // Import this first! -import "./instrument"; +import "./instrument.mjs"; // Now import other modules -import * as Sentry from "@sentry/node"; import Hapi from "@hapi/hapi"; const init = async () => { @@ -39,8 +35,6 @@ const init = async () => { // All your routes etc. - await Sentry.setupHapiErrorHandler(server); - await server.start(); }; diff --git a/platform-includes/getting-started-use/javascript.koa.mdx b/platform-includes/getting-started-use/javascript.koa.mdx index 64f754d8834c4..6f1f0eac33262 100644 --- a/platform-includes/getting-started-use/javascript.koa.mdx +++ b/platform-includes/getting-started-use/javascript.koa.mdx @@ -5,13 +5,10 @@ require("./instrument"); // Now require other modules const Koa = require("koa"); const Router = require("@koa/router"); -const Sentry = require("@sentry/node"); const app = new Koa(); const router = new Router(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.use(router.routes()); @@ -21,19 +18,14 @@ app.listen(3030); ``` ```javascript {tabTitle:ESM} -// Import this first! -import "./instrument"; - -// Now import other modules +// Start with `node --import ./instrument.mjs app.mjs`. A top-level +// import of the instrument file loses Koa's spans and route names. import Koa from "koa"; import Router from "@koa/router"; -import * as Sentry from "@sentry/node"; const app = new Koa(); const router = new Router(); -Sentry.setupKoaErrorHandler(app); - // Add your routes, etc. app.use(router.routes()); diff --git a/platform-includes/getting-started-verify/javascript.connect.mdx b/platform-includes/getting-started-verify/javascript.connect.mdx deleted file mode 100644 index 7449938a9aa41..0000000000000 --- a/platform-includes/getting-started-verify/javascript.connect.mdx +++ /dev/null @@ -1,62 +0,0 @@ -### Issues - - - - - -First, let's make sure Sentry is correctly capturing errors and creating issues in your project. Add the following code snippet to your main application file; it defines a route that will deliberately trigger an error when called: - - - - -```javascript -app.use("/debug-sentry", (req, res) => { - throw new Error("My first Sentry error!"); -}); -``` - - - - - - - -### Tracing - - - - - -To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes to execute your code: - - - - -```javascript -app.use("/debug-sentry", async (req, res) => { - await Sentry.startSpan( - { - op: "test", - name: "My First Test Transaction", - }, - async () => { - await new Promise((resolve) => setTimeout(resolve, 100)); - throw new Error("My first Sentry error!"); - } - ); -}); -``` - - - - - - - - - - - - - - diff --git a/platform-includes/metrics/options/javascript.mdx b/platform-includes/metrics/options/javascript.mdx index 08c7a4247bed3..2f34ab3ee2b8a 100644 --- a/platform-includes/metrics/options/javascript.mdx +++ b/platform-includes/metrics/options/javascript.mdx @@ -37,7 +37,12 @@ Sentry.init({ ### Disable Metrics -Set `enableMetrics: false` to disable metrics collection entirely. +Metrics are only captured when you call `Sentry.metrics.*`, so there is no option to turn them on or off. To stop sending metrics without removing those calls, return `null` from `beforeSendMetric`. + + + On SDK versions below `11.0.0`, set `enableMetrics: false` in your + `Sentry.init` to disable metrics instead. + ### Flush Metrics @@ -47,10 +52,10 @@ Metrics are buffered and sent periodically. Use this snippet to flush immediatel ```javascript -// Disable metrics +// Drop all metrics Sentry.init({ dsn: "___PUBLIC_DSN___", - enableMetrics: false, + beforeSendMetric: () => null, }); // Flush all pending metrics diff --git a/platform-includes/metrics/requirements/javascript.mdx b/platform-includes/metrics/requirements/javascript.mdx index a7404ef7f43db..f15b9be3c6c56 100644 --- a/platform-includes/metrics/requirements/javascript.mdx +++ b/platform-includes/metrics/requirements/javascript.mdx @@ -1,3 +1,9 @@ Metrics are supported in all Sentry JavaScript SDKs version `10.25.0` and above. Make sure you have the SDK set up before proceeding. + + + +Metrics are also supported via [CDN bundles and the Loader Script](/platforms/javascript/install/loader/). Use a bundle that includes metrics, such as `bundle.logs.metrics.min.js`. On other bundles, `Sentry.metrics.*` calls are a no-op that only warns when `debug` is enabled. + + diff --git a/platform-includes/metrics/usage/javascript.mdx b/platform-includes/metrics/usage/javascript.mdx index 2743757f8af70..a70fa09f78a87 100644 --- a/platform-includes/metrics/usage/javascript.mdx +++ b/platform-includes/metrics/usage/javascript.mdx @@ -10,7 +10,7 @@ | `gauge` | Current values (queue depth, connections) | | `distribution` | Value ranges (response times, payload sizes) | -No setup required beyond SDK initialization. +No setup required beyond SDK initialization. Metrics are captured whenever you call `Sentry.metrics.*`. diff --git a/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx b/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx deleted file mode 100644 index 13c630acb863d..0000000000000 --- a/platform-includes/migration/javascript-v8/important-changes/javascript.connect.mdx +++ /dev/null @@ -1,166 +0,0 @@ -### Supported versions - -Sentry Node SDK `8.x` supports Node `14.18.0` or higher - -If you need to support older versions of Node.js, please use Sentry Node SDK `7.x`. - -### Updated SDK initialization - -With 8.x, @sentry/node has been completely overhauled. It is now powered by [OpenTelemetry](https://opentelemetry.io/) under the hood. You do not need to know or understand what OpenTelemetry is in order to use Sentry. We set up OpenTelemetry under the hood. If you use OpenTelemetry-native APIs to start spans, Sentry will pick up everything automatically. - -Here's an example of instrumentating a Connect application with Sentry Node SDK `8.x`: - -```javascript {tabTitle:CommonJS} -require("./instrument"); -const connect = require("connect"); -const Sentry = require("@sentry/node"); -const app = connect(); - -// Add routes etc. here - -Sentry.setupConnectErrorHandler(app); - -app.listen(3000); -``` - -```javascript {tabTitle:ESM} -import "./instrument"; -import connect from "connect"; -import * as Sentry from "@sentry/node"; -const app = connect(); - -// Add your routes, etc. here - -Sentry.setupConnectErrorHandler(app); - -app.listen(3030); -``` - -To migrate your Connect app to Sentry Node SDK `8.x`, you need to make the following changes: - -1. Create an external file called `instrument.js` and move your `Sentry.init` call to it. - -Due to the way that auto instrumentation works in `8.x` of the Sentry Node SDK, it is required that you initialize Sentry before you require or import any other package. Any package that is required/imported before Sentry is initialized may not be correctly auto-instrumented. - -```JavaScript {tabTitle:CommonJS} {filename: instrument.js} -const Sentry = require('@sentry/node'); - -Sentry.init({ - // ... -}); -``` - -```JavaScript diff {tabTitle:ESM} {filename: instrument.mjs} -import * as Sentry from "@sentry/node"; - -Sentry.init({ - // ... -}); -``` - -2. Remove any performance related integrations - -All performance auto-instrumentation will be automatically enabled if the package is found. You do not need to add any integration yourself, and `autoDiscoverNodePerformanceMonitoringIntegrations()` has also been removed. This means you can remove all custom `requestHandler` and `tracingMiddleware` Sentry code. - -We now support the following integrations out of the box with 0 configuration: - -- `httpIntegration`: Automatically instruments Node http and https standard libraries -- `nativeNodeFetchIntegration`: Automatically instruments top level fetch and undici -- `koaIntegration`: Automatically instruments Koa -- `graphqlIntegration`: Automatically instruments GraphQL -- `mongoIntegration`: Automatically instruments MongoDB -- `mongooseIntegration`: Automatically instruments Mongoose -- `mysqlIntegration`: Automatically instruments MySQL -- `mysql2Integration`: Automatically instruments MySQL2 -- `postgresIntegration`: Automatically instruments PostgreSQL - -3. Require `instrument.js` before any other module in your application - -```JavaScript diff {tabTitle:CommonJS} -+require('./instrument'); - const connect = require('connect'); - const Sentry = require('@sentry/node'); - const app = connect(); -``` - -```JavaScript diff {tabTitle:ESM} -+import './instrument'; - import connect from 'connect'; - import * as Sentry from "@sentry/node"; - const app = connect(); -``` - - - -If you run your application with ESM, you need to import the Sentry Initialization file before importing any other modules. See running Sentry with ESM. -If you are unsure how you are running your application, see Installation Methods for more information. - - - -4. Add Sentry error handler - -Previously you had to use `Sentry.Handlers.requestHandler()`, `Sentry.Handlers.tracingHandler()`, and `Sentry.Handlers.errorHandler()` to add Sentry instrumentation to your Connect app. In `8.x`, you only need to use `Sentry.setupConnectErrorHandler(app)`, you can remove all other handlers. - -```JavaScript diff {tabTitle:CommonJS} - require('./instrument'); - const connect = require('connect'); - const Sentry = require('@sentry/node'); - const app = connect(); - --app.use(Sentry.Handlers.requestHandler()); --app.use(Sentry.Handlers.tracingHandler()); - -// add routes etc. here - --app.use(Sentry.Handlers.errorHandler()); -+Sentry.setupConnectErrorHandler(app); - - app.listen(3000); -``` - -```JavaScript diff {tabTitle:ESM} - import './instrument'; - import connect from 'connect'; - import * as Sentry from "@sentry/node"; - const app = connect(); - --app.use(Sentry.Handlers.requestHandler()); --app.use(Sentry.Handlers.tracingHandler()); - -// add routes etc. here - --app.use(Sentry.Handlers.errorHandler()); -+Sentry.setupConnectErrorHandler(app); - - app.listen(3000); -``` - -### Ensure Request Isolation - -For any non-HTTP scenarios (e.g. websockets or a scheduled job), you'll have to manually ensure request isolation by wrapping the function with `Sentry.withIsolationScope()`. Previously we recommended you use `Sentry.runWithAsyncContext` for this but that has been removed in `8.x`. - -```javascript {tabTitle:CommonJS} -const Sentry = require("@sentry/node"); - -function myScheduledJob() { - return Sentry.withIsolationScope(async () => { - await doSomething(); - await doSomethingElse(); - return { status: "DONE" }; - }); -} -``` - -```javascript {tabTitle:ESM} -import * as Sentry from "@sentry/node"; - -function myScheduledJob() { - return Sentry.withIsolationScope(async () => { - await doSomething(); - await doSomethingElse(); - return { status: "DONE" }; - }); -} -``` - -This way, anything happening inside of this function will be isolated, even if they run concurrently. diff --git a/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx b/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx deleted file mode 100644 index 4f7f6ab6537eb..0000000000000 --- a/platform-includes/migration/javascript-v8/integrations-package-removal/javascript.connect.mdx +++ /dev/null @@ -1,14 +0,0 @@ -### Removal of `@sentry/integrations` package - -`@sentry/integrations` has been removed and will no longer be published. We moved pluggable integrations from their own package (`@sentry/integrations`) to `@sentry/node`. In addition they are now functions instead of classes. - -Integrations that are now exported from `@sentry/node` for server-side init: - -- `captureConsoleIntegration` (`CaptureConsole`) -- `debugIntegration` (`Debug`) -- `extraErrorDataIntegration` (`ExtraErrorData`) -- `rewriteFramesIntegration` (`RewriteFrames`) -- `sessionTimingIntegration` (`SessionTiming`) -- `dedupeIntegration` (`Dedupe`) - Note: enabled by default, not pluggable - -The `Transaction` integration has been removed from `@sentry/integrations`. There is no replacement API. diff --git a/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx b/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx deleted file mode 100644 index 1654e8dd1f386..0000000000000 --- a/platform-includes/migration/javascript-v8/intro/javascript.connect.mdx +++ /dev/null @@ -1 +0,0 @@ -`8.x` simplifies Sentry Node SDK initialization and leverages Node.js OpenTelemetry instrumentation for tracing. diff --git a/platform-includes/performance/add-spans-example/javascript.mdx b/platform-includes/performance/add-spans-example/javascript.mdx index 4092a0bf335c7..800967ac2397f 100644 --- a/platform-includes/performance/add-spans-example/javascript.mdx +++ b/platform-includes/performance/add-spans-example/javascript.mdx @@ -45,7 +45,7 @@ function processItem(item) { http.get(`/items/${item.id}`, (response) => { response.on("data", () => {}); response.on("end", () => { - span.setTag("http.status_code", response.statusCode); + span.setAttribute("http.response.status_code", response.statusCode); span.setAttribute( "http.foobarsessionid", getFoobarSessionid(response) @@ -72,7 +72,7 @@ function processItem(item) { const response = await fetch("/items/${item.id}"); const json = await response.json(); - span.setTag("http.status_code", response.statusCode); + span.setAttribute("http.response.status_code", response.status); span.setAttribute("http.foobarsessionid", getFoobarSessionid(response)); } ); diff --git a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx index f1238fabd3b94..99ad8cd43b12e 100644 --- a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx +++ b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx @@ -19,7 +19,7 @@ const client = Sentry.init({ let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan(client, { name: window.location.pathname, attributes: { - [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "url", + "sentry.segment.name.source": "url", }, }); @@ -29,14 +29,14 @@ myRouter.on("routeChange", (route) => { // After that, each route change should trigger a navigation span (which will automatically finish the previous one) if (pageLoadSpan) { pageLoadSpan.updateName(route.name); - pageLoadSpan.setAttribute(Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, "route"); + pageLoadSpan.setAttribute("sentry.segment.name.source", "route"); pageLoadSpan = undefined; } else { Sentry.startBrowserTracingNavigationSpan(client, { op: "navigation", name: route.name, // or what the name of the span should be attributes: { - [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "route", + "sentry.segment.name.source": "route", }, }); } diff --git a/platform-includes/performance/enable-inp-example/javascript.mdx b/platform-includes/performance/enable-inp-example/javascript.mdx index 9182861cab98e..7c64af2750285 100644 --- a/platform-includes/performance/enable-inp-example/javascript.mdx +++ b/platform-includes/performance/enable-inp-example/javascript.mdx @@ -3,7 +3,9 @@ Sentry.init({ // ... integrations: [ Sentry.browserTracingIntegration({ - enableInp: true, + webVitals: { + ignore: ["inp"], + }, }), ], }); diff --git a/platform-includes/performance/enable-stream-mode/javascript.bun.mdx b/platform-includes/performance/enable-stream-mode/javascript.bun.mdx index 50fcd0d395b0d..3b0ace37a99d4 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.bun.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.bun.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx b/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx index baaa88c96e41c..4fd10ed1d10a5 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.cloudflare.mdx @@ -5,7 +5,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -16,7 +16,7 @@ import * as Sentry from "@sentry/cloudflare"; export const onRequest = [ Sentry.sentryPagesPlugin((context) => ({ dsn: "___PUBLIC_DSN___", - tracesSampleRate: 0.2 + tracesSampleRate: 0.2, // enables stream mode traceLifecycle: "stream", })), @@ -32,7 +32,7 @@ export const onRequest = [ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -44,7 +44,7 @@ export default Sentry.withSentry( (env: Env) => ({ dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, - // Enables stream mode + // enables stream mode traceLifecycle: "stream", }), { @@ -59,4 +59,4 @@ export default Sentry.withSentry( -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.deno.mdx b/platform-includes/performance/enable-stream-mode/javascript.deno.mdx index 297c972e1deaf..c20aa6d9137b8 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.deno.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.deno.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -21,4 +21,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx b/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx index dd0e571319c4b..5e042cd319f7b 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.elysia.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx b/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx index fc3c31c729469..cc2162172b45a 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.gcp-functions.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.hono.mdx b/platform-includes/performance/enable-stream-mode/javascript.hono.mdx index 951546caad069..d60bc5ef99b21 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.hono.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.hono.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -48,4 +48,4 @@ app.use( -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx b/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx index 8faa6f11ac1b2..af1a4ef92631c 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nestjs.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx b/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx index 99ba2c2facc47..70b4ea075e854 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nextjs.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK in your server, client, and edge config files: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK in your server, client, and edge config files: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx b/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx index bf70f69d9b3cc..a421fc85e6f38 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.nitro.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -22,4 +22,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/enable-stream-mode/javascript.node.mdx b/platform-includes/performance/enable-stream-mode/javascript.node.mdx index 053c862d60073..f4bf41c9f9d6d 100644 --- a/platform-includes/performance/enable-stream-mode/javascript.node.mdx +++ b/platform-includes/performance/enable-stream-mode/javascript.node.mdx @@ -2,7 +2,7 @@ -Opt in by setting the `traceLifecycle` option to `'stream'` when initializing the SDK: +Stream mode is enabled by default in v11. On older versions, set the `traceLifecycle` option to `'stream'` explicitly when initializing the SDK: @@ -33,4 +33,4 @@ Sentry.init({ -To revert to transaction mode, set `traceLifecycle` to `'static'` (the default) or remove the option entirely. +To use transaction mode instead, set `traceLifecycle` to `'static'`. Transaction mode exists for backwards compatibility and will be removed in a future major version. diff --git a/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.bun__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.mdx b/platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/error-monitoring-only/javascript__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx similarity index 95% rename from platform-includes/performance/opentelemetry-setup/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx index 4927978b8dd07..8a9c210fb0eba 100644 --- a/platform-includes/performance/opentelemetry-setup/javascript.bun.mdx +++ b/platform-includes/performance/opentelemetry-setup/javascript.bun__v10.x.mdx @@ -83,4 +83,4 @@ sdk.start(); validateOpenTelemetrySetup(); ``` -Make sure that all [Required OpenTelemetry Instrumentation](./#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. +Make sure that all [Required OpenTelemetry Instrumentation](#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. diff --git a/platform-includes/performance/opentelemetry-setup/javascript.mdx b/platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx similarity index 94% rename from platform-includes/performance/opentelemetry-setup/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx index 8e89e864d6d5b..70515a91aa4d2 100644 --- a/platform-includes/performance/opentelemetry-setup/javascript.mdx +++ b/platform-includes/performance/opentelemetry-setup/javascript__v10.x.mdx @@ -75,4 +75,4 @@ sdk.start(); Sentry.validateOpenTelemetrySetup(); ``` -Make sure that all [Required OpenTelemetry Instrumentation](./#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. +Make sure that all [Required OpenTelemetry Instrumentation](#required-instrumentation) is set up correctly. Otherwise, the Sentry SDK may not work as expected. diff --git a/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun.mdx b/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun.mdx rename to platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.bun__v10.x.mdx diff --git a/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.mdx b/platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript__v10.x.mdx similarity index 100% rename from platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript.mdx rename to platform-includes/performance/opentelemetry-setup/with-custom-sampler/javascript__v10.x.mdx diff --git a/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx b/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx index cb6da7d5b4f7f..e73e949efbd3d 100644 --- a/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx +++ b/platform-includes/sourcemaps/legacy-troubleshooting/javascript.mdx @@ -39,7 +39,7 @@ To verify that the distribution has been set correctly in the SDK, open an issue 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. +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 diff --git a/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx b/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx index aa5af4955018b..df7829193bb77 100644 --- a/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx +++ b/platform-includes/sourcemaps/legacy-uploading-methods/javascript.mdx @@ -328,7 +328,7 @@ To verify that the distribution has been set correctly in the SDK, open an issue 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. +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 diff --git a/platform-includes/sourcemaps/overview/javascript.capacitor.mdx b/platform-includes/sourcemaps/overview/javascript.capacitor.mdx index 2e80008f76640..b64502cfa0761 100644 --- a/platform-includes/sourcemaps/overview/javascript.capacitor.mdx +++ b/platform-includes/sourcemaps/overview/javascript.capacitor.mdx @@ -50,7 +50,7 @@ If you used Create React App to set up your React application see our Sentry CLI. - + diff --git a/platform-includes/sourcemaps/overview/javascript.mdx b/platform-includes/sourcemaps/overview/javascript.mdx index 0461bec03fa66..bdf2eaf2dead5 100644 --- a/platform-includes/sourcemaps/overview/javascript.mdx +++ b/platform-includes/sourcemaps/overview/javascript.mdx @@ -58,7 +58,7 @@ If you used Create React App to set up your React application see our Sentry CLI. - + diff --git a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx index b03d030a4751a..c8fd38841a7a7 100644 --- a/platform-includes/sourcemaps/overview/javascript.nextjs.mdx +++ b/platform-includes/sourcemaps/overview/javascript.nextjs.mdx @@ -41,7 +41,7 @@ With **Turbopack** (Next.js 15+ default), source maps upload after the build com ```typescript {filename:next.config.ts} import type { NextConfig } from "next"; -import { withSentryConfig } from "@sentry/nextjs"; +import { withSentryConfig } from "@sentry/nextjs/config"; const nextConfig: NextConfig = { // your existing Next.js config @@ -70,10 +70,7 @@ See Build OptionsWebpack Setup for complete Webpack configuration. diff --git a/platform-includes/sourcemaps/overview/javascript.remix.mdx b/platform-includes/sourcemaps/overview/javascript.remix.mdx index 40b741b58836f..44817187e006e 100644 --- a/platform-includes/sourcemaps/overview/javascript.remix.mdx +++ b/platform-includes/sourcemaps/overview/javascript.remix.mdx @@ -9,66 +9,47 @@ If you installed the SDK manually or the wizard failed, follow the steps below t Starting from version 2.2.0, Remix supports [Vite](https://vitejs.dev/) as a build tool, and from Remix version 2.7.0 it's stable and the recommended way to build your application. -If you use Vite to build your project, you can use the [Vite plugin](/platforms/javascript/sourcemaps/uploading/vite/) to upload source maps to Sentry. +If you use Vite to build your project, `sentryRemixVitePlugin` uploads your source maps to Sentry. It ships with `@sentry/remix`, so there's no extra package to install. -First, install the plugin if you haven't already done so: - -```bash {tabTitle:npm} -npm install @sentry/vite-plugin --save-dev -``` - -```bash {tabTitle:yarn} -yarn add @sentry/vite-plugin --dev -``` - -```bash {tabTitle:pnpm} -pnpm add @sentry/vite-plugin --save-dev -``` - -Then, add the plugin to your Vite configuration: +Add your Sentry organization, project, and auth token to the plugin in your Vite configuration: ```typescript {filename:vite.config.ts} -import { defineConfig } from "vite"; import { vitePlugin as remix } from "@remix-run/dev"; -import { sentryVitePlugin } from "@sentry/vite-plugin"; +import { sentryRemixVitePlugin } from "@sentry/remix/vite"; +import { defineConfig } from "vite"; export default defineConfig({ plugins: [ remix({ // ... your Remix plugin options }), - sentryVitePlugin({ - // If you use .sentryclirc or environment variables, - // you don't need to specify these options - authToken: "___SENTRY_AUTH_TOKEN___", + sentryRemixVitePlugin({ + // If you use environment variables, you don't need to specify these options + authToken: process.env.SENTRY_AUTH_TOKEN, org: "___SENTRY_ORG_SLUG___", project: "___SENTRY_PROJECT_SLUG___", - - sourcemaps: { - // As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry. - // Set the appropriate glob pattern for your output folder - some glob examples below: - filesToDeleteAfterUpload: ["./**/*.map", ".*/**/public/**/*.map", "./dist/**/client/**/*.map"] - } }), ], - build: { - sourcemap: "hidden", // Source map generation must be turned on ("hidden", true, etc.) - // ... rest of your Vite build options - }, // ... rest of your Vite config }); ``` +The plugin reads `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` from your environment, so you can leave the options out and set those instead. + +During a production build, the plugin injects debug IDs, uploads the source maps, and then deletes the `.map` files it generated from your build output. It skips uploading in development, so `vite dev` doesn't create a new set of artifacts on every restart. + +If you don't set `build.sourcemap` yourself, the plugin turns on hidden source maps. If you do set it, the plugin keeps your setting and leaves your source maps in place, so you control whether they're deleted with `sourcemaps.filesToDeleteAfterUpload`. + - Generating source maps **may expose them to the public**, potentially causing your - source code to be leaked. You can prevent this by configuring your server to deny access to `.js.map` files, or by - using [Sentry Vite Plugin's - `sourcemaps.filesToDeleteAfterUpload`](https://www.npmjs.com/package/@sentry/vite-plugin#sourcemapsfilestodeleteafterupload) - option to delete source maps after they've been uploaded to Sentry. + Generating source maps **may expose them to the public**, potentially causing + your source code to be leaked. If you turn on source maps yourself, prevent + this by configuring your server to deny access to `.js.map` files, or by + setting `sourcemaps.filesToDeleteAfterUpload` to delete them after they've + been uploaded to Sentry. -To see the full list of options, refer to the [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin). +To turn uploading off, set `sourcemaps.disable` to `true`. To keep the debug IDs and upload the maps yourself, set it to `'disable-upload'`. ### Using `npx @sentry/remix --upload-sourcemaps` diff --git a/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx b/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx index 840a7f50c5acf..745f393984a3b 100644 --- a/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx +++ b/platform-includes/sourcemaps/overview/javascript.sveltekit.mdx @@ -38,7 +38,7 @@ SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -58,7 +58,7 @@ Configure source map behavior in your Vite config: ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -78,7 +78,7 @@ By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to confi ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ @@ -96,7 +96,7 @@ You can disable automatic source maps upload in your Vite config: ```javascript {filename:vite.config.js} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default defineConfig({ plugins: [ diff --git a/platform-includes/sourcemaps/troubleshooting/javascript.mdx b/platform-includes/sourcemaps/troubleshooting/javascript.mdx index 0a478c5e54635..9015bf368ce4e 100644 --- a/platform-includes/sourcemaps/troubleshooting/javascript.mdx +++ b/platform-includes/sourcemaps/troubleshooting/javascript.mdx @@ -133,7 +133,6 @@ Sometimes build scripts and plugins produce pre-compressed minified files (for e 'javascript.node', 'javascript.aws-lambda', 'javascript.azure-functions', - 'javascript.connect', 'javascript.express', 'javascript.fastify', 'javascript.gcp-functions', diff --git a/platform-includes/sourcemaps/upload/primer/javascript.mdx b/platform-includes/sourcemaps/upload/primer/javascript.mdx index f181c01f57bc5..45e543f4beaf5 100644 --- a/platform-includes/sourcemaps/upload/primer/javascript.mdx +++ b/platform-includes/sourcemaps/upload/primer/javascript.mdx @@ -1,7 +1,7 @@ We provide guides on uploading source maps to Sentry for the most popular JavaScript build tools. Pick one from the list below to learn more. - + @@ -11,7 +11,7 @@ If you can't find the tool of your choice in the list below, we recommend you ch - + diff --git a/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx b/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx index 47372f4bfdbed..21d87031621b0 100644 --- a/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx +++ b/platform-includes/sourcemaps/upload/primer/javascript.sveltekit.mdx @@ -23,11 +23,11 @@ SENTRY_URL="https://your-sentry-instance.com" **Option 2** -You can also set your org and project slugs by passing a `sourceMapsUploadOptions` object to `sentrySvelteKit`, as seen in the example below. For a full list of available options, see the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options). +You can also set your org and project slugs directly in the `sentrySvelteKit` options, as seen in the example below. For a full list of available options, see the [Sentry Vite Plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#options). ```javascript {filename:vite.config.(js|ts)} {6-12} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -36,7 +36,7 @@ export default { project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, // If you're self-hosting Sentry, also add your instance URL: - // url: "https://your-self-hosted-sentry.com/", + // sentryUrl: "https://your-self-hosted-sentry.com/", }), sveltekit(), ], @@ -60,7 +60,7 @@ By default, `sentrySvelteKit` will try to detect your SvelteKit adapter to confi ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ @@ -79,7 +79,7 @@ You can disable automatic source maps upload in your Vite config: ```javascript {filename:vite.config.(js|ts)} {7} import { sveltekit } from "@sveltejs/kit/vite"; -import { sentrySvelteKit } from "@sentry/sveltekit"; +import { sentrySvelteKit } from "@sentry/sveltekit/vite"; export default { plugins: [ diff --git a/redirects.js b/redirects.js index ce4a3cae7c455..643052fa57bfc 100644 --- a/redirects.js +++ b/redirects.js @@ -588,6 +588,17 @@ const developerDocsRedirects = [ /** @type {import('next/dist/lib/load-custom-routes').Redirect[]} */ const userDocsRedirects = [ + { + source: '/platforms/javascript/guides/:guide/opentelemetry/integration/', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/:guide/opentelemetry/integration.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/opentelemetry.md', + }, + // Guides → Get Started restructure { source: '/guides/', @@ -970,6 +981,82 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/aws-lambda/cjs-npm__v9.x/', destination: '/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x/', }, + { + // Previous Nuxt setup method (--import) + source: '/platforms/javascript/guides/nuxt/install/cli-import/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // Previous Nuxt setup method (top-level import) + source: '/platforms/javascript/guides/nuxt/install/limited-server-tracing/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // Previous Nuxt setup method (dynamic import) + source: '/platforms/javascript/guides/nuxt/install/dynamic-import/', + destination: '/platforms/javascript/guides/nuxt/install/', + }, + { + // The Nuxt SDK links to this path in its Cloudflare build warning + source: '/platforms/javascript/guides/nuxt/install/cloudflare-workers/', + destination: '/platforms/javascript/guides/cloudflare/frameworks/nuxt/', + }, + { + source: '/platforms/javascript/guides/connect/', + destination: '/platforms/javascript/guides/node/', + }, + { + source: '/platforms/javascript/guides/connect/:path*', + destination: '/platforms/javascript/guides/node/', + }, + { + source: '/platforms/javascript/guides/node/install/lightweight/', + destination: + '/platforms/javascript/guides/node/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/express/install/lightweight/', + destination: + '/platforms/javascript/guides/express/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/fastify/install/lightweight/', + destination: + '/platforms/javascript/guides/fastify/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/hapi/install/lightweight/', + destination: + '/platforms/javascript/guides/hapi/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/hono/install/lightweight/', + destination: + '/platforms/javascript/guides/hono/configuration/integrations/opentelemetry/', + }, + { + source: '/platforms/javascript/guides/koa/install/lightweight/', + destination: + '/platforms/javascript/guides/koa/configuration/integrations/opentelemetry/', + }, + { + source: + '/platforms/javascript/guides/:guide(node|express|fastify|hapi|hono|koa|nestjs)/install/esm/', + destination: '/platforms/javascript/guides/:guide/', + }, + { + source: + '/platforms/javascript/guides/:guide(node|express|fastify|hapi|hono|koa|nestjs)/install/commonjs/', + destination: '/platforms/javascript/guides/:guide/', + }, + { + source: '/platforms/javascript/guides/nestjs/install/esm-without-import/', + destination: '/platforms/javascript/guides/nestjs/', + }, + { + source: '/platforms/javascript/guides/nestjs/install/', + destination: '/platforms/javascript/guides/nestjs/', + }, { source: '/platforms/javascript/guides/react-router/features/instrumentation-api/', destination: '/platforms/javascript/guides/react-router/manual-setup/', @@ -2318,6 +2405,30 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/cloudflare/features/vite-plugin/:path*', destination: '/platforms/javascript/guides/cloudflare/install/vite-plugin/:path*', }, + // The nodejs_compat entrypoint was removed in v11; the guide covers the single entry. + { + source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat.md', + destination: '/platforms/javascript/guides/cloudflare.md', + }, + { + source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', + destination: '/platforms/javascript/guides/cloudflare/', + }, + // instrumentD1WithSentry was removed in v11; withSentry() instruments D1 bindings automatically. + { + source: '/platforms/javascript/guides/cloudflare/features/d1.md', + destination: '/platforms/javascript/guides/cloudflare/features/bindings.md', + }, + { + source: '/platforms/javascript/guides/cloudflare/features/d1/:path*', + destination: '/platforms/javascript/guides/cloudflare/features/bindings/', + }, + // honoIntegration was removed in v11 in favor of the @sentry/hono SDK. + { + source: + '/platforms/javascript/guides/cloudflare/configuration/integrations/hono/:path*', + destination: '/platforms/javascript/guides/hono/', + }, // Cloudflare AI pages moved from Features to Agent Tracing. { source: '/platforms/javascript/guides/cloudflare/features/agents-sdk.md', @@ -2421,6 +2532,123 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/:guide/agent-tracing/eve/:path*', destination: '/platforms/javascript/guides/eve/', }, + // AI provider setup pages moved from agent-tracing to configuration/integrations + { + source: '/platforms/javascript/agent-tracing/openai.md', + destination: '/platforms/javascript/guides/node/configuration/integrations/openai.md', + }, + { + source: '/platforms/javascript/agent-tracing/openai/:path*', + destination: '/platforms/javascript/guides/node/configuration/integrations/openai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/openai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/openai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/openai/:path*', + destination: '/platforms/javascript/guides/:guide/configuration/integrations/openai/', + }, + { + source: '/platforms/javascript/agent-tracing/anthropic.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/anthropic.md', + }, + { + source: '/platforms/javascript/agent-tracing/anthropic/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/anthropic/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/anthropic.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/anthropic.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/anthropic/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/anthropic/', + }, + { + source: '/platforms/javascript/agent-tracing/google-genai.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/google-genai.md', + }, + { + source: '/platforms/javascript/agent-tracing/google-genai/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/google-genai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/google-genai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/google-genai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/google-genai/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/google-genai/', + }, + { + source: '/platforms/javascript/agent-tracing/langchain.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langchain.md', + }, + { + source: '/platforms/javascript/agent-tracing/langchain/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langchain/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langchain.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langchain.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langchain/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langchain/', + }, + { + source: '/platforms/javascript/agent-tracing/langgraph.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langgraph.md', + }, + { + source: '/platforms/javascript/agent-tracing/langgraph/:path*', + destination: + '/platforms/javascript/guides/node/configuration/integrations/langgraph/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langgraph.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langgraph.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/langgraph/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/langgraph/', + }, + { + source: '/platforms/javascript/agent-tracing/vercelai.md', + destination: + '/platforms/javascript/guides/node/configuration/integrations/vercelai.md', + }, + { + source: '/platforms/javascript/agent-tracing/vercelai/:path*', + destination: '/platforms/javascript/guides/node/configuration/integrations/vercelai/', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/vercelai.md', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/vercelai.md', + }, + { + source: '/platforms/javascript/guides/:guide/agent-tracing/vercelai/:path*', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/vercelai/', + }, // Browser and mobile Agent Tracing pages now point to the Node.js guides. { source: '/platforms/javascript/agent-tracing.md', @@ -2522,55 +2750,16 @@ const userDocsRedirects = [ source: '/platforms/python/integrations/pydantic-ai/:path*', destination: '/platforms/python/agent-tracing/pydantic-ai/:path*', }, - // AI library setup pages moved from configuration/integrations to agent-tracing - { - source: '/platforms/javascript/configuration/integrations/vercelai/', - destination: '/platforms/javascript/agent-tracing/vercelai/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/vercelai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/vercelai/', - }, + // InboundFilters integration was renamed to EventFilters in SDK v11 { - source: '/platforms/javascript/configuration/integrations/openai/', - destination: '/platforms/javascript/agent-tracing/openai/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/openai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/openai/', - }, - { - source: '/platforms/javascript/configuration/integrations/anthropic/', - destination: '/platforms/javascript/agent-tracing/anthropic/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/anthropic/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/anthropic/', - }, - { - source: '/platforms/javascript/configuration/integrations/google-genai/', - destination: '/platforms/javascript/agent-tracing/google-genai/', + source: '/platforms/javascript/configuration/integrations/inboundfilters/', + destination: '/platforms/javascript/configuration/integrations/eventfilters/', }, { source: - '/platforms/javascript/guides/:guide/configuration/integrations/google-genai/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/google-genai/', - }, - { - source: '/platforms/javascript/configuration/integrations/langchain/', - destination: '/platforms/javascript/agent-tracing/langchain/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/langchain/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/langchain/', - }, - { - source: '/platforms/javascript/configuration/integrations/langgraph/', - destination: '/platforms/javascript/agent-tracing/langgraph/', - }, - { - source: '/platforms/javascript/guides/:guide/configuration/integrations/langgraph/', - destination: '/platforms/javascript/guides/:guide/agent-tracing/langgraph/', + '/platforms/javascript/guides/:guide/configuration/integrations/inboundfilters/', + destination: + '/platforms/javascript/guides/:guide/configuration/integrations/eventfilters/', }, // agent-tracing-browser merged into agent-tracing { diff --git a/src/components/agentMigrationCallout.tsx b/src/components/agentMigrationCallout.tsx new file mode 100644 index 0000000000000..2b3949535db68 --- /dev/null +++ b/src/components/agentMigrationCallout.tsx @@ -0,0 +1,35 @@ +import {getCurrentPlatformOrGuide} from 'sentry-docs/docTree'; +import {serverContext} from 'sentry-docs/serverContext'; + +import {AgentSetupCallout} from './agentSetupCallout'; + +type Props = { + /** Absolute URL, site-relative path, or path relative to the selected platform. */ + guideUrl: string; + /** Migration instructions to follow after reading the guide. */ + prompt: string; + description?: string; +}; + +export function AgentMigrationCallout({ + guideUrl, + prompt, + description = 'Copy this prompt into your AI agent to migrate your Sentry SDK.', +}: Props) { + const {rootNode, path} = serverContext(); + const platform = getCurrentPlatformOrGuide(rootNode, path); + const resolvedGuideUrl = new URL( + guideUrl, + `https://docs.sentry.io${platform?.url ?? '/'}` + ).href; + + return ( + + ); +} diff --git a/src/components/agentSetupCallout/index.tsx b/src/components/agentSetupCallout/index.tsx index 4f55dffc8bf9c..5c8043f2f412f 100644 --- a/src/components/agentSetupCallout/index.tsx +++ b/src/components/agentSetupCallout/index.tsx @@ -17,14 +17,21 @@ type Props = { platformName?: string; /** Skill package name, e.g. "sentry-nextjs-sdk". Omit for generic/all skills. */ skill?: string; + /** Custom instructions for tasks other than SDK setup. */ + instructions?: { + title: string; + prompt: string; + description: string; + }; }; -export function AgentSetupCallout({skill, platformName}: Props) { +export function AgentSetupCallout({skill, platformName, instructions}: Props) { const [copied, setCopied] = useState(false); const [isExpanded, setIsExpanded] = useState(false); const {emit} = usePlausibleEvent(); - const prompt = buildPrompt(platformName); + const prompt = instructions?.prompt ?? buildPrompt(platformName); + const title = instructions?.title ?? 'Agent-Assisted Setup'; const copyPrompt = useCallback( async (event: React.MouseEvent) => { @@ -32,7 +39,10 @@ export function AgentSetupCallout({skill, platformName}: Props) { event.preventDefault(); emit('Copy AI Prompt', { - props: {page: window.location.pathname, title: 'Agent Setup Callout'}, + props: { + page: window.location.pathname, + title: instructions?.title ?? 'Agent Setup Callout', + }, }); try { @@ -50,18 +60,20 @@ export function AgentSetupCallout({skill, platformName}: Props) { setCopied(false); } }, - [prompt, emit, skill] + [prompt, emit, skill, instructions?.title] ); - const description = platformName - ? `Your agent will set up Sentry in your ${platformName} app automatically.` - : 'Your agent will set up Sentry automatically.'; + const description = + instructions?.description ?? + (platformName + ? `Your agent will set up Sentry in your ${platformName} app automatically.` + : 'Your agent will set up Sentry automatically.'); return (
- Agent-Assisted Setup + {title}
{prompt} @@ -76,36 +88,40 @@ export function AgentSetupCallout({skill, platformName}: Props) { {description} Works with Cursor, Claude Code, Codex, and more. - - View docs ↗ - + {!instructions && ( + + View docs ↗ + + )}
-
setIsExpanded(e.currentTarget.open)} - > - - {isExpanded ? ( - - ) : ( - - )} - Install the full plugin - -
-

- Install the Sentry plugin to give your assistant every skill. See the{' '} - installation docs for more details. -

- - 
-              npx @sentry/agent-plugin install
-
- -
-
+ {!instructions && ( +
setIsExpanded(e.currentTarget.open)} + > + + {isExpanded ? ( + + ) : ( + + )} + Install the full plugin + +
+

+ Install the Sentry plugin to give your assistant every skill. See the{' '} + installation docs for more details. +

+ + 
+                npx @sentry/agent-plugin install
+
+ +
+
+ )}
); } diff --git a/src/components/platformIcon.tsx b/src/components/platformIcon.tsx index 440248389f4fb..bccc78bb1eef1 100644 --- a/src/components/platformIcon.tsx +++ b/src/components/platformIcon.tsx @@ -68,6 +68,7 @@ import GodotSVG from 'platformicons/svg/godot.svg'; import GoogleSVG from 'platformicons/svg/google.svg'; import GrapheneSVG from 'platformicons/svg/graphene.svg'; import GraphqlSVG from 'platformicons/svg/graphql.svg'; +import GroqSVG from 'platformicons/svg/groq.svg'; import GrpcSVG from 'platformicons/svg/grpc.svg'; import HapiSVG from 'platformicons/svg/hapi.svg'; import HonoSVG from 'platformicons/svg/hono.svg'; @@ -92,6 +93,7 @@ import LoguruSVG from 'platformicons/svg/loguru.svg'; import MastraSVG from 'platformicons/svg/mastra.svg'; import MauiSVG from 'platformicons/svg/maui.svg'; import McpSVG from 'platformicons/svg/mcp.svg'; +import MistralSVG from 'platformicons/svg/mistral.svg'; import MongodbSVG from 'platformicons/svg/mongodb.svg'; import NativecSVG from 'platformicons/svg/nativec.svg'; import NestjsSVG from 'platformicons/svg/nestjs.svg'; @@ -223,6 +225,7 @@ import GodotSVGLarge from 'platformicons/svg_80x80/godot.svg'; import GoogleSVGLarge from 'platformicons/svg_80x80/google.svg'; import GrapheneSVGLarge from 'platformicons/svg_80x80/graphene.svg'; import GraphqlSVGLarge from 'platformicons/svg_80x80/graphql.svg'; +import GroqSVGLarge from 'platformicons/svg_80x80/groq.svg'; import GrpcSVGLarge from 'platformicons/svg_80x80/grpc.svg'; import HapiSVGLarge from 'platformicons/svg_80x80/hapi.svg'; import HonoSVGLarge from 'platformicons/svg_80x80/hono.svg'; @@ -247,6 +250,7 @@ import LoguruSVGLarge from 'platformicons/svg_80x80/loguru.svg'; import MastraSVGLarge from 'platformicons/svg_80x80/mastra.svg'; import MauiSVGLarge from 'platformicons/svg_80x80/maui.svg'; import McpSVGLarge from 'platformicons/svg_80x80/mcp.svg'; +import MistralSVGLarge from 'platformicons/svg_80x80/mistral.svg'; import MongodbSVGLarge from 'platformicons/svg_80x80/mongodb.svg'; import NativecSVGLarge from 'platformicons/svg_80x80/nativec.svg'; import NestjsSVGLarge from 'platformicons/svg_80x80/nestjs.svg'; @@ -676,6 +680,14 @@ const formatToSVG = { sm: LanggraphSVG, lg: LanggraphSVGLarge, }, + groq: { + sm: GroqSVG, + lg: GroqSVGLarge, + }, + mistral: { + sm: MistralSVG, + lg: MistralSVGLarge, + }, laravel: { sm: LaravelSVG, lg: LaravelSVGLarge, @@ -1003,6 +1015,9 @@ export const PLATFORM_TO_ICON = { git: 'git', go: 'go', 'google-genai': 'gemini', + groq: 'groq', + mistral: 'mistral', + 'together-ai': 'default', 'go-echo': 'echo', 'go-fasthttp': 'fasthttp', 'go-fiber': 'fiber', diff --git a/src/components/sidebar/platformSidebar.tsx b/src/components/sidebar/platformSidebar.tsx index 27c660d7c1437..8f6ca1b738fd0 100644 --- a/src/components/sidebar/platformSidebar.tsx +++ b/src/components/sidebar/platformSidebar.tsx @@ -23,19 +23,6 @@ const AGENT_TRACING_ALIAS_PATH_OVERRIDES: Record> const UNALIASED_AGENT_TRACING_PAGES = new Set(['manual-instrumentation']); const CLOUDFLARE_AGENT_TRACING_PAGE_SLUGS = ['agents-sdk', 'workers-ai']; -// Standalone JavaScript guides that own their Agent Tracing setup. They're -// surfaced in every JavaScript Agent Tracing sidebar as link-only entries that -// navigate to the dedicated guide instead of a page under the current guide. -const STANDALONE_AGENT_TRACING_GUIDES: { - guide: string; - sidebar_order: number; - slug: string; - title: string; -}[] = [ - {guide: 'mastra', slug: 'mastra', title: 'Mastra', sidebar_order: 26}, - {guide: 'eve', slug: 'eve', title: 'Eve', sidebar_order: 27}, -]; - export function PlatformSidebar({ rootNode, platformName, @@ -139,31 +126,10 @@ export function PlatformSidebar({ }; }).filter(alias => alias !== undefined); - // Surface the standalone Mastra and Eve guides from every JavaScript Agent - // Tracing sidebar. Their links navigate to the dedicated guide instead of - // creating an Agent Tracing page under the current guide. - const standaloneGuideAgentTracingAliases = - platformName !== 'javascript' || !agentTracingNode - ? [] - : STANDALONE_AGENT_TRACING_GUIDES.filter( - guideData => guideData.guide !== guideName - ).map(guideData => ({ - context: { - platform: {platformName}, - title: guideData.title, - sidebar_order: guideData.sidebar_order, - href: `/platforms/javascript/guides/${guideData.guide}/`, - }, - path: `/${pathRoot}/agent-tracing/${guideData.slug}/`, - })); - const tree = toTree( - [ - ...nodes, - ...agentTracingAliases, - ...cloudflareAgentTracingAliases, - ...standaloneGuideAgentTracingAliases, - ].filter(n => !!n.context) + [...nodes, ...agentTracingAliases, ...cloudflareAgentTracingAliases].filter( + n => !!n.context + ) ); // Use "Getting Started" for Next.js, default title for other platforms diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index 71a3e813dc990..15b0b589b8f88 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -1,3 +1,4 @@ +import {AgentMigrationCallout} from './components/agentMigrationCallout'; import {AgentSetupCallout} from './components/agentSetupCallout'; import {Alert} from './components/alert'; import {Arcade} from './components/arcade'; @@ -77,6 +78,7 @@ export function mdxComponents( wrapper: any = ({children}) => children ) { return { + AgentMigrationCallout, AgentSetupCallout, Alert, Arcade,