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.

• OpenTelemetry Node.js
• Configuration
• Getting started
• Automatic instrumentation
• What's next?

OpenTelemetry Node.js

# 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.

const uptrace = require('@uptrace/node')

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',
  })
  // Start OpenTelemetry SDK.
  .start()
  // Then execute the main function when SDK is ready.
  .then(main)

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.
WithDeploymentEnvironment	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>:

const otel = require('@opentelemetry/api')
const uptrace = require('@uptrace/node')

// Configure OpenTelemetry with sensible defaults.
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',
  })
  .start()
  .then(main)

function main() {
  // 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:

Automatic instrumentation

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

To register instrumentations, use the following code :

const uptrace = require('@uptrace/node')

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

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

  instrumentations: [
    {
      plugins: {
        express: {
          enabled: true,
          path: '@opentelemetry/plugin-express',
        },
      },
    },
  ],
})

What's next?

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