Skip to content
Node.js

Export traces from Node.js

Add BTX export to your existing trace provider.

Install

Requires Node.js 20.6 or later, OpenTelemetry API 1.9.x, and trace SDK 2.9.x or later in the 2.x series.

bash
pnpm add @btx-second-context/otel '@opentelemetry/api@~1.9.0' '@opentelemetry/sdk-trace@^2.9.0'

Create a project API key and make it available to your backend as BTX_API_KEY. This package exports existing spans; your application still owns instrumentation and its provider.

Add the processor

Add btxProcessor to your existing provider's spanProcessors array before starting the SDK. Keep your other processors, including Langfuse's, registered. Initialize the provider once, before loading instrumented application modules.

For an application that already uses NodeSDK from @opentelemetry/sdk-node, update its existing configuration:

typescript
import { NodeSDK } from '@opentelemetry/sdk-node'
import { BtxSpanProcessor } from '@btx-second-context/otel'

const btxProcessor = new BtxSpanProcessor({
  apiKey: process.env.BTX_API_KEY,
})

const sdk = new NodeSDK({
  spanProcessors: [
    btxProcessor,
    // Keep your existing processors here.
  ],
  // Keep your existing instrumentation, resource, and sampler options.
})
sdk.start()

Observe export results

To report delivery without logging span content, add onExport to the processor from the setup example. Register only one BTX processor.

typescript
const btxProcessor = new BtxSpanProcessor({
  apiKey: process.env.BTX_API_KEY,
  onExport(result) {
    console.info('BTX export', {
      outcome: result.outcome,
      spans: result.spans,
      reason: result.reason,
      httpStatus: result.httpStatus,
    })
  },
})

Outcomes are accepted, failed, overflow, and projection_failed. reason and httpStatus are present when available. Keep the callback fast and avoid instrumented work inside it. Without a callback, hosted export failures use bounded console warnings.

onExport does not expose partial-success rejection counts. Use OpenTelemetry diagnostics to investigate partial acknowledgments. See receiver troubleshooting for HTTP errors.

Verify delivery

Run an existing instrumented request or job. After its spans finish, flush the BTX processor:

typescript
try {
  await btxProcessor.forceFlush()
} catch {
  console.warn('BTX export did not complete successfully')
}

Find the trace in BTX Telemetry. With Langfuse export enabled, check the same trace ID in both destinations.

Before a serverless runtime pauses, await the flush after all traced work finishes. It can reject on export failure or timeout; handle that separately from the feature's result. A completed flush is not a per-span storage receipt. During application shutdown, await sdk.shutdown().

Control exported data

The npm package has no filtering or masking hooks. Remove sensitive data in your instrumentation, or use an application-owned export adapter that sanitizes BTX's copy. Langfuse policies do not apply to BTX. Review span names, attributes, events, links, and resource metadata before enabling export.

Advanced: Configure delivery

Delivery tuning is optional. Start with the defaults and override only the settings your workload needs. For example, to shorten the export interval from 30 seconds to 5 seconds, replace the basic processor configuration with:

typescript
const btxProcessor = new BtxSpanProcessor({
  apiKey: process.env.BTX_API_KEY,
  scheduledDelayMillis: 5_000, // Export every 5 seconds.
})

Keep the same provider registration and register only one BTX processor. Hosted BTX export supports these delivery options:

OptionDefault
maxQueueSize512 pending spans, including export in progress
maxExportBatchSize128 spans
scheduledDelayMillis30,000 ms
exportTimeoutMillis15,000 ms

Values must be positive safe integers, and maxExportBatchSize must not exceed maxQueueSize. Queue size controls buffering during bursts; batch size controls spans per request. A shorter interval can make traces appear sooner but increases request frequency. exportTimeoutMillis bounds HTTP export attempts; flushTimeoutMillis separately controls how long a flush waits and defaults to 20,000 ms.

The npm package also accepts maxQueueBytes (default 4 MiB) and maxSpanBytes (default 128 KiB). These byte budgets use conservative size estimates; the receiver also checks its own limits. Exceeding a budget drops spans rather than truncating them. The queue is in memory, and transport retries are bounded.

With apiKey, the package configures BTX's endpoint and authorization independently of shared OTLP settings. For an application-managed destination, use either the otlp exporter configuration or a custom exporter instead; these options are mutually exclusive with apiKey.