---
title: "Instrument a Node.js application | OpenTelemetry documentation"
description: "Instrument a Node.js application for Application Observability."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Instrument a Node.js application

If you need process-level telemetry for Node.js, use this guide to set up the [upstream OpenTelemetry SDK for JavaScript](https://opentelemetry.io/docs/languages/js/) for Application Observability.

## Recommended setup for Grafana Cloud

Grafana Labs recommends that you set up OpenTelemetry components, including instrumentation and an OpenTelemetry Collector distribution, using one of the [Grafana Cloud setup guides](/docs/opentelemetry/grafana-cloud/).

These opinionated guides make it easy to get started. They include all the binaries, configuration, and connection parameters you need to set up OpenTelemetry for [Grafana Cloud](/products/cloud/).

## Install the SDK

Before you begin, ensure you have a Node.js development environment with a package manager such as **NPM** or **Yarn**, and a Node.js application to instrument.

Run the following command in your project folder:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
```

## Run your application

Run your application with the following command to use auto-instrumentation and export OTLP data:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
OTEL_TRACES_EXPORTER="otlp" \
OTEL_METRICS_EXPORTER="otlp" \
OTEL_LOGS_EXPORTER="otlp" \
OTEL_NODE_RESOURCE_DETECTORS="env,host,os" \
OTEL_RESOURCE_ATTRIBUTES="service.name=<name>,service.namespace=<namespace>,deployment.environment=<environment>" \
OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" \
node <my-app>.js
```

Replace variables in `<...>` with values specific to your application and backend. For more details, see the [OpenTelemetry service attributes](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#service-attributes) documentation.

- `<name>`: your service name, for example, `shoppingcart`
- `<namespace>`: a string to group related services, such as `ecommerce` for a team that manages several services
- `<environment>`: the deployment environment, for example, the `production` deployment tier

Some backends, such as Grafana Cloud, also require you to set authentication headers in the `OTEL_EXPORTER_OTLP_HEADERS` environment variable.

### Limitations

Auto-instrumentation relies on Node.js `require` hooks. Bundling your application, for example, with `@vercel/ncc`, can break these hooks and prevent instrumentation from loading. Avoid bundling or confirm that your bundler preserves `require` hooks for instrumentation packages. For more details, see the [`@opentelemetry/instrumentation` package notes](https://www.npmjs.com/package/@opentelemetry/instrumentation).

## Resources

1. [OpenTelemetry JavaScript documentation](https://opentelemetry.io/docs/languages/js/)
2. [@opentelemetry/api on NPM](https://www.npmjs.com/package/@opentelemetry/api)
3. [opentelemetry-js on GitHub](https://github.com/open-telemetry/opentelemetry-js)