---
title: Instrument a Next.js Application for Agent Observability
description: >-
  Learn how to set up Agent Observability in a Next.js application using
  auto-instrumentation to monitor and trace your LLM calls.
breadcrumbs: >-
  Docs > Agent Observability > Agent Observability Guides > Instrument a Next.js
  Application for Agent Observability
---

# Instrument a Next.js Application for Agent Observability

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

Monitor Next.js applications using [Agent Observability](https://docs.datadoghq.com/llm_observability.md) by instrumenting your server-side LLM and agent calls.

## Prerequisites{% #prerequisites %}

- A [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys)
- Next.js 13.4+ (required for `instrumentation.ts` support)
- `dd-trace` >= 5.38.0

## Setup{% #setup %}

### Install the SDK{% #install-the-sdk %}

```shell
npm install dd-trace
```

### Configure Next.js{% #configure-nextjs %}

Add `dd-trace` and any LLM integration packages to `serverExternalPackages` in your `next.config.ts` (or `next.config.js`). Check [the list of supported libraries](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation.md?tab=nodejs) for a list of supported libraries before writing to the `serverExternalPackages` array to include all packages that are auto-instrumented by dd-trace. This tells Next.js not to bundle these packages, which is required for auto-instrumentation to work:

```typescript
// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  serverExternalPackages: [
    'dd-trace',
    'openai',
    // add any other auto-instrumented packages here, refer to the supported autoinstrumentation matrix for specific supported packages
  ],
  experimental: {
    instrumentationHook: true, // required for Next.js versions before 15.x
  },
}

export default nextConfig
```

**Note**: For Next.js 15+, `instrumentationHook` is enabled by default and does not need to be set explicitly.

### Initialization{% #initialization %}

You can initialize the Agent Observability SDK using `NODE_OPTIONS` (recommended) or `instrumentation.ts`.

{% tab title="Node options" %}
Set the following `NODE_OPTIONS` to allow `dd-trace` to instrument all relevant LLM client and agentic calls from your Next.js application:

```bash
NODE_OPTIONS="--import dd-trace/initialize.mjs"
```

{% /tab %}

{% tab title="Instrumentation.ts" %}
**Note**: Utilizing `NODE_OPTIONS` is the preferred method for enabling auto-instrumentation for Next.js applications. Only apply `instrumentation.ts` changes when that is not available.

Create an `instrumentation.ts` file in the root of your project (at the same level as `pages/` or `app/`):

```typescript
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const initializeImportName = 'dd-trace/initialize.mjs';
    await import(initializeImportName as string)
    // await import(/* webpackIgnore: true */ initializeImportName as 'dd-trace/initialize.mjs') // if using webpack instead of turbopack
  }
}
```

The `NEXT_RUNTIME === 'nodejs'` check ensures the tracer is only initialized in the Node.js server runtime, not in the Edge runtime.
{% /tab %}

### Set environment variables{% #set-environment-variables %}

Set the following environment variables before starting your Next.js application. You can add them to a `.env.local` file for local development:

```shell
DD_LLMOBS_ENABLED=1
DD_LLMOBS_ML_APP=<YOUR_ML_APP_NAME>
DD_SITE=<YOUR_DATADOG_SITE>
DD_API_KEY=<YOUR_DATADOG_API_KEY>
```

Your Datadog site is <YOUR_DATADOG_SITE>.

**Note**: If you are using `NODE_OPTIONS`, define these environment variables at the same level as `NODE_OPTIONS`, otherwise Agent Observability will not be properly enabled.

### Start the application{% #start-the-application %}

```shell
npm run dev   # development
npm run build && npm run start  # production
```

After startup, the SDK automatically traces LLM calls made in server-side code to [supported Node.js frameworks](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation.md?tab=nodejs) such as OpenAI, LangChain, Vercel AI SDK, Bedrock, Anthropic, and more.

## View traces in Datadog{% #view-traces-in-datadog %}

After making LLM calls, view the resulting traces in the [Agent Observability Traces view](https://app.datadoghq.com/llm/traces) in Datadog. Select your ML application name from the top-left dropdown.

Each trace shows token usage, model, latency, and the full input and output for the LLM call.

## Troubleshooting{% #troubleshooting %}

**Traces are not appearing**

- Confirm `instrumentation.ts` is in the project root (same level as `app/` or `pages/`), not inside the `app/` directory.
- Confirm `dd-trace` and your LLM provider package (for example, `openai`) are both listed under `serverExternalPackages` in `next.config.ts`.
- If using Next.js < 15, confirm `experimental.instrumentationHook: true` is set in `next.config.ts`.
- Confirm the environment variables `DD_LLMOBS_ENABLED` and `DD_API_KEY` are set when initializing the tracer before starting the server.

**Edge runtime is not supported** The Datadog SDK requires the Node.js runtime. Ensure your Route Handlers and Server Actions that make LLM calls do not set `export const runtime = 'edge'`.