OpenTelemetry Node.js distro for Uptrace

uptrace-jsopen in new window configures opentelemetry-jsopen in new window to export spans and metrics to Uptrace using OpenTelemetry protocol (OTLP).

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://<key>@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://<key>@uptrace.dev/<project_id>',
    serviceName: 'myservice',
    serviceVersion: '1.0.0',
  })
  // 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.

OptionDescription
dsnA data source that is used to connect to uptrace.dev. For example, https://<key>@uptrace.dev/<project_id>.
serviceNameservice.name resource attribute. For example, myservice.
serviceVersionservice.version resource attribute. For example, 1.0.0.
resourceAttributesAny other resource attributes.
resourceResource 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 varDescription
UPTRACE_DSNA data source that is used to connect to uptrace.dev. For example, https://<key>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_PROPAGATORSPropagators 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.

# npm
npm install @uptrace/node --save

# yarn
yarn add @uptrace/node --save
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://<key>@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()
  })
}
node main.js
https://uptrace.dev/search/<project_id>?q=<trace_id>
  • Step 4. Follow the link to view the trace:

Basic trace

Using automatic instrumentation

Whenever you load a module, OpenTelemetry checks if there a matching instrumentation pluginopen in new window 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://<key>@uptrace.dev/<project_id>',

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

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

What's next?