OpenTelemetry Node.js distro for Uptrace

This document explains how to configure OpenTelemetry JavaScript SDK for Node.js to export spans and metrics to Uptrace using OTLP/HTTP.

To learn about OpenTelemetry API, see OpenTelemetry JS Tracing API and OpenTelemetry JS Metrics API.

• Installation
• Configuration
• Automatic instrumentation
• Configuration options
• Getting started
• What's next?

Installation

# npm
npm install @uptrace/node --save

# yarn
yarn add @uptrace/node --save

Configuration

You can configure Uptrace client using a DSN (Data Source Name, e.g. https://<token>@uptrace.dev/<project_id>) from the project settings page.

WARNING

You must call configureOpentelemetry as early as possible and before importing other packages, because OpenTelemetry SDK must patch libraries before you import them.

// The very first import must be Uptrace/OpenTelemetry.
const uptrace = require('@uptrace/node')
const otel = require('@opentelemetry/api')

// Start OpenTelemetry SDK and invoke instrumentations to patch the code.
uptrace.configureOpentelemetry({
  // copy your project DSN here or use UPTRACE_DSN env var
  //dsn: 'https://<token>@uptrace.dev/<project_id>',
  serviceName: 'myservice',
  serviceVersion: '1.0.0',
  deploymentEnvironment: 'production',
})

// Other imports. Express is monkey-patched at this point.
const express = require('express')

// Create a tracer.
const tracer = otel.trace.getTracer('app_or_package_name')

// Start the app.
const app = express()
app.listen(3000)

You can also put the OpenTelemetry initialization code into a separate file called tracing.js and use the --require flag to load the tracing code before the application code:

# JavaScript
node --require ./tracing.js app.js

# TypeScript
ts-node --require ./tracing.ts app.ts

See express-pg for a working example.

Automatic instrumentation

Whenever you load a module, OpenTelemetry automatically checks if there a matching instrumentation plugin and uses it to patch the original package.

You can also register instrumentations manually:

const uptrace = require('@uptrace/node')
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http')
const { PgInstrumentation } = require('@opentelemetry/instrumentation-pg')

uptrace.configureOpentelemetry({
  // Set dsn or UPTRACE_DSN env var.
  dsn: 'https://<token>@uptrace.dev/<project_id>',

  serviceName: 'myservice',
  serviceVersion: '1.0.0',

  instrumentations: [new PgInstrumentation(), new HttpInstrumentation()],
})

Configuration options

You can use the following options to configure Uptrace client.

Option	Description
dsn	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
serviceName	service.name resource attribute. For example, myservice.
serviceVersion	service.version resource attribute. For example, 1.0.0.
deploymentEnvironment	deployment.environment resource attribute. For example, production.
resourceAttributes	Any other resource attributes.
resource	Resource contains attributes representing an entity that produces telemetry. Resource attributes are copied to all spans and events.

You can also use environment variables to configure the client:

Env var	Description
UPTRACE_DSN	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTES	Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORS	Propagators to be used as a comma separated list. The default is tracecontext,baggage.

Getting started

Install OpenTelemetry distro, generate your first trace, and click the link in your terminal to open Uptrace. All it takes is a minute of your time.

• Step 0. Create an Uptrace project to obtain a DSN (connection string), for example, https://<token>@uptrace.dev/<project_id>.

• Step 1. Install @uptrace/node:

# npm
npm install @uptrace/node --save

# yarn
yarn add @uptrace/node --save

• Step 2. Copy the code to main.js replacing the <dsn>:

// The very first import must be Uptrace/OpenTelemetry.
const otel = require('@opentelemetry/api')
const uptrace = require('@uptrace/node')

// Start OpenTelemetry SDK and invoke instrumentations to patch the code.
uptrace.configureOpentelemetry({
  // Set dsn or UPTRACE_DSN env var.
  dsn: 'https://<token>@uptrace.dev/<project_id>',
  serviceName: 'myservice',
  serviceVersion: '1.0.0',
})

// Create a tracer. Usually, tracer is a global variable.
const tracer = otel.trace.getTracer('app_or_package_name', '1.0.0')

// Create a root span (a trace) to measure some operation.
tracer.startActiveSpan('main-operation', (main) => {
  tracer.startActiveSpan('child1-of-main', (child1) => {
    child1.setAttribute('key1', 'value1')
    child1.recordException(new Error('error1'))
    child1.end()
  })

  tracer.startActiveSpan('child2-of-main', (child2) => {
    child2.setAttribute('key2', 42)
    child2.end()
  })

  // End the span when the operation we are measuring is done.
  main.end()

  console.log(uptrace.traceUrl(main))
})

setTimeout(async () => {
  // Send buffered spans and free resources.
  await uptrace.shutdown()
})

• Step 3. Run the example to get a link for the generated trace:

node main.js
https://uptrace.dev/traces/<trace_id>

• Step 4. Follow the link to view the trace:

What's next?

• Look for instrumentations and browse examples.
• Learn about Tracing API and Metrics API to create your own instrumentations.