@unikvs/tracing

操作ごとにトレーススパンを発行するミドルウェアです。

概要

Tracing は読み書きや変換の操作ごとにトレーススパンを発行し、成否を記録します。use・encode・decode のスパンはフックチェーンの実行時間を測り、ストリームのスパンは読み切り・エラー・取り消しまで継続するため、ストリームの消費時間やストレージ読み取り時間を含むことがあります。Middleware

分散トレーシングや性能分析に使います。OpenTelemetry と構造的に互換性のあるトレーサーを渡して使います。

• name は Tracing です。
• isOpen は常に true です。
• スパンには key・action・success・durationMs を属性として含めます。
• encode・decode・ストリームはデータを透過し、スパンの発行のみ行います。

インストールは次のコマンドで行います。

npm install @unikvs/tracing

pnpm add @unikvs/tracing

yarn add @unikvs/tracing

bun add @unikvs/tracing

nub add @unikvs/tracing

aube add @unikvs/tracing

使い方

Tracing は IMiddleware を実装しています。UniKvs には use() で渡します。

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

コンストラクターの引数は次のとおりです。

以下は、カスタムトレーサーで操作を記録する例です。

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

操作ごとにトレーススパンを発行するミドルウェアです。use では操作ごとのスパン、encode・decode・ストリームでは変換ごとのスパンを発行します。

TracingOptions

Tracing のコンストラクターが受け取るオプションです。トレーサーとスパン名の接頭辞を指定できます。

SpanStatusCode

スパンの状態コードです。"unset"・"ok"・"error" のいずれかです。

SpanStatus

スパンに設定する状態です。

SpanAttributeValue

スパン属性に設定できる値の型です。string・number・boolean のいずれかです。

SpanLike

トレーサーから発行されるスパンの最小インターフェースです。OpenTelemetry の Span と構造的に互換性があります。

TracerLike

スパンを発行するトレーサーの最小インターフェースです。OpenTelemetry の Tracer と構造的に互換性があります。

データ型

• use は unikvs.use.<action> のスパンで下流の use フックチェーンを包み、ストレージ I/O は含みません。encode は unikvs.encode、decode は unikvs.decode のスパンで包みます。
• ストリームは unikvs.encodeStream・unikvs.decodeStream のスパンで包み、読み切り・エラー・取り消しのいずれかで終了します。
• チャンクはそのまま通し、順序と参照を保ちます。
• 成功時は success に true と状態 ok を設定し、失敗時は success に false と状態 error、メッセージを設定します。

エラー

このパッケージ固有のエラーはありません。

スパンの発行自体は例外を投げず、操作が失敗したときは、このミドルウェアは状態を error にして元のエラーを再送出します。トレーサーを省略した場合は何も記録せず、操作はそのまま通ります。