※本記事には広告(楽天アフィリエイト)リンクが含まれる場合があります。
「本番でエラーが出たけど再現できない」「APIのどこで遅くなっているか分からない」「AIアプリのトークン消費がどこで増えているか把握できない」——個人開発でもサービスが育ってくると、こんな悩みが出てきます。
これを解決するのがオブザーバビリティ(可観測性)。そしてそのオープンスタンダードが OpenTelemetry(OTel) です。もともとGoogleやMicrosoftが主導してCNCFに寄贈したプロジェクトで、2026年現在は事実上の業界標準となりました。
本記事では、OpenTelemetryの基本概念から Node.js/TypeScript での実装、Hono との組み合わせ、そして個人開発者でも使える無料枠のある SaaS へのエクスポートまで、動くコードを交えて解説します。
OpenTelemetryとは?3つの柱を理解する
OpenTelemetry(OTel)は、アプリケーションのテレメトリデータを収集・エクスポートするためのオープンソースのフレームワーク&APIセットです。CNCFのグラデュエーテッドプロジェクトで、ベンダーロックインなしに複数のバックエンドへデータを送れます。
オブザーバビリティは次の3つの柱(Three Pillars)で構成されます。
| 柱 | 何が分かるか | 代表的なツール |
|---|---|---|
| トレース(Traces) | リクエストがどのサービス・関数を通ったか、各ステップの所要時間 | Jaeger, Zipkin, Grafana Tempo |
| メトリクス(Metrics) | カウンタ・ゲージ・ヒストグラム形式の集計値(RPM、レイテンシ分布など) | Prometheus, Grafana |
| ログ(Logs) | 任意のイベント・エラー情報。トレースIDと紐づけると強力 | Loki, Elasticsearch |
OpenTelemetry の強みは、この3つを1つの SDK で統一的に扱えること、そして送り先(バックエンド)を後から自由に変えられることです。
OpenTelemetryのアーキテクチャ
OTel の全体像はシンプルです。
アプリ(SDK)
│
├─ OTLP(OpenTelemetry Protocol)
│
▼
OTel Collector(オプション)
│
├─ Jaeger / Grafana Tempo(トレース)
├─ Prometheus / Grafana(メトリクス)
└─ Loki / Datadog(ログ)
- SDK:アプリに組み込むライブラリ。自動計装と手動計装の両方に対応
- Collector:受信・変換・転送を担うプロキシ。本番では挟む、開発では省略も可
- OTLP:gRPCまたはHTTP/JSONで通信する標準プロトコル
個人開発では Collector を省いて SDK から直接 SaaS へ送るのが手軽です。
Node.js / TypeScript でクイックスタート
まずは最小構成で動かしてみます。Hono + Cloudflare Workers ではなく、まず Node.js で概念を掴みましょう。
パッケージのインストール
npm install \
@opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http \
@opentelemetry/exporter-metrics-otlp-http
instrumentation.ts(エントリーポイントより前に読み込む)
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
const sdk = new NodeSDK({
serviceName: 'my-app',
traceExporter: new OTLPTraceExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + '/v1/traces',
headers: { Authorization: `Bearer ${process.env.OTEL_API_KEY}` },
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + '/v1/metrics',
headers: { Authorization: `Bearer ${process.env.OTEL_API_KEY}` },
}),
exportIntervalMillis: 60_000,
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
auto-instrumentations-node を入れるだけで、http/https・fetch・Express・Hono・Prisma・MySQL・PostgreSQLなど主要ライブラリが自動で計装されます。コードを1行も変えずにトレースが取れるのが大きな利点です。
起動時に読み込む
# tsxの場合
node --import ./instrumentation.js dist/server.js
# または package.json scripts
"start": "node --import ./dist/instrumentation.js dist/server.js"
手動スパン:重要な処理を計測する
自動計装では取れない「ビジネスロジックの処理時間」は、手動スパンで追加します。
import { trace, SpanStatusCode } from '@opentelemetry/api';
const tracer = trace.getTracer('my-app');
async function generateReport(userId: string) {
return tracer.startActiveSpan('generate-report', async (span) => {
span.setAttribute('user.id', userId);
try {
const data = await fetchUserData(userId);
span.setAttribute('report.record_count', data.length);
const result = await buildReport(data);
span.setStatus({ code: SpanStatusCode.OK });
return result;
} catch (err) {
span.recordException(err as Error);
span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
throw err;
} finally {
span.end();
}
});
}
ポイントは span.setAttribute() で ビジネス的に重要な値(ユーザーID、件数、ステータス)を属性として付けること。後でフィルタリングや集計に使えます。
Hono(Cloudflare Workers)でのOTel設定
Cloudflare Workers は Node.js ランタイムではないため、auto-instrumentations-node は使えません。代わりに軽量な OTLP HTTP エクスポーターを使います。
// src/tracing.ts
import { trace, context, SpanStatusCode } from '@opentelemetry/api';
import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
export function initTracing(env: { OTEL_ENDPOINT: string; OTEL_API_KEY: string }) {
const provider = new BasicTracerProvider({
resource: new Resource({
[ATTR_SERVICE_NAME]: 'my-hono-app',
}),
});
provider.addSpanProcessor(
new SimpleSpanProcessor(
new OTLPTraceExporter({
url: `${env.OTEL_ENDPOINT}/v1/traces`,
headers: { Authorization: `Bearer ${env.OTEL_API_KEY}` },
})
)
);
provider.register();
return trace.getTracer('my-hono-app');
}
// src/index.ts
import { Hono } from 'hono';
import { initTracing } from './tracing';
const app = new Hono<{ Bindings: Env }>();
app.use('*', async (c, next) => {
const tracer = initTracing(c.env);
return tracer.startActiveSpan(
`${c.req.method} ${c.req.path}`,
{ attributes: { 'http.method': c.req.method, 'http.url': c.req.url } },
async (span) => {
try {
await next();
span.setAttribute('http.status_code', c.res.status);
span.end();
} catch (err) {
span.recordException(err as Error);
span.setStatus({ code: SpanStatusCode.ERROR });
span.end();
throw err;
}
}
);
});
export default app;
メトリクス:カウンタとヒストグラムを使いこなす
メトリクスはリアルタイムのシステム状態を把握するのに使います。OTel には3種類のメトリクスがあります。
| 種類 | 用途 | 例 |
|---|---|---|
| Counter | 単調増加する値 | リクエスト総数、エラー数 |
| Gauge | 増減する現在値 | アクティブ接続数、メモリ使用量 |
| Histogram | 分布(p50/p95/p99) | レイテンシ、レスポンスサイズ |
import { metrics } from '@opentelemetry/api';
const meter = metrics.getMeter('my-app');
// リクエストカウンター(ステータスコード別)
const requestCounter = meter.createCounter('http.requests.total', {
description: 'Total HTTP requests',
});
// レイテンシヒストグラム
const latencyHistogram = meter.createHistogram('http.request.duration', {
description: 'HTTP request duration in ms',
unit: 'ms',
advice: { explicitBucketBoundaries: [5, 10, 25, 50, 100, 250, 500, 1000] },
});
// 使用例
app.use('*', async (c, next) => {
const start = Date.now();
await next();
const duration = Date.now() - start;
requestCounter.add(1, {
'http.method': c.req.method,
'http.status_code': String(c.res.status),
'http.route': c.req.routePath,
});
latencyHistogram.record(duration, {
'http.method': c.req.method,
'http.route': c.req.routePath,
});
});
AIアプリのLLMトレース(2026年の新標準)
2026年のホットトピックが LLMオブザーバビリティ です。OpenTelemetry の LLM セマンティクス規約(gen_ai.*)が策定され、AIアプリのトークン消費・コスト・応答時間を可視化できるようになりました。
import { trace, SpanKind } from '@opentelemetry/api';
import Anthropic from '@anthropic-ai/sdk';
const tracer = trace.getTracer('ai-app');
const client = new Anthropic();
async function callLLM(prompt: string) {
return tracer.startActiveSpan(
'gen_ai.chat',
{
kind: SpanKind.CLIENT,
attributes: {
'gen_ai.system': 'anthropic',
'gen_ai.request.model': 'claude-sonnet-4-6',
'gen_ai.request.max_tokens': 1024,
},
},
async (span) => {
const response = await client.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: prompt }],
});
span.setAttributes({
'gen_ai.usage.input_tokens': response.usage.input_tokens,
'gen_ai.usage.output_tokens': response.usage.output_tokens,
'gen_ai.response.finish_reasons': [response.stop_reason ?? 'unknown'],
});
span.end();
return response;
}
);
}
これで 1リクエストあたりの入力/出力トークン数がトレースに記録されます。Grafana などでダッシュボードを作れば「どのエンドポイントがトークンを消費しているか」が一目で分かります。
エクスポート先の比較:個人開発に使いやすい SaaS
| SaaS | 無料枠 | 強み | 向いている人 |
|---|---|---|---|
| Grafana Cloud | トレース50GB/月、メトリクス10K series | Grafana・Prometheus・Lokiをセットで使える | オールインワンで揃えたい人 |
| Honeycomb | 月2000万イベント | 高速クエリ、開発者体験が抜群 | トレース中心で使いたい人 |
| Axiom | 500GB/月(ログ) | ログとトレースの統合、低コスト | ログを大量に保存したい人 |
| Jaeger(自前) | 無制限(自己ホスト) | 無料、プライバシー保護 | VPS があってコストを抑えたい人 |
| Datadog | 14日間トライアル | エンタープライズ機能が充実 | チーム開発・本番運用 |
個人開発では Grafana Cloud の無料枠 か Honeycomb の無料枠 から始めるのがおすすめです。両方 OTL P対応なので、後で切り替えても SDK 側の変更は最小限で済みます。
Grafana Cloudへの接続例(.env)
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-ap-southeast-0.grafana.net/otlp
OTEL_API_KEY=<your-grafana-cloud-token>
OTEL_SERVICE_NAME=my-app
Honeycomb への接続例(.env)
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
OTEL_API_KEY=<your-honeycomb-api-key>
OTEL_SERVICE_NAME=my-app
どちらも OTEL_EXPORTER_OTLP_HEADERS に認証情報を入れるだけで動くので、環境変数を差し替えるだけで移行できます。
OTel Collectorを使う場合のdocker-compose
本番環境では Collector を挟むことで、SDKと送り先を完全に分離できます。
# docker-compose.yml
services:
otel-collector:
image: otel/opentelemetry-collector-contrib:0.110.0
ports:
- "4317:4317" # gRPC
- "4318:4318" # HTTP
volumes:
- ./otel-collector.yml:/etc/otelcol-contrib/config.yaml
jaeger:
image: jaegertracing/all-in-one:1.62
ports:
- "16686:16686" # UI
- "14250:14250" # gRPC
prometheus:
image: prom/prometheus:v3.0.0
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
# otel-collector.yml
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch:
timeout: 1s
exporters:
otlp/jaeger:
endpoint: jaeger:14250
tls:
insecure: true
prometheusremotewrite:
endpoint: http://prometheus:9090/api/v1/write
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlp/jaeger]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [prometheusremotewrite]
セマンティクス規約(Semantic Conventions)を活用する
OTel には属性名の命名規則が定められており、これを守ることで SaaS 側のダッシュボードが自動で機能します。
http.method,http.status_code,http.route:HTTPリクエストdb.system,db.operation,db.statement:データベース操作gen_ai.system,gen_ai.usage.input_tokens:LLM呼び出しuser.id,session.id:ユーザー追跡(個人情報に注意)
パッケージ @opentelemetry/semantic-conventions を使うと型補完付きで書けます。
import {
ATTR_HTTP_REQUEST_METHOD,
ATTR_HTTP_RESPONSE_STATUS_CODE,
ATTR_DB_SYSTEM_NAME,
} from '@opentelemetry/semantic-conventions';
span.setAttributes({
[ATTR_HTTP_REQUEST_METHOD]: 'GET',
[ATTR_HTTP_RESPONSE_STATUS_CODE]: 200,
[ATTR_DB_SYSTEM_NAME]: 'postgresql',
});
よくある落とし穴と対処法
1. Span が閉じられない
非同期処理で span.end() が呼ばれないケースが最多。try/finally で必ず end() を呼ぶか、startActiveSpan のコールバック形式を使いましょう。
2. Context が引き継がれない
Worker スレッドや setTimeout を使うと AsyncLocalStorage のコンテキストが切れます。context.bind() か context.with() で明示的に伝播させる必要があります。
3. Cloudflare Workers で動かない
Node.js専用の自動計装パッケージは Workers で動きません。@opentelemetry/sdk-trace-base(Node.jsランタイム依存なし)を使ってください。また、Collectorへの接続は fetch ベースの OTLP HTTP エクスポーターを使います。
4. 開発環境でトレースを確認したい
SaaS に送らずコンソールに出力する ConsoleSpanExporter が便利です。
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
// 開発時
if (process.env.NODE_ENV === 'development') {
provider.addSpanProcessor(
new SimpleSpanProcessor(new ConsoleSpanExporter())
);
}
まとめ:OpenTelemetryで始めるオブザーバビリティ
OpenTelemetry は一見複雑に見えますが、基本構造は「SDK でデータを収集 → OTLP で送る → 好きな SaaS で可視化」というシンプルな流れです。
- まず試すなら:
auto-instrumentations-node+ Grafana Cloud 無料枠でゼロコード計装 - 重要な処理だけ追うなら:
startActiveSpanで手動スパンを追加 - AIアプリを作っているなら:
gen_ai.*属性でトークンコストを可視化 - エッジ環境(Cloudflare Workers)なら:
sdk-trace-base+ OTLP HTTP エクスポーター
個人開発では「壊れてから調べる」デバッグから、「データで先手を打つ」オブザーバビリティ駆動の開発へ移行することで、障害対応にかかる時間が大幅に短縮されます。まずは Grafana Cloud の無料枠で試してみてください。