Skip to content

docs(eve): Move Sentry.init to the agent/instrumentation/ directory #19530

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.

Sign up for GitHub

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

Closed
sergical wants to merge 1 commit into from
Closed

docs(eve): Move Sentry.init to the agent/instrumentation/ directory #19530

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
49 changes: 42 additions & 7 deletions docs/platforms/javascript/guides/eve/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,11 @@ pnpm add @sentry/node@^11.0.0-rc.0 @sentry/profiling-node@^11.0.0-rc.0

## Configure

Create `agent/instrumentation.ts` and initialize Sentry. Eve auto-discovers `agent/instrumentation.ts` and runs it at server startup, before it loads your agent and the AI SDK:
Create `agent/instrumentation/sentry.ts` and initialize Sentry. Eve auto-discovers each file in the `agent/instrumentation/` directory and loads it at server startup, before it loads your agent and the AI SDK. Each file in that directory must default-export an instrumentation provider, so the file also exports one that flushes Sentry when Eve flushes its telemetry:

```typescript {filename:agent/instrumentation.ts}
```typescript {filename:agent/instrumentation/sentry.ts}
import * as Sentry from "@sentry/node";
import { defineInstrumentation } from "eve/instrumentation";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling
Expand Down Expand Up @@ -111,12 +112,28 @@ Sentry.init({
profileSessionSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ profiling
});

export default defineInstrumentation({
flush: async () => {
await Sentry.flush(2000);
},
});
```

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. 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.
<Alert level="warning" title="Eve 0.62.0 removed agent/instrumentation.ts">

Eve versions before `0.62.0` load a single `agent/instrumentation.ts` file instead. Eve `0.62.0` and later fail the build when that file exists. If you upgrade Eve, move your `Sentry.init` call into `agent/instrumentation/sentry.ts` as shown above and delete `agent/instrumentation.ts`.

Eve treats every file in `agent/instrumentation/` as a provider. Keep shared helper code in a different directory, for example `agent/lib/`.

</Alert>

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. When you run `eve dev`, prompts and model outputs are recorded on your agent spans, so the Agent Tracing transcript shows the full exchange. Outside development, Eve turns this recording off for each model call. To record prompts and model outputs there too, see [Record Prompts and Outputs Outside Development](#record-prompts-and-outputs-outside-development).

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

Let the Sentry SDK own the OpenTelemetry setup. Don't add Eve's `otel()` or `otelIntegration()` providers to `agent/instrumentation/` next to this file. If both the Sentry SDK and Eve try to register the global OpenTelemetry tracer provider, Eve refuses to start.

## Verify

Start Eve and send a prompt that calls a tool. Then open [Agent Tracing](/product/agents/) in Sentry and select the run. The timeline shows the model calls, tool calls, token usage, and latency for that turn, plus any errors your agent threw.
Expand All @@ -125,16 +142,18 @@ If no data appears, confirm that:

- The `dsn` belongs to the Sentry project you're viewing.
- `tracesSampleRate` is greater than `0`.
- Your app completed at least one agent turn after you added `agent/instrumentation.ts`.
- Your app completed at least one agent turn after you added `agent/instrumentation/sentry.ts`.
- `agent/instrumentation.ts` doesn't exist. Eve `0.62.0` and later fail the build when it finds that file.
- Eve's earlier OTLP instrumentation isn't also initialized in the agent runtime. Running both integrations duplicates AI spans, token totals, and costs.
- If the spans appear without prompts and model outputs, see [Record Prompts and Outputs Outside Development](#record-prompts-and-outputs-outside-development).

</StepConnector>

## Privacy Controls

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`:
Generative AI inputs and outputs — the prompts your agent sends and the model responses it receives — are recorded on your agent spans by default when you run `eve dev`. 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.ts}
```typescript {filename:agent/instrumentation/sentry.ts}
Sentry.init({
dsn: "___PUBLIC_DSN___",
dataCollection: {
Comment on lines +156 to 159

@sentry sentry Bot Sep 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Documentation snippets for agent/instrumentation/sentry.ts are presented as complete files but lack the required export default defineInstrumentation({...}) wrapper, causing build failures.
Severity: MEDIUM

Suggested Fix

Update the documentation snippets to either include the full, valid file content including the export default defineInstrumentation({...}) wrapper and necessary imports, or explicitly label them as partial examples that must be merged into the existing file configuration. This will prevent users from creating invalid files.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/javascript/guides/eve/index.mdx#L156-L159

Potential issue: The documentation for Eve presents several code snippets for
`agent/instrumentation/sentry.ts` as if they are complete files, using a filename
indicator. However, these snippets are missing the required `export default
defineInstrumentation({...})` wrapper. The guide explicitly states that every file in
the `agent/instrumentation/` directory must have this default export. A user copying and
pasting these incomplete snippets from sections like 'Privacy Controls' or 'Record
Prompts' will create an invalid file, causing the Eve build process to fail.

Also affects:

  • docs/platforms/javascript/guides/eve/index.mdx:173~183

Did we get this right? 👍 / 👎 to inform future reviews.

Expand All @@ -143,6 +162,22 @@ Sentry.init({
});
```

### Record Prompts and Outputs Outside Development

Outside development, for example under `eve start`, Eve passes `recordInputs: false` and `recordOutputs: false` to the AI SDK on each model call. These per-call values take priority over `dataCollection.genAI`, so your spans arrive without prompts and model outputs. To record them, set the options on the Vercel AI integration:

```typescript {filename:agent/instrumentation/sentry.ts}
Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
Sentry.vercelAIIntegration({
recordInputs: true,
recordOutputs: true,
}),
],
});
```

## Link Conversations

Each Eve turn is its own durable workflow, so a session's turns land in separate traces. To group them into a single [Conversation](/product/agents/conversations/) in the Agents dashboards, add the `eveConversationHook` in an `agent/hooks/sentry.ts` file:
Expand Down Expand Up @@ -201,4 +236,4 @@ export default defineAgent({
## Supported Versions

- `@sentry/node`: `>=11.0.0-rc.0`
- `eve`: tested with `0.52.3` and later
- `eve`: tested with `0.63.0`. Eve versions before `0.62.0` use `agent/instrumentation.ts` in place of the `agent/instrumentation/` directory.
Loading