diff --git a/docs/platforms/javascript/common/install/index.mdx b/docs/platforms/javascript/common/install/index.mdx index be74a26ac984fa..bdf4d7e8bb89a1 100644 --- a/docs/platforms/javascript/common/install/index.mdx +++ b/docs/platforms/javascript/common/install/index.mdx @@ -56,6 +56,10 @@ If you are using `import` in your application, your installation method depends If you do not compile your code, you'll need to follow the [ESM instructions](./esm). +### I don't need automatic spans/transactions + +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. + diff --git a/docs/platforms/javascript/common/install/lightweight.mdx b/docs/platforms/javascript/common/install/lightweight.mdx new file mode 100644 index 00000000000000..f0d909bcd8d367 --- /dev/null +++ b/docs/platforms/javascript/common/install/lightweight.mdx @@ -0,0 +1,129 @@ +--- +title: Lightweight Mode +sidebar_order: 15 +description: "Learn about using @sentry/node-core in lightweight mode without OpenTelemetry." +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`. + +## 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. + + +## 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.