OpenTelemetry JavaScript distro for Uptrace

This document explains how to configure the OpenTelemetry JavaScript SDK to export spans (traces), logs, and metrics to Uptrace using OTLP/HTTP.

Choose Your Setup Path

Option A: Node.js Applications

Best for: Server-side JavaScript, backend services, APIs

uptrace-js is a thin wrapper over opentelemetry-js that configures the OpenTelemetry SDK to export data to Uptrace. It does not add any new functionality and is provided only for your convenience.

Quick Start below | Detailed Node.js Guide

Option B: Browser Applications

Best for: Client-side web apps, SPAs, frontend monitoring

Browser SDK Setup

Quick Start Guide

Follow these steps to get your first trace running in 5 minutes:

Step 1: Create an Uptrace Project

Create an Uptrace project to obtain a DSN (Data Source Name), for example, https://<secret>@api.uptrace.dev?grpc=4317.

Step 2: Install @uptrace/node

shell npm
npm install @uptrace/node --save
shell yarn
yarn add @uptrace/node --save

Step 3: Basic Configuration

Configure the Uptrace client using a DSN (Data Source Name) from the project settings page. Replace <FIXME> with your actual Uptrace DSN, and myservice with a name that identifies your application.

js
// The very first import must be Uptrace and/or OpenTelemetry.
const uptrace = require('@uptrace/node')
const otel = require('@opentelemetry/api')

// Start OpenTelemetry SDK and invoke instrumentations to patch the code.
const sdk = uptrace.configureOpentelemetry({
  // Copy your project DSN here or use UPTRACE_DSN env var
  //dsn: '<FIXME>',
  serviceName: 'myservice',
  serviceVersion: '1.0.0',
  deploymentEnvironment: 'production',
})
sdk.start()

Step 4: Create Your First Trace

Copy the code to main.js:

js
'use strict'

// The very first import must be Uptrace/OpenTelemetry.
const otel = require('@opentelemetry/api')
const uptrace = require('@uptrace/node')

// Start OpenTelemetry SDK and invoke instrumentations to patch the code.
const sdk = uptrace.configureOpentelemetry({
  // Set dsn or UPTRACE_DSN env var.
  //dsn: '<FIXME>',
  serviceName: 'myservice',
  serviceVersion: '1.0.0',
})
sdk.start()

// 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('GET /posts/:id', (child1) => {
    child1.setAttribute('http.method', 'GET')
    child1.setAttribute('http.route', '/posts/:id')
    child1.setAttribute('http.url', 'http://localhost:8080/posts/123')
    child1.setAttribute('http.status_code', 200)
    child1.recordException(new Error('error1'))
    child1.end()
  })

  tracer.startActiveSpan('SELECT', (child2) => {
    child2.setAttribute('db.system', 'mysql')
    child2.setAttribute('db.statement', 'SELECT * FROM posts LIMIT 100')
    child2.end()
  })

  // End the span when the operation we are measuring is done.
  main.end()

  console.log(sdk.traceUrl(main))
})

setTimeout(async () => {
  // Send buffered spans and free resources.
  await sdk.shutdown()
})

Step 5: Run Your Application

Execute the example, replacing <FIXME> with your Uptrace DSN:

shell
$ UPTRACE_DSN="<FIXME>" node main.js
https://app.uptrace.dev/traces/<trace_id>

Step 6: View Your Trace

Click the generated link to view your trace in the Uptrace dashboard:

Basic trace

Configuration Options

You can find the full list of available options at the @uptrace/node repository.

OptionDescription
dsnA data source that specifies Uptrace project credentials. For example, https://<secret>@api.uptrace.dev?grpc=4317.
serviceNameservice.name resource attribute. For example, myservice.
serviceVersionservice.version resource attribute. For example, 1.0.0.
deploymentEnvironmentdeployment.environment resource attribute. For example, production.
resourceAttributesAny other resource attributes.
resourceResource attributes representing an entity that produces telemetry.
instrumentationsCustom instrumentations to register.

What's Next?

Instrument more operations to get a detailed picture of your application. Prioritize network calls, database queries, errors, and logs.

By Use Case

I want to...Read this
Instrument without code changesZero-code instrumentation
Learn more about Node.js setupNode.js SDK
Instrument browser applicationsBrowser SDK
Use OTLP exporter directlyDirect OTLP Configuration
Instrument my code with spansTracing API
Collect application metricsMetrics API
Send logs to UptraceLogs integration
Enable distributed tracingContext propagation
Reduce costs in productionSampling strategies
Auto-detect cloud environmentResource detectors

Framework Guides