Node.js OpenTelemetry Agent

otel-agent-nodejs is a reusable OpenTelemetry agent for Node.js applications, designed to simplify the setup of distributed tracing and metrics collection. This package allows developers to quickly integrate OpenTelemetry into their projects with minimal configuration.

Features

• Automatic Instrumentation: Instruments popular Node.js libraries such as HTTP, Express, and more, without requiring changes to your application code.
• Trace and Metrics Export: Captures both traces and metrics and exports them using the OTLP (OpenTelemetry Protocol) in Protobuf format.
• Easy Integration: Simply add the package to your Dockerfile, configure NODE_OPTIONS, and set environment variables.
• Customizable: Allows specification of custom OTLP endpoints and other OpenTelemetry configurations via environment variables.

Installation

You can install the otel-agent-nodejs package via NPM:

npm install otel-agent-nodejs

Usage

To use the OpenTelemetry agent in your Node.js application, follow these steps:

1. Update Your Dockerfile

Add the following lines to your Dockerfile to install and configure the OpenTelemetry agent:

FROM node:20

WORKDIR /app

COPY package*.json ./
RUN npm install

# Install the OpenTelemetry agent
RUN npm install otel-agent-nodejs

COPY . .

# Set NODE_OPTIONS to preload the agent before the application starts
ENV NODE_OPTIONS="--require otel-agent-nodejs"

EXPOSE 3000

CMD ["node", "index.js"]

2. Configure Environment Variables

In your docker-compose.yml or directly in the environment where your application runs, configure the necessary environment variables:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OTEL_SERVICE_NAME=nodejs-otel-agent
      - OTEL_TRACES_EXPORTER=otlp
      - OTEL_METRICS_EXPORTER=otlp
      - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces
      - OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics

3. Run Your Application

Build and run your Docker container as usual. The OpenTelemetry agent will automatically start and instrument your application:

docker-compose up --build

Customization

You can customize the behavior of the OpenTelemetry agent by setting additional environment variables:

• OTEL_SERVICE_NAME: This variable sets the name of your service in the OpenTelemetry traces. It's crucial for identifying which service generated which traces.
• OTEL_TRACES_EXPORTER: Specifies the exporter to be used for sending trace data. Here, it's set to otlp (OpenTelemetry Protocol).
• OTEL_METRICS_EXPORTER: Specifies the exporter for sending metrics data, also set to otlp.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: Defines the endpoint where the OpenTelemetry collector is running. This is where the traces are sent.
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: Defines the endpoint where the OpenTelemetry collector is running. This is where the metrics are sent.

Example Project

For a complete example project that uses otel-agent-nodejs, refer to the example repository on GitHub.

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you have any improvements or new features you'd like to see.

License

This project is licensed under the MIT License. See the LICENSE file for details.