Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/platforms/javascript/common/install/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Comment on lines +59 to +62
Copy link
Copy Markdown
Member

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.

Copy link
Copy Markdown
Member Author

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).

Copy link
Copy Markdown
Member

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.

</PlatformCategorySection>

<PlatformCategorySection supported={['browser']}>
Expand Down
129 changes: 129 additions & 0 deletions docs/platforms/javascript/common/install/lightweight.mdx
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+).
Comment thread
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)
Comment thread
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.