---
title: Node.js Application Agentic Instrumentation
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > Agent Observability > Agent Observability Instrumentation > Agentic
  Instrumentation > Node.js Application Agentic Instrumentation
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Node.js Application Agentic Instrumentation

{% 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 %}

**Note**: The Datadog Node.js SDK **only** supports Node.js runtimes. If the user's application is in another Javascript runtime, do **not** use this instruction set.

## Frameworks{% #frameworks %}

If the user is instrumenting an application with one of the following frameworks, follow that guide *instead* of following the instructions at and below Instrumentation.

| Framework | Instructions                                                                                        |
| --------- | --------------------------------------------------------------------------------------------------- |
| Next.js   | [Next.js Instrumentation Guide](https://docs.datadoghq.com/llm_observability/guide/nextjs_guide.md) |

## Instrumentation{% #instrumentation %}

1. Install the latest `ddtrace` package.

Check the package manager the repo or project already uses and use that to install the dependencies. Verify via lockfiles.

```bash
npm install dd-trace # npm
pnpm add dd-trace # pnpm
yarn add dd-trace # yarn
```
Add in Datadog loader hooks
This is **mandatory**.

Datadog loader hooks are used to automatically patch ESM and Typescript import statements to instrument supported frameworks. Set `NODE_OPTIONS="--import dd-trace/register.js"` as early as possible, ideally as part of the startup command. This should be available for the Node.js process when it spawns, so setting it after load time is **not** acceptable.

Here is an example with the package.json:

```json
{
  "scripts": {
    "start": "NODE_OPTIONS=\"--import dd-trace/register.js\" node app.js"
  }
}
```

Although this value can be set in a `Dockerfile`, bootstrap script, etc., as long as that infrastructure *already* exists in the code and is *before* the Node.js application process starts.
Initialize the Agent Observability package
Initialize the Agent Observability SDK via `ddtrace.auto`. This **needs** to be done as the first import in the application's entrypoint, aside from any environment variable or configuration-loading imports.

**Note**: do not add in extraneous comments.

```typescript
import 'dotenv/config'; // this might load DD_ environment variables

import 'dd-trace/init'; // CRUCIAL: this initializes the Agent Observability SDK and instrumentations

// ... remaining application logic
```