OTLP Export

Export traces to any OpenTelemetry-compatible backend with zero additional dependencies.

Overview

The OpenTelemetry Protocol (OTLP) is the standard wire format for sending telemetry data to observability backends. Vestig ships a built-in OTLP exporter that:

Zero dependencies — uses native fetch() instead of the heavy @opentelemetry/exporter-trace-otlp-http SDK
Batches and retries — automatically buffers spans and retries with exponential backoff
Edge-compatible — works on Cloudflare Workers, Vercel Edge Functions, and any runtime with fetch()
Universal backend support — Jaeger, Honeycomb, Grafana Cloud, Vercel, Datadog, Axiom, and any OTLP-compatible collector

Quick Start

typescript

1import { registerSpanProcessor, span } from 'vestig'
2import { OTLPExporter } from 'vestig/otlp'
3 
4const exporter = new OTLPExporter({
5  endpoint: 'https://otel.example.com/v1/traces',
6  serviceName: 'my-app',
7})
8 
9registerSpanProcessor(exporter)
10 
11// Your spans are now exported to the OTLP endpoint
12await span('db:query', async (s) => {
13  s.setAttribute('db.table', 'users')
14  return await db.select().from(users)
15})

Configuration Reference

Option	Type	Default	Description
`endpoint`	`string`	Required	OTLP endpoint URL for traces
`serviceName`	`string`	Required	Service name, maps to `service.name` resource attribute
`serviceVersion`	`string`	--	Service version, maps to `service.version`
`environment`	`string`	--	Deployment environment, maps to `deployment.environment`
`headers`	`Record<string, string>`	--	Custom HTTP headers for authentication
`resourceAttributes`	`Record<string, unknown>`	--	Additional OTLP resource attributes
`batchSize`	`number`	`100`	Max spans to batch before sending
`flushInterval`	`number`	`5000`	Interval in ms between automatic flushes
`timeout`	`number`	`30000`	Request timeout in ms
`maxRetries`	`number`	`3`	Maximum retry attempts on failure
`retryDelay`	`number`	`1000`	Initial retry delay in ms (doubles each attempt)
`enabled`	`boolean`	`true`	Enable/disable the exporter

The exporter also sets the following resource attributes automatically:

telemetry.sdk.name — vestig
telemetry.sdk.version — current Vestig version
telemetry.sdk.language — javascript

Backend-Specific Setup

Jaeger

Local development with Jaeger (default OTLP HTTP port):

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'http://localhost:4318/v1/traces',
5  serviceName: 'my-app',
6})

Honeycomb

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://api.honeycomb.io/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'x-honeycomb-team': process.env.HONEYCOMB_API_KEY!,
8  },
9})

Grafana Cloud

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://otlp-gateway-prod-us-east-0.grafana.net/otlp/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'Authorization': `Basic ${btoa(`${instanceId}:${process.env.GRAFANA_API_KEY}`)}`,
8  },
9})

Vercel

Vercel sets standard OpenTelemetry environment variables automatically:

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
5  serviceName: 'my-app',
6  environment: process.env.VERCEL_ENV,
7})

Datadog

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://trace.agent.datadoghq.com/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'DD-API-KEY': process.env.DD_API_KEY!,
8  },
9})

Axiom

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://api.axiom.co/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'Authorization': `Bearer ${process.env.AXIOM_API_TOKEN}`,
8    'X-Axiom-Dataset': 'traces',
9  },
10})

SpanProcessor Interface

The OTLPExporter implements the SpanProcessor interface, which is how Vestig notifies external systems about span lifecycle events.

typescript

1import type { SpanProcessor } from 'vestig'
2 
3interface SpanProcessor {
4  onStart?(span: Span): void
5  onEnd(span: Span): void
6  forceFlush?(): Promise<void>
7  shutdown?(): Promise<void>
8}

onStart — called when a span begins (optional, used for real-time streaming)
onEnd — called when a span finishes (required, this is where batching exporters collect spans)
forceFlush — send all buffered data immediately
shutdown — flush remaining data and release resources

Creating a Custom Processor

typescript

1import type { SpanProcessor } from 'vestig'
2import { registerSpanProcessor } from 'vestig'
3 
4const consoleProcessor: SpanProcessor = {
5  onStart(span) {
6    console.log(`[span:start] ${span.name}`)
7  },
8  onEnd(span) {
9    const duration = span.endTime! - span.startTime
10    console.log(`[span:end] ${span.name} (${duration.toFixed(1)}ms)`)
11  },
12  forceFlush() {
13    return Promise.resolve()
14  },
15  shutdown() {
16    return Promise.resolve()
17  },
18}
19 
20registerSpanProcessor(consoleProcessor)

Management Functions

Vestig provides global functions for managing all registered processors:

Function	Description
`registerSpanProcessor(processor)`	Register a processor globally
`unregisterSpanProcessor(processor)`	Remove a registered processor
`getSpanProcessors()`	List all registered processors
`flushSpanProcessors()`	Flush all processors (send buffered data)
`shutdownSpanProcessors()`	Shutdown all processors (flush and release)

All management functions are importable from vestig or vestig/otlp.

Graceful Shutdown

Always flush pending spans before your process exits. Undelivered spans in the buffer are lost if the process terminates without flushing.

typescript

1import { shutdownSpanProcessors } from 'vestig'
2 
3process.on('SIGTERM', async () => {
4  await shutdownSpanProcessors()
5  process.exit(0)
6})

For Next.js apps, place this in your instrumentation.ts:

typescript

1import { registerSpanProcessor, shutdownSpanProcessors } from 'vestig'
2import { OTLPExporter } from 'vestig/otlp'
3 
4export function register() {
5  const exporter = new OTLPExporter({
6    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
7    serviceName: 'my-app',
8  })
9 
10  registerSpanProcessor(exporter)
11 
12  process.on('SIGTERM', async () => {
13    await shutdownSpanProcessors()
14    process.exit(0)
15  })
16}

Error Handling

Export failures throw OTLPExportError, which provides structured error details:

typescript

1import { OTLPExportError } from 'vestig/otlp'

Properties

Property	Type	Description
`statusCode`	`number`	HTTP status code (`0` for network errors)
`responseBody`	`string \| undefined`	Response body from the backend, if available
`cause`	`Error \| undefined`	Underlying error (e.g., network failure)

Helper Getters

Getter	Returns `true` when
`isNetworkError`	Status code is `0` (fetch failed entirely)
`isTimeout`	Status code is `408` (request timed out)
`isClientError`	Status code is `4xx` (bad request, auth failure)
`isServerError`	Status code is `5xx` (backend unavailable)
`isRetryable`	Network error, timeout, or server error

The exporter automatically retries on retryable errors (network, timeout, 5xx) with exponential backoff. Client errors (4xx) are not retried since they indicate a configuration problem.

Advanced

Conversion Utilities

For advanced use cases, Vestig exports the low-level conversion functions used internally by the exporter:

typescript

1import {
2  toOTLPSpan,
3  toOTLPAttributes,
4  toOTLPAttributeValue,
5  toOTLPStatusCode,
6  msToNano,
7  isoToNano,
8} from 'vestig/otlp'

toOTLPSpan(span, epochStartMs) — convert a Vestig Span to the OTLP wire format
toOTLPAttributes(attrs) — convert a Record<string, unknown> to OTLP key-value pairs
toOTLPAttributeValue(value) — convert a single value to an OTLP attribute value
toOTLPStatusCode(status) — convert a Vestig span status to an OTLP status code
msToNano(ms) — convert milliseconds to nanosecond string (OTLP timestamp format)
isoToNano(isoString) — convert an ISO date string to nanosecond string

OTLP Enums

Standard OTLP enums are available for building custom payloads:

typescript

1import { OTLPStatusCode, OTLPSpanKind, OTLPSeverityNumber } from 'vestig/otlp'
2 
3OTLPStatusCode.UNSET   // 0
4OTLPStatusCode.OK      // 1
5OTLPStatusCode.ERROR   // 2
6 
7OTLPSpanKind.INTERNAL  // 1
8OTLPSpanKind.SERVER    // 2
9OTLPSpanKind.CLIENT    // 3
10OTLPSpanKind.PRODUCER  // 4
11OTLPSpanKind.CONSUMER  // 5
12 
13OTLPSeverityNumber.DEBUG  // 5
14OTLPSeverityNumber.INFO   // 9
15OTLPSeverityNumber.WARN   // 13
16OTLPSeverityNumber.ERROR  // 17
17OTLPSeverityNumber.FATAL  // 21

Edge Compatibility

The OTLP exporter works on Edge runtimes — Cloudflare Workers, Vercel Edge Functions, Deno Deploy — because it relies solely on the fetch() API rather than Node.js-specific modules like http or net.

For Edge environments, consider smaller batch sizes and shorter flush intervals since Edge functions have shorter execution windows:

typescript

1const exporter = new OTLPExporter({
2  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
3  serviceName: 'edge-api',
4  batchSize: 10,
5  flushInterval: 1000,
6  timeout: 5000,
7})

Tracing Overview — How tracing works in Vestig
Spans — Deep dive into the Span API
Context Propagation — AsyncLocalStorage-based context flow
Instrumentation — Unified Next.js setup with registerVestig()
Cloudflare & Edge — Edge runtime deployment guide

OTLP Export

Export traces to any OpenTelemetry-compatible backend with zero additional dependencies.

Overview

The OpenTelemetry Protocol (OTLP) is the standard wire format for sending telemetry data to observability backends. Vestig ships a built-in OTLP exporter that:

Zero dependencies — uses native fetch() instead of the heavy @opentelemetry/exporter-trace-otlp-http SDK
Batches and retries — automatically buffers spans and retries with exponential backoff
Edge-compatible — works on Cloudflare Workers, Vercel Edge Functions, and any runtime with fetch()
Universal backend support — Jaeger, Honeycomb, Grafana Cloud, Vercel, Datadog, Axiom, and any OTLP-compatible collector

Quick Start

typescript

1import { registerSpanProcessor, span } from 'vestig'
2import { OTLPExporter } from 'vestig/otlp'
3 
4const exporter = new OTLPExporter({
5  endpoint: 'https://otel.example.com/v1/traces',
6  serviceName: 'my-app',
7})
8 
9registerSpanProcessor(exporter)
10 
11// Your spans are now exported to the OTLP endpoint
12await span('db:query', async (s) => {
13  s.setAttribute('db.table', 'users')
14  return await db.select().from(users)
15})

Configuration Reference

Option	Type	Default	Description
`endpoint`	`string`	Required	OTLP endpoint URL for traces
`serviceName`	`string`	Required	Service name, maps to `service.name` resource attribute
`serviceVersion`	`string`	--	Service version, maps to `service.version`
`environment`	`string`	--	Deployment environment, maps to `deployment.environment`
`headers`	`Record<string, string>`	--	Custom HTTP headers for authentication
`resourceAttributes`	`Record<string, unknown>`	--	Additional OTLP resource attributes
`batchSize`	`number`	`100`	Max spans to batch before sending
`flushInterval`	`number`	`5000`	Interval in ms between automatic flushes
`timeout`	`number`	`30000`	Request timeout in ms
`maxRetries`	`number`	`3`	Maximum retry attempts on failure
`retryDelay`	`number`	`1000`	Initial retry delay in ms (doubles each attempt)
`enabled`	`boolean`	`true`	Enable/disable the exporter

The exporter also sets the following resource attributes automatically:

telemetry.sdk.name — vestig
telemetry.sdk.version — current Vestig version
telemetry.sdk.language — javascript

Backend-Specific Setup

Jaeger

Local development with Jaeger (default OTLP HTTP port):

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'http://localhost:4318/v1/traces',
5  serviceName: 'my-app',
6})

Honeycomb

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://api.honeycomb.io/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'x-honeycomb-team': process.env.HONEYCOMB_API_KEY!,
8  },
9})

Grafana Cloud

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://otlp-gateway-prod-us-east-0.grafana.net/otlp/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'Authorization': `Basic ${btoa(`${instanceId}:${process.env.GRAFANA_API_KEY}`)}`,
8  },
9})

Vercel

Vercel sets standard OpenTelemetry environment variables automatically:

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
5  serviceName: 'my-app',
6  environment: process.env.VERCEL_ENV,
7})

Datadog

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://trace.agent.datadoghq.com/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'DD-API-KEY': process.env.DD_API_KEY!,
8  },
9})

Axiom

typescript

1import { OTLPExporter } from 'vestig/otlp'
2 
3const exporter = new OTLPExporter({
4  endpoint: 'https://api.axiom.co/v1/traces',
5  serviceName: 'my-app',
6  headers: {
7    'Authorization': `Bearer ${process.env.AXIOM_API_TOKEN}`,
8    'X-Axiom-Dataset': 'traces',
9  },
10})

SpanProcessor Interface

The OTLPExporter implements the SpanProcessor interface, which is how Vestig notifies external systems about span lifecycle events.

typescript

1import type { SpanProcessor } from 'vestig'
2 
3interface SpanProcessor {
4  onStart?(span: Span): void
5  onEnd(span: Span): void
6  forceFlush?(): Promise<void>
7  shutdown?(): Promise<void>
8}

onStart — called when a span begins (optional, used for real-time streaming)
onEnd — called when a span finishes (required, this is where batching exporters collect spans)
forceFlush — send all buffered data immediately
shutdown — flush remaining data and release resources

Creating a Custom Processor

typescript

1import type { SpanProcessor } from 'vestig'
2import { registerSpanProcessor } from 'vestig'
3 
4const consoleProcessor: SpanProcessor = {
5  onStart(span) {
6    console.log(`[span:start] ${span.name}`)
7  },
8  onEnd(span) {
9    const duration = span.endTime! - span.startTime
10    console.log(`[span:end] ${span.name} (${duration.toFixed(1)}ms)`)
11  },
12  forceFlush() {
13    return Promise.resolve()
14  },
15  shutdown() {
16    return Promise.resolve()
17  },
18}
19 
20registerSpanProcessor(consoleProcessor)

Management Functions

Vestig provides global functions for managing all registered processors:

Function	Description
`registerSpanProcessor(processor)`	Register a processor globally
`unregisterSpanProcessor(processor)`	Remove a registered processor
`getSpanProcessors()`	List all registered processors
`flushSpanProcessors()`	Flush all processors (send buffered data)
`shutdownSpanProcessors()`	Shutdown all processors (flush and release)

All management functions are importable from vestig or vestig/otlp.

Graceful Shutdown

Always flush pending spans before your process exits. Undelivered spans in the buffer are lost if the process terminates without flushing.

typescript

1import { shutdownSpanProcessors } from 'vestig'
2 
3process.on('SIGTERM', async () => {
4  await shutdownSpanProcessors()
5  process.exit(0)
6})

For Next.js apps, place this in your instrumentation.ts:

typescript

1import { registerSpanProcessor, shutdownSpanProcessors } from 'vestig'
2import { OTLPExporter } from 'vestig/otlp'
3 
4export function register() {
5  const exporter = new OTLPExporter({
6    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
7    serviceName: 'my-app',
8  })
9 
10  registerSpanProcessor(exporter)
11 
12  process.on('SIGTERM', async () => {
13    await shutdownSpanProcessors()
14    process.exit(0)
15  })
16}

Error Handling

Export failures throw OTLPExportError, which provides structured error details:

typescript

1import { OTLPExportError } from 'vestig/otlp'

Properties

Property	Type	Description
`statusCode`	`number`	HTTP status code (`0` for network errors)
`responseBody`	`string \| undefined`	Response body from the backend, if available
`cause`	`Error \| undefined`	Underlying error (e.g., network failure)

Helper Getters

Getter	Returns `true` when
`isNetworkError`	Status code is `0` (fetch failed entirely)
`isTimeout`	Status code is `408` (request timed out)
`isClientError`	Status code is `4xx` (bad request, auth failure)
`isServerError`	Status code is `5xx` (backend unavailable)
`isRetryable`	Network error, timeout, or server error

The exporter automatically retries on retryable errors (network, timeout, 5xx) with exponential backoff. Client errors (4xx) are not retried since they indicate a configuration problem.

Advanced

Conversion Utilities

For advanced use cases, Vestig exports the low-level conversion functions used internally by the exporter:

typescript

1import {
2  toOTLPSpan,
3  toOTLPAttributes,
4  toOTLPAttributeValue,
5  toOTLPStatusCode,
6  msToNano,
7  isoToNano,
8} from 'vestig/otlp'

toOTLPSpan(span, epochStartMs) — convert a Vestig Span to the OTLP wire format
toOTLPAttributes(attrs) — convert a Record<string, unknown> to OTLP key-value pairs
toOTLPAttributeValue(value) — convert a single value to an OTLP attribute value
toOTLPStatusCode(status) — convert a Vestig span status to an OTLP status code
msToNano(ms) — convert milliseconds to nanosecond string (OTLP timestamp format)
isoToNano(isoString) — convert an ISO date string to nanosecond string

OTLP Enums

Standard OTLP enums are available for building custom payloads:

typescript

1import { OTLPStatusCode, OTLPSpanKind, OTLPSeverityNumber } from 'vestig/otlp'
2 
3OTLPStatusCode.UNSET   // 0
4OTLPStatusCode.OK      // 1
5OTLPStatusCode.ERROR   // 2
6 
7OTLPSpanKind.INTERNAL  // 1
8OTLPSpanKind.SERVER    // 2
9OTLPSpanKind.CLIENT    // 3
10OTLPSpanKind.PRODUCER  // 4
11OTLPSpanKind.CONSUMER  // 5
12 
13OTLPSeverityNumber.DEBUG  // 5
14OTLPSeverityNumber.INFO   // 9
15OTLPSeverityNumber.WARN   // 13
16OTLPSeverityNumber.ERROR  // 17
17OTLPSeverityNumber.FATAL  // 21

Edge Compatibility

For Edge environments, consider smaller batch sizes and shorter flush intervals since Edge functions have shorter execution windows:

typescript

1const exporter = new OTLPExporter({
2  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
3  serviceName: 'edge-api',
4  batchSize: 10,
5  flushInterval: 1000,
6  timeout: 5000,
7})

Tracing Overview — How tracing works in Vestig
Spans — Deep dive into the Span API
Context Propagation — AsyncLocalStorage-based context flow
Instrumentation — Unified Next.js setup with registerVestig()
Cloudflare & Edge — Edge runtime deployment guide

OTLP Export

Overview

Quick Start

Configuration Reference

Backend-Specific Setup

Jaeger

Honeycomb

Grafana Cloud

Vercel

Datadog

Axiom

SpanProcessor Interface

Creating a Custom Processor

Management Functions

Graceful Shutdown

Error Handling

Properties

Helper Getters

Advanced

Conversion Utilities

OTLP Enums

Edge Compatibility

Related

OTLP Export

Overview

Quick Start

Configuration Reference

Backend-Specific Setup

Jaeger

Honeycomb

Grafana Cloud

Vercel

Datadog

Axiom

SpanProcessor Interface

Creating a Custom Processor

Management Functions

Graceful Shutdown

Error Handling

Properties

Helper Getters

Advanced

Conversion Utilities

OTLP Enums

Edge Compatibility

Related