Uptrace for Node.js¶

This document describes Uptrace for Node.js. For Web browsers see @uptrace/web.

Installation¶

npm:

npm install @uptrace/node --save

yarn:

yarn add @uptrace/node --save

Introduction¶

@uptrace/node is the official Uptrace client for Node.js that sends your traces/spans to Uptrace.

To learn about tracing, please see Introduction to distributed tracing.

Configuring Uptrace client¶

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

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

# Set dsn or UPTRACE_DSN env var.
const dsn = ''

const upclient = uptrace.createClient({
  dsn,
})

The following example shows how to create a tracer, start spans and add events:

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

const upclient = uptrace.createClient()

// Report an exception.
upclient.reportException(new Error('hello from @uptrace/node), {
  foo: 'bar',
})

const tracer = upclient.getTracer('github.com/uptrace/uptrace-js')

// Start a root/main span (span without a parent).
const mainSpan = tracer.startSpan('main span')

// Activate main span.
tracer.withSpan(mainSpan, () => {
  // span1 is a child of mainSpan.
  const span1 = tracer.startSpan('span1', {
    parent: tracer.getCurrentSpan(),
  })

  // Activate span1.
  tracer.withSpan(span1, () => {
    const span = tracer.getCurrentSpan() // == span1
    span.setAttribute('key1', 'value1')
    span.addEvent('event-name')
    span.end()
  })

  // span2 is a child of mainSpan.
  const span2 = tracer.startSpan('span2', {
    parent: tracer.getCurrentSpan(),
  })

  // Activate span2.
  tracer.withSpan(span2, () => {
    const span = tracer.getCurrentSpan() // == span2
    span.setAttribute('key2', 'value2')
    span.addEvent('event-name')
    span.end()
  })

  const span = tracer.getCurrentSpan() // == mainSpan
  span.end()
})

// Flush and close the client.
upclient.close()

Instrumenting your code¶

To report exceptions directly (without a span):

upclient.reportException(new Error('hello world'), {
  key1: 'value1',
  key2: 'value2',
})

To create a tracer:

const tracer = upclient.getTracer('github.com/my/repo')

To create a span:

// Main/root span.
const span = tracer.startSpan('span-name')

// Span with a parent.
const span2 = tracer.startSpan('span2', {
  parent: span,
})

To get the active span:

const span = tracer.getCurrentSpan()

To activate the span (make the span active):

tracer.withSpan(span, () => {
  console.log(tracer.getCurrentSpan() === span)
})

Once you have a span you can start adding attributes:

// Single attribute.
span.setAttribute('key1', 'value1')

// Multiple attributes.
span.setAttributes({
  key1: 'value1',
  key2: 'value2',
})

And more complex events:

span.addEvent('event-name', {
  key1: 'value1',
  key2: 'value2',
})

To record an exception:

span.recordException(new Error('hello world'))

Using automatic instrumentation¶

Uptrace client comes with opentelemetry-node to provide automatic instrumentation for popular modules. To make auto-instrumentation work, make sure to initialize Uptrace client before loading any other module.

Whenever you load a module, OpenTelemetry checks if there a matching instrumentation plugin and uses it to automatically patch the original module. It also prompts you to install missing instrumentation plugins. For example, for Express.js you need to install @opentelemetry/plugin-express:

npm install @opentelemetry/plugin-express --save

You can also check already instrumented node-express-realworld-example-app.

Instrumenting express¶

OpenTelemetry automatically instruments Express after plugin is installed:

npm install @opentelemetry/plugin-express --save

Instrumenting mongoose¶

There is no official OpenTelemetry plugin for mongoose yet, but there is a community plugin provided by @wdalmut/opentelemetry-plugin-mongoose:

npm install @wdalmut/opentelemetry-plugin-mongoose --save

Add add plugin info to the client config:

const upclient = uptrace.createClient({
  dsn: 'https://<token>@api.uptrace.dev/<project_id>',

  plugins: {
    mongoose: {
      enabled: true,
      path: '@wdalmut/opentelemetry-plugin-mongoose',
    },
  },
})