This page describes how to install the Observe Agent, then instrument your Node.js applications to send data to Observe.

Compatibility

See Supported Node.js libraries and frameworks for the .NET compatibility matrix.

To manually instrument custom logic, see Manual instrumentation setup in the OpenTelemetry documentation.

Get the Observe Agent

Use the Add Data portal in the product to get the Observe Agent installed in your environment.

1. From the left navigation rail, select Data & integrations > Add data.
2. In the Observe Agent section, pick your environment, then follow the instructions to create a data ingest token and install the Observe Agent.

Depending on the environment you select, you are asked to select some options for installing and configuring the Observe Agent.

3. Follow the remainder of the instructions to install the Observe Agent and verify that your data is being received.

Add the zero-code auto-instrumentation for Node.js

Perform the following steps to add zero-code instrumentation to your Node.js apps.

1. Add the OpenTelemetry zero-code instrumentation for Node.js.

   Run the following commands to add zero-code instrumentation for your Node.js application, meaning you don’t have to modify your application’s source code to collect telemetry:

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

   1. Set the following environment variables to configure the Node.js instrumentation. Replace the placeholders such as ${YOUR_SERVICE_NAME} with the actual information from your environment.

      export OTEL_SERVICE_NAME=${YOUR_SERVICE_NAME}
      export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
      export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=${YOUR_APP_ENVIRONMENT}
      export OTEL_EXPORTER_OTLP_ENDPOINT=http://${YOUR_OBSERVE_AGENT_ENDPOINT}:4318
      export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

      Set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to one of the following addresses to send application telemetry including traces to the Observe Agent:

      Environment	Endpoint
      Host (Linux, macOS, Windows)	OTLP/HTTP: https://localhost:4318 OTLP/grpc: https://localhost:4317
      Kubernetes	OTLP/HTTP: http://observe-agent-forwarder.observe.svc.cluster.local:4318 OTLP/grpc: http://observe-agent-forwarder.observe.svc.cluster.local:4317

      
      

2. (Optional) To correlate your infrastructure metrics with services in the Service Explorer, you need to annotate your pods as described in Associate infrastructure metrics with services.

3. Run your instrumented app:

   node --require @opentelemetry/auto-instrumentations-node/register <YOUR_APP_ENTRYPOINT>.js
   

ESM support

If your application is written in JavaScript as ECMAScript modules (ESM), or compiled to ESM from TypeScript, then a loader hook is required to properly patch instrumentation. Below is the custom hook for ESM instrumentation:

--experimental-loader=@opentelemetry/instrumentation/hook.mjs

This flag must be passed to the node binary, which is often done as a startup command and/or in the NODE_OPTIONS environment variable. For more information, ECMAScript Modules vs. Common JS in the OpenTelemetry documentation.

Use the following commands to run your app with the experimental loader:

node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --require @opentelemetry/auto-instrumentations-node/register <YOUR_APP_ENTRYPOINT>.js

Instrument Fastify

Fastify's built-in OTel plugin, @fastify/otel, produces richer request-handler spans than the generic HTTP instrumentation alone. It is not included in the auto-instrumentations meta-package.

Install alongside the auto-instrumentations:

npm install @fastify/otel

Register it as a Fastify plugin in your application code:

• For CJS:

  const { FastifyOtel } = require("@fastify/otel");
  fastify.register(FastifyOtel, { serviceName: "<service-name>" });

• For ESM / TypeScript

  import { FastifyOtel } from "@fastify/otel";
  fastify.register(FastifyOtel, { serviceName: "<service-name>" });

Start with the same flags from your configuration when you installed the Observe Agent. @fastify/otel reads from the global TracerProvider registered by the auto-instrumentations — no additional SDK setup is required.

Instrument Prisma

Prisma ships its own instrumentation package, @prisma/instrumentation, which produces prisma:engine:db_query client spans with full SQL query text. It is not included in the auto-instrumentations meta-package.

Because @prisma/instrumentation must be registered programmatically, you need a short setup file instead of the register shorthand.

Install alongside the auto-instrumentations:

npm install @prisma/instrumentation

Create an instrumentation setup file at the project root:

• For CJS, create instrumentation.cjs:

  const { NodeSDK } = require("@opentelemetry/sdk-node");
  const {
    getNodeAutoInstrumentations,
  } = require("@opentelemetry/auto-instrumentations-node");
  const { PrismaInstrumentation } = require("@prisma/instrumentation");
  
  const sdk = new NodeSDK({
    instrumentations: [
      getNodeAutoInstrumentations(),
      new PrismaInstrumentation(),
    ],
  });
  
  sdk.start();

• For ESM / TypeScript, create instrumentation.mjs or instrumentation.ts:

  import { NodeSDK } from "@opentelemetry/sdk-node";
  import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
  import { PrismaInstrumentation } from "@prisma/instrumentation";
  
  const sdk = new NodeSDK({
    instrumentations: [
      getNodeAutoInstrumentations(),
      new PrismaInstrumentation(),
    ],
  });
  
  sdk.start();

Start with --require or --import pointing at the setup file:

If you are using both Fastify and Prisma, register @fastify/otel as a Fastify plugin in your application code. The setup file above already configures the global TracerProvider that @fastify/otel reads from.

Next steps

Navigate to Traces in your Observe tenant to view traces from your application.

• Use Trace Explorer to find traces in your environment.
• Use service management to view your services and their dependencies.
• Monitor and track new deployments on your service.
• View logs associated with a trace.
• Use the APM reference to see what data is collected by APM.