@unikvs/tracing

Middleware that emits a trace span per operation.

Overview

Tracing emits a trace span for each read, write, and conversion operation and records success. use, encode, and decode spans measure hook-chain duration; stream spans run until the stream is fully consumed, fails, or is cancelled, and can include stream consumption or storage read time.Middleware

Use it for distributed tracing and performance analysis. Pass a structurally OpenTelemetry-compatible tracer.

• name is Tracing.
• isOpen is always true.
• Spans carry key, action, success, and durationMs as attributes.
• encode / decode and streams pass data through and only emit spans.

Install with:

npm install @unikvs/tracing

pnpm add @unikvs/tracing

yarn add @unikvs/tracing

bun add @unikvs/tracing

nub add @unikvs/tracing

aube add @unikvs/tracing

Usage

Tracing implements IMiddleware. Pass it to UniKvs with use().

import { Tracing } from "@unikvs/tracing";

Constructor arguments:

The following records operations with a custom tracer:

import { Memory } from "@unikvs/memory";
import { Tracing, type TracerLike } from "@unikvs/tracing";
import * as unikvs from "unikvs";

const tracer: TracerLike = {
  startSpan: (name) => ({
    setAttribute: () => {},
    setStatus: () => {},
    end: () => {},
  }),
};

const kvs = new unikvs.Builder<{ k1: unikvs.PlainValue<string> }>()
  .use(new Tracing({ tracer }))
  .persist(new Memory())
  .build();

await kvs.open();
await kvs.set("k1", "hello");
console.log(await kvs.get("k1")); // "hello"
await kvs.close();

Tracing

Middleware that emits a trace span per operation. use emits one span per operation; encode / decode and streams emit one span per conversion.

TracingOptions

Options accepted by the Tracing constructor. Specifies the tracer and the span-name prefix.

SpanStatusCode

Span status code. One of "unset", "ok", or "error".

SpanStatus

Status set on a span.

SpanAttributeValue

Value type settable as a span attribute. One of string, number, or boolean.

SpanLike

Minimal interface of spans issued by a tracer. Structurally compatible with OpenTelemetry Span.

TracerLike

Minimal interface of tracers that emit spans. Structurally compatible with OpenTelemetry Tracer.

Data types

• use wraps the downstream use hook chain in a unikvs.use.<action> span; storage I/O is not included. encode uses unikvs.encode and decode uses unikvs.decode.
• Streams are wrapped in unikvs.encodeStream / unikvs.decodeStream spans, ending on full read, error, or cancellation.
• Chunks pass through unchanged, preserving order and references.
• Success sets success to true with status ok; failure sets success to false with status error and a message.

Errors

This package has no package-specific errors.

Span emission itself never throws. When an operation fails, this middleware marks the status error and rethrows the original error. When no tracer is given, operations pass through with nothing recorded.