@unikvs/metrics

操作の件数とバイト数、use フックの実行時間を記録し、OTel や Prometheus へ転送できるミドルウェアです。

概要

Metrics は操作の件数とバイト数、use フックの実行時間を記録し、集計と外部転送を行います。この実行時間にストレージ I/O の遅延は含みません。Middleware

性能の可視化や運用監視に使います。測定値はメモリーに保持され、必要に応じて OTel の計器やカスタム出力先へ転送されます。

• name は Metrics です。
• isOpen は常に true です。
• use は各操作の前段で use フックチェーンの成否と実行時間を測定します。この実行時間にストレージ I/O の遅延は含みません。encode・decode・ストリームではバイト数も記録します。
• 記録処理は決して例外を投げず、出力先の失敗は無視します。

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

npm install @unikvs/metrics @opentelemetry/api

pnpm add @unikvs/metrics @opentelemetry/api

yarn add @unikvs/metrics @opentelemetry/api

bun add @unikvs/metrics @opentelemetry/api

nub add @unikvs/metrics @opentelemetry/api

aube add @unikvs/metrics @opentelemetry/api

@opentelemetry/api は exporter に "otel" を指定するときのみ必要です。Prometheus 形式の出力 (toPrometheusString()) やメモリー集計のみでは不要です。

使い方

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

import { Metrics } from "@unikvs/metrics";

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

以下は、操作を測定し、集計を取得する例です。

import { Memory } from "@unikvs/memory";
import { Metrics } from "@unikvs/metrics";
import * as unikvs from "unikvs";

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

await kvs.open();
await kvs.set("k1", "hello");
console.log(metrics.getMetrics().total); // 記録件数
console.log(metrics.toPrometheusString()); // Prometheus 形式
await kvs.close();

Metrics

操作のメトリクスを記録するミドルウェアです。測定値はメモリーに保持され、getMetrics() と toPrometheusString() で取得できます。

MetricsOptions

Metrics のコンストラクターが受け取るオプションです。エクスポーターや時計を指定できます。

MetricsAction

メトリクスミドルウェアが観測する操作名です。IMiddleware.UseContext["action"] と等価です。

MetricsOutcome

観測した use フックチェーン、または encode・decode・ストリームの成否を表します。"success" か "error" です。use の場合はストレージ操作の成否ではありません。

MetricsExporterKind

名前で選択する組み込みのエクスポーターです。"otel" は計器への転送を指し、"prometheus" はメモリー保持とテキスト出力を指します。

MetricsExporter

記録されたすべての測定値を受け取るカスタム出力先です。

MetricRecord

1 回のフック実行で観測した測定値です。

MetricsActionSummary

操作名ごとに集計したカウンターです。

MetricsSnapshot

これまでに記録したすべての測定値のスナップショットです。

データ型

• use は操作ごとに 1 件を記録し、バイト数は undefined です。durationMs は use フックチェーンの実行時間で、ストレージ I/O の遅延は含みません。
• use フックの後に実行されるストレージ I/O の失敗は、use の記録に反映されません。プレーン値の set の書き込み失敗、存在しないキー以外の get の読み取り失敗、stream の取得や存在しないキーの失敗、delete・has・clear・copy・move の失敗が該当します。
• Metrics がエラーとして記録するのは、フック自体の失敗と、ラップ後のストリームの読み取り失敗・取り消しです。存在しないキーの get もエラーとしては記録されません。プレーン値の set がエンコード中に失敗した場合は、use の success と encode の error が並びます。
• ストリームの記録は、ストリームの完了、読み取り失敗、取り消しのいずれか早い時点で確定します。完了は success、読み取り失敗と取り消しは error です。完了前に書き込み先の失敗などでストリームが取り消された場合も error になります。確定後の失敗は反映されず、ソースがラップ前にロックされていた場合は何も記録されません。
• ストリームの durationMs は、ラップからソース (変換) の完了・読み取り失敗・取り消しによる確定までの時間で、ストリームの消費時間を含むことがあります。ここでの完了はソース (変換) の完了を指し、destination の読み切りを意味しません。use・encode・decode の durationMs はフックチェーンの実行時間です。
• Metrics は afterUse を実装していないため、書き込み系操作の成否を別レコードとして出力しません。コアの use はストレージ I/O の前に実行されるため、どのミドルウェアでも use からストレージ操作の成否を観測できません。コアには、ストレージ I/O の確定後に成否を受け取る afterUse フックがあります。
• encode と decode はデータをそのまま通し、文字列や ArrayBuffer、ArrayBufferView ではバイト数も記録します。不明な型では undefined です。
• ストリームではチャンクをそのまま通し、確定時にそれまでの合計チャンクサイズを 1 件として記録します。
• このミドルウェアはキーラベルを意図的に省略し、toPrometheusString() のカーディナリティーが増えないようにしています。キーごとの詳細は getMetrics() と onRecord から取得できます。

エラー

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

記録処理は例外を投げず、出力先の失敗は無視するため、メトリクスが操作のパイプラインを壊すことはありません。フックの実行中にエラーが発生したときは、error を記録してからそのエラーを再送出します。ストリームでは、読み取り中の失敗や取り消しも error として記録します。ただし、use はストレージ I/O の前に完了するため、ストレージ操作の失敗は use の記録には反映されません。