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',
},
},
})