-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
feat(node-core): Add lightweight mode docs #16396
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
11dda7c
feat(node-core): Add lightweight mode docs
andreiborza ca9ac33
Add manual tracing explanation
andreiborza b3d3429
Update docs/platforms/javascript/common/install/lightweight.mdx
andreiborza c4d6bf6
Update docs/platforms/javascript/common/install/lightweight.mdx
andreiborza f0c0508
Update docs/platforms/javascript/common/install/lightweight.mdx
andreiborza f332c0d
Don't escape <
andreiborza 3f83e66
Update comparison table
andreiborza File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
129 changes: 129 additions & 0 deletions
129
docs/platforms/javascript/common/install/lightweight.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| --- | ||
|
|
||
| <Alert level="warning"> | ||
| Lightweight mode is experimental and may have breaking changes in minor or | ||
| patch releases. | ||
| </Alert> | ||
|
|
||
| <Alert> | ||
| Are you unsure if you should use this installation method? Review our | ||
| [installation methods](../). | ||
| </Alert> | ||
|
|
||
| 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+). | ||
|
sentry[bot] marked this conversation as resolved.
|
||
|
|
||
| If needed, you can still manually create spans by using Sentry's <PlatformLink to="/tracing/instrumentation/">custom instrumentation APIs</PlatformLink> 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) | ||
|
andreiborza marked this conversation as resolved.
|
||
|
|
||
| ## 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"); | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| <Alert level="warning"> | ||
| When using manual isolation on Node.js < 22, distributed tracing will not | ||
| work correctly. | ||
| </Alert> | ||
|
|
||
| ## 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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this would be nice in a dropdown, as not everyone needs to read the paragraph.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, this is in the overview of install methods. Tbh I don't even know if this is the right place to put this but it's the best I could think of atm.
If we put it in a dropdown I fear the discoverability suffers a lot. It's already kind of hidden in this page (can't see lightweight mode in the sidebar).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah makes sense! I expanded the rest of the file and I think it's better to just keep it like this.