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