OpenTelemetry Sink

The OpenTelemetry sink creates a span for each session using your existing @opentelemetry/api tracer. WriteTrack doesn’t bundle the OpenTelemetry SDK — you provide your initialized tracer.

Prerequisites

You need @opentelemetry/api v1.0.0 or later (and a configured exporter) already initialized in your application.

npm

npm i @opentelemetry/api @opentelemetry/sdk-trace-web

pnpm

pnpm add @opentelemetry/api @opentelemetry/sdk-trace-web

yarn

yarn add @opentelemetry/api @opentelemetry/sdk-trace-web

bun

bun add @opentelemetry/api @opentelemetry/sdk-trace-web

Setup

import { WriteTrack, opentelemetry } from 'writetrack';
import { trace } from '@opentelemetry/api';

// Get your tracer (from your existing OTel setup)
const tracer = trace.getTracer('writetrack');

const tracker = new WriteTrack({
  target: textarea,
  userId: 'u_abc123',
});

tracker.pipe(
  opentelemetry({
    tracer,
  })
);

tracker.start();

Options

Option	Type	Default	Description
tracer	OTelTracer	—	Initialized OpenTelemetry tracer Required
spanName	string	'writetrack.session'	Custom span name

Data Mapping

The sink creates a span and sets the following attributes:

Attribute	Source	Type	Description
writetrack.duration	metadata.duration	number	Session duration in ms
writetrack.keystroke_count	session.events.length	number	Total keystroke events
writetrack.quality_level	quality.qualityLevel	string	Quality assessment
writetrack.target_element	metadata.targetElement	string	Element type
writetrack.schema_version	version	string	Schema version
writetrack.user_id	metadata.userId	string	User ID (if provided)
writetrack.content_id	metadata.contentId	string	Content ID (if provided)

The span status is set to OK (code 1) on success.

Examples

With Custom Span Name

tracker.pipe(
  opentelemetry({
    tracer,
    spanName: 'typing.session.captured',
  })
);

Viewing Traces

The span appears in your tracing backend (Jaeger, Zipkin, Honeycomb, Grafana Tempo, etc.) under the tracer name you configured. Filter by:

• Span name: writetrack.session
• Attribute: writetrack.quality_level = EXCELLENT
• Attribute: writetrack.user_id = u_abc123

Error Handling

The span is always ended in a finally block, even if setting attributes fails. Errors are caught and emitted as pipe:error events.

tracker.on('pipe:error', (err, sink) => {
  console.error('OpenTelemetry sink failed:', err);
});