⬡ API & SDK/2026-05-01上級

Claude API のテレメトリを ClickHouse に流して分析する — 本番環境のコスト・遅延・エラーを可視化する設計ガイド

Claude API のリクエスト単位でコスト・遅延・トークン使用量を ClickHouse に蓄積し、Materialized View でリアルタイムダッシュボードを構築する本番運用設計を解説します。

claude-api⁸¹ clickhouse observability¹⁴ analytics³ production⁸⁷

✦ プレミアム記事

Claude API を本番投入してから半年経ったある月末、請求書を見て手が震えた経験があります。前月比で 4.2 倍。原因を切り分けるのに丸 2 日かかりました。あのときアプリ側にリクエスト単位のテレメトリ基盤があれば、おそらく 30 分で原因のエンドポイントを特定できていたはずです。

Claude API のリクエスト単位の使用量・コスト・遅延を ClickHouse に蓄積し、Postgres では実現しにくい高速な集計と異常検知を本番品質で組み立てる方法を順を追って整理していきます。Cloudflare Workers から ClickHouse Cloud に安全に書き込む実装、Materialized View でダッシュボードを 1 秒以内に返す設計、そしてハルシネーション疑い・リトライループといった「請求書には現れない損失」を SQL で検出するレシピまで、本番運用で実際に効いたパターンをまとめています。

なぜ ClickHouse なのか — Postgres / BigQuery / Snowflake と何が違うのか

最初に Postgres にテレメトリを書こうと考える方が多いはずです。私もそうでした。リクエスト 1 件あたり 1 行を events テーブルに INSERT すれば、SQL で集計できます。一見シンプルです。

しかし API 呼び出しが 1 日 100 万件を超えたあたりから、Postgres の限界が見えてきます。SELECT model, sum(input_tokens), sum(output_tokens) FROM events WHERE ts > now() - interval '1 day' GROUP BY model のような集計クエリが、インデックスを工夫しても 30 秒以上かかるようになります。Postgres は OLTP（行指向トランザクション）に最適化されているため、列方向の集計には根本的に不利なのです。

ClickHouse のテレメトリ用途で重要な強みを順に挙げると、まず列指向ストレージで集計が高速で、数億行を SUM / AVG / quantile() するクエリが秒単位で返ってきます。次に ReplacingMergeTree / AggregatingMergeTree などの専用エンジンが、重複排除や事前集計を宣言的に書けるよう設計されている点です。さらに Materialized View が「即時反映の集計テーブル」として機能し、ダッシュボードを 1 秒以内で返すための基盤になります。データ圧縮率も高く、テレメトリは似た値の繰り返しが多いため 1/10 以下になることも珍しくありません。

BigQuery や Snowflake も列指向ですが、レイテンシ（数秒〜十数秒のスロット起動）と料金体系（クエリ単価）の点で、ダッシュボードの「裏側で頻繁にクエリされる用途」には合いません。ClickHouse はリアルタイム分析の即応性に振り切った設計なので、運用ダッシュボード・アラート判定・社内向け Slack 通知のようなユースケースで真価を発揮します。

私はチーム規模・予算・運用負荷のバランスで「100 万件/日を超える Claude API 利用がある場合は ClickHouse を最初の選択肢にする」というルールを使っています。それ未満であれば Postgres + 適切な集計テーブルで十分なケースもあるので、規模感に合わせて選んでください。

計測すべきイベントと最低限のスキーマ

「とりあえず全部入れる」とスキーマが肥大化します。本番運用で実際に役立つ最小限のフィールドを最初に決める点が肝心です。

私が 4 つのプロダクトで運用した経験から、以下のスキーマを推奨します。

CREATE TABLE claude_api_events (
    -- 識別子
    event_id UUID,
    request_id String,        -- Anthropic の request-id ヘッダ
    user_id String,           -- アプリ側のユーザー識別子
    workspace_id LowCardinality(String),  -- マルチテナント対応
 
    -- 時刻・モデル情報
    ts DateTime64(3, 'UTC'),  -- ミリ秒精度
    model LowCardinality(String),
    api_version LowCardinality(String),
 
    -- リクエスト・レスポンス
    input_tokens UInt32,
    output_tokens UInt32,
    cache_read_tokens UInt32 DEFAULT 0,
    cache_creation_tokens UInt32 DEFAULT 0,
    stop_reason LowCardinality(String),
 
    -- パフォーマンス
    latency_ms UInt32,
    ttft_ms UInt32,           -- Time To First Token
    streaming UInt8,
 
    -- 結果
    success UInt8,
    error_type LowCardinality(String) DEFAULT '',
    http_status UInt16,
 
    -- アプリ層の文脈
    feature_id LowCardinality(String),  -- 「要約」「翻訳」など機能名
    prompt_template_id LowCardinality(String),
    prompt_version UInt32 DEFAULT 0,
 
    -- コスト計算（事前計算しておくとクエリが軽い）
    cost_usd Decimal64(6) DEFAULT 0
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(ts)
ORDER BY (workspace_id, feature_id, ts)
TTL ts + INTERVAL 18 MONTH
SETTINGS index_granularity = 8192;

設計上の重要ポイントを 3 つだけ強調します。

第一に LowCardinality(String) を使えばす。model 名や feature_id のように値の種類が少ない列は、必ず LowCardinality で宣言します。圧縮率が大幅に上がり、GROUP BY も高速化します。私のプロダクトでは導入後にストレージが約 35% 減りました。

第二に ORDER BY の順序が性能を左右します。ClickHouse は ORDER BY の先頭から順に並んだプライマリキーで部分検索を高速化します。「テナント単位 → 機能単位 → 時刻」の順は、ダッシュボードのクエリ（「特定テナントの特定機能の直近 24 時間」）に最適化された順序です。

第三にコストは事前計算しておくことです。取り込み時点で cost_usd を計算しておくと、ダッシュボードクエリが SUM 一発で済みます。価格表が変わったときの再計算は、後述のように Materialized View で吸収できます。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦「先月の API 請求がいきなり 3 倍になっていた」という事故を防げる、リクエスト単位のコスト追跡基盤を手に入れられます

✦Postgres でテレメトリを保存していてクエリが詰まっていた人が、ClickHouse + Materialized View で 1 秒以内に集計を返せる構成に切り替えられます

✦ハルシネーション疑い・リトライループ・レイテンシ急増を SQL で検出する具体的なクエリパターンを習得し、ユーザーから報告される前に異常を能動的に検知できるようになります

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

取り込みパイプラインの実装 — Cloudflare Workers から ClickHouse Cloud への安全な書き込み

Cloudflare Workers から Claude API を呼んでいる構成を前提に、Workers 側で計測・送信する実装を示します。

直接 ClickHouse の HTTP インターフェースに INSERT するのが最もシンプルです。ただし同期書き込みは絶対に避けてください。書き込み失敗が API レスポンスに影響すると、ユーザー体験が崩れます。ctx.waitUntil でバックグラウンドに逃がすのが鉄則です。

// src/lib/telemetry.ts
import Anthropic from "@anthropic-ai/sdk";
 
interface Env {
  ANTHROPIC_API_KEY: string;
  CLICKHOUSE_URL: string;
  CLICKHOUSE_USER: string;
  CLICKHOUSE_PASSWORD: string;
  TELEMETRY_FALLBACK: KVNamespace;
}
 
interface TelemetryEvent {
  event_id: string;
  request_id: string;
  user_id: string;
  workspace_id: string;
  ts: string; // ISO8601
  model: string;
  api_version: string;
  input_tokens: number;
  output_tokens: number;
  cache_read_tokens: number;
  cache_creation_tokens: number;
  stop_reason: string;
  latency_ms: number;
  ttft_ms: number;
  streaming: number;
  success: number;
  error_type: string;
  http_status: number;
  feature_id: string;
  prompt_template_id: string;
  prompt_version: number;
  cost_usd: number;
}
 
const PRICES_PER_MTOK: Record<string, { input: number; output: number; cacheRead: number; cacheCreation: number }> = {
  "claude-sonnet-4-6": { input: 3, output: 15, cacheRead: 0.3, cacheCreation: 3.75 },
  "claude-opus-4-6":   { input: 15, output: 75, cacheRead: 1.5, cacheCreation: 18.75 },
  "claude-haiku-4-5":  { input: 0.8, output: 4, cacheRead: 0.08, cacheCreation: 1 },
};
 
function calcCost(model: string, ev: TelemetryEvent): number {
  const p = PRICES_PER_MTOK[model];
  if (!p) return 0;
  const m = 1_000_000;
  return (
    (ev.input_tokens * p.input +
     ev.output_tokens * p.output +
     ev.cache_read_tokens * p.cacheRead +
     ev.cache_creation_tokens * p.cacheCreation) / m
  );
}
 
export async function sendTelemetry(env: Env, event: TelemetryEvent): Promise<void> {
  // ClickHouse は JSONEachRow が最も効率がよい
  const body = JSON.stringify(event);
  const url = `${env.CLICKHOUSE_URL}/?query=INSERT+INTO+claude_api_events+FORMAT+JSONEachRow`;
 
  try {
    const res = await fetch(url, {
      method: "POST",
      headers: {
        "Authorization": `Basic ${btoa(`${env.CLICKHOUSE_USER}:${env.CLICKHOUSE_PASSWORD}`)}`,
        "Content-Type": "application/x-ndjson",
      },
      body,
    });
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`ClickHouse insert failed: ${res.status} ${text}`);
    }
  } catch (err) {
    // 失敗時のフォールバック: KV にキューイングして cron で再送
    console.error("Telemetry insert failed, queuing to KV:", err);
    await env.TELEMETRY_FALLBACK.put(
      `event:${event.event_id}`,
      body,
      { expirationTtl: 7 * 24 * 60 * 60 }
    );
  }
}

そしてリクエストハンドラの中で計測します。

// src/handler.ts
export async function handleClaudeRequest(
  req: Request,
  env: Env,
  ctx: ExecutionContext
): Promise<Response> {
  const t0 = Date.now();
  const eventId = crypto.randomUUID();
  const userId = req.headers.get("x-user-id") ?? "anonymous";
  const workspaceId = req.headers.get("x-workspace-id") ?? "default";
  const featureId = "summarize";
  const promptTemplateId = "summary-v3";
  let ttftMs = 0;
  let firstChunkSeen = false;
 
  const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });
 
  try {
    const stream = anthropic.messages.stream({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Summarize the latest deployment notes." }],
    });
 
    for await (const _chunk of stream) {
      if (!firstChunkSeen) {
        ttftMs = Date.now() - t0;
        firstChunkSeen = true;
      }
    }
    const final = await stream.finalMessage();
 
    const event: TelemetryEvent = {
      event_id: eventId,
      request_id: (stream as { request_id?: string }).request_id ?? "",
      user_id: userId,
      workspace_id: workspaceId,
      ts: new Date().toISOString(),
      model: "claude-sonnet-4-6",
      api_version: "2023-06-01",
      input_tokens: final.usage.input_tokens,
      output_tokens: final.usage.output_tokens,
      cache_read_tokens: final.usage.cache_read_input_tokens ?? 0,
      cache_creation_tokens: final.usage.cache_creation_input_tokens ?? 0,
      stop_reason: final.stop_reason ?? "",
      latency_ms: Date.now() - t0,
      ttft_ms: ttftMs,
      streaming: 1,
      success: 1,
      error_type: "",
      http_status: 200,
      feature_id: featureId,
      prompt_template_id: promptTemplateId,
      prompt_version: 3,
      cost_usd: 0,
    };
    event.cost_usd = calcCost(event.model, event);
 
    // ⚠️ 重要: バックグラウンドで送信。レスポンスを待たせない
    ctx.waitUntil(sendTelemetry(env, event));
 
    return new Response("ok");
  } catch (err) {
    const e = err as { status?: number; constructor: { name: string } };
    const event: TelemetryEvent = {
      event_id: eventId,
      request_id: "",
      user_id: userId,
      workspace_id: workspaceId,
      ts: new Date().toISOString(),
      model: "claude-sonnet-4-6",
      api_version: "2023-06-01",
      input_tokens: 0,
      output_tokens: 0,
      cache_read_tokens: 0,
      cache_creation_tokens: 0,
      stop_reason: "",
      latency_ms: Date.now() - t0,
      ttft_ms: ttftMs,
      streaming: 1,
      success: 0,
      error_type: e?.constructor?.name ?? "UnknownError",
      http_status: e?.status ?? 500,
      feature_id: featureId,
      prompt_template_id: promptTemplateId,
      prompt_version: 3,
      cost_usd: 0,
    };
    ctx.waitUntil(sendTelemetry(env, event));
    return new Response("error", { status: 500 });
  }
}

なぜストリーミングでも usage を最後にまとめて記録するのか、という質問をよく受けます。ストリーミング応答では message_delta イベントの中に最終的な usage 情報が入っています。途中で output_tokens を加算していくのではなく、ストリーム終端で finalMessage() から取得するほうが確実です。途中で接続が切れた場合は別途エラー記録になるので、二重計上にはなりません。

フォールバックを必ず仕込むことも重要です。ClickHouse Cloud は SLA 99.9% ですが、ネットワーク障害は普通に起きます。書き込み失敗時に Cloudflare KV へキューイングし、cron で再送する仕組みを入れておくと、データ欠損率を 99.99% 以上に保てます。

集計と可視化 — Materialized View で分単位ダッシュボードを作る

ダッシュボードの裏で SELECT model, sum(cost_usd) FROM claude_api_events WHERE ts > now() - INTERVAL 1 DAY GROUP BY model を毎秒走らせる設計は、データが増えるとすぐに苦しくなります。代わりに Materialized View で事前集計テーブルを作るのが ClickHouse の流儀です。

-- 分単位の事前集計テーブル
CREATE TABLE claude_minute_metrics (
    minute DateTime,
    workspace_id LowCardinality(String),
    feature_id LowCardinality(String),
    model LowCardinality(String),
 
    request_count UInt32,
    success_count UInt32,
    error_count UInt32,
    total_input_tokens UInt64,
    total_output_tokens UInt64,
    total_cache_read_tokens UInt64,
    total_cost_usd Decimal64(6),
 
    p50_latency_ms AggregateFunction(quantile(0.5), UInt32),
    p95_latency_ms AggregateFunction(quantile(0.95), UInt32),
    p99_latency_ms AggregateFunction(quantile(0.99), UInt32)
)
ENGINE = SummingMergeTree()
PARTITION BY toYYYYMM(minute)
ORDER BY (workspace_id, feature_id, model, minute);
 
-- 元テーブルへの INSERT を自動で集計テーブルに反映する MV
CREATE MATERIALIZED VIEW claude_minute_metrics_mv
TO claude_minute_metrics
AS SELECT
    toStartOfMinute(ts) AS minute,
    workspace_id,
    feature_id,
    model,
    count() AS request_count,
    sumIf(1, success = 1) AS success_count,
    sumIf(1, success = 0) AS error_count,
    sum(input_tokens) AS total_input_tokens,
    sum(output_tokens) AS total_output_tokens,
    sum(cache_read_tokens) AS total_cache_read_tokens,
    sum(cost_usd) AS total_cost_usd,
    quantileState(0.5)(latency_ms) AS p50_latency_ms,
    quantileState(0.95)(latency_ms) AS p95_latency_ms,
    quantileState(0.99)(latency_ms) AS p99_latency_ms
FROM claude_api_events
GROUP BY minute, workspace_id, feature_id, model;

集計済みテーブルへのクエリは劇的に速くなります。

-- ダッシュボード用クエリ（数十ミリ秒で返る）
SELECT
    minute,
    sum(total_cost_usd) AS cost_usd,
    sum(request_count) AS requests,
    quantileMerge(0.95)(p95_latency_ms) AS p95_ms
FROM claude_minute_metrics
WHERE workspace_id = 'tenant_abc'
  AND minute >= now() - INTERVAL 24 HOUR
GROUP BY minute
ORDER BY minute;

なぜ AggregateFunction(quantile(0.95), UInt32) を使うのか、と疑問に思う方もいるでしょう。パーセンタイルは「集計済みの値をさらに集計」できないため、生データから毎回計算するのが普通です。しかし quantileState で中間状態を保存しておくと、Materialized View で集約しても精度を保ったまま quantileMerge で最終値を取り出せます。これが ClickHouse の真骨頂であり、他の DBMS では真似しにくい部分です。

コスト分析の SQL レシピ — モデル別・ユーザー別・プロンプト別の内訳

「コストが急増した」という事象に対して、原因を 5 分以内で切り分けるためのクエリ集です。

モデル別の月次コスト推移を可視化するクエリは次のようになります。

SELECT
    toStartOfDay(ts) AS day,
    model,
    sum(cost_usd) AS cost_usd,
    sum(input_tokens + output_tokens) AS total_tokens
FROM claude_api_events
WHERE ts >= now() - INTERVAL 30 DAY
GROUP BY day, model
ORDER BY day, cost_usd DESC;

プロンプトテンプレート別のコスト効率を見るクエリも頻繁に使います。

SELECT
    prompt_template_id,
    count() AS requests,
    sum(cost_usd) AS total_cost,
    avg(cost_usd) AS avg_cost,
    avg(output_tokens) AS avg_output_tokens,
    quantile(0.95)(latency_ms) AS p95_latency_ms
FROM claude_api_events
WHERE ts >= now() - INTERVAL 7 DAY
  AND success = 1
GROUP BY prompt_template_id
ORDER BY total_cost DESC
LIMIT 20;

このクエリで「平均トークン消費が大きいテンプレート」を特定できれば、プロンプトの圧縮（few-shot を減らす、説明文を短くする）で大きなコスト削減が見込めます。私のチームでは、このクエリで見つかった上位 3 テンプレートを最適化しただけで月額コストが 22% 下がりました。

キャッシュヒット率の可視化も重要です。

SELECT
    feature_id,
    sum(cache_read_tokens) AS cache_read,
    sum(input_tokens) AS total_input,
    round(sum(cache_read_tokens) / nullif(sum(input_tokens), 0) * 100, 2) AS cache_hit_pct
FROM claude_api_events
WHERE ts >= now() - INTERVAL 7 DAY
GROUP BY feature_id
ORDER BY total_input DESC;

Prompt Caching を有効化したのにヒット率が低い機能があれば、プロンプト構造が頻繁に変わっている可能性があります。テンプレートの安定化やキャッシュキーの設計を見直すきっかけになります。

失敗パターンの検出 — 異常検知・ループ検出・ハルシネーション疑い

請求書には現れないが運用上は致命的な「サイレント障害」を SQL で検出するレシピです。これがダッシュボードに常駐すれば、ユーザーが報告する前に異常を検知できます。

リトライループの検出は最初に入れるべきアラートです。同じユーザーが同じ feature_id で短時間に大量リクエストしている状態は、再試行ロジックの暴走を意味します。

SELECT
    user_id,
    feature_id,
    count() AS requests_in_window,
    sum(cost_usd) AS cost_usd,
    sum(input_tokens) AS input_tokens
FROM claude_api_events
WHERE ts >= now() - INTERVAL 5 MINUTE
GROUP BY user_id, feature_id
HAVING requests_in_window > 50
ORDER BY requests_in_window DESC;

ハルシネーション疑いの検出には、出力トークン数の異常値を見ます。期待されるトークン数のレンジから大きく外れた応答は、何かが壊れているシグナルです。

SELECT
    feature_id,
    prompt_template_id,
    count() AS suspicious_count,
    avg(output_tokens) AS avg_output,
    quantile(0.99)(output_tokens) AS p99_output
FROM claude_api_events
WHERE ts >= now() - INTERVAL 1 HOUR
  AND success = 1
  AND (output_tokens < 10 OR output_tokens > 3000)
GROUP BY feature_id, prompt_template_id
HAVING suspicious_count > 5;

レイテンシ急増の検出は z スコアを使います。

WITH baseline AS (
    SELECT
        feature_id,
        avg(latency_ms) AS baseline_avg,
        stddevPop(latency_ms) AS baseline_std
    FROM claude_api_events
    WHERE ts BETWEEN now() - INTERVAL 1 DAY AND now() - INTERVAL 1 HOUR
      AND success = 1
    GROUP BY feature_id
)
SELECT
    e.feature_id,
    avg(e.latency_ms) AS recent_avg,
    b.baseline_avg,
    (avg(e.latency_ms) - b.baseline_avg) / nullif(b.baseline_std, 0) AS z_score
FROM claude_api_events e
JOIN baseline b USING (feature_id)
WHERE e.ts >= now() - INTERVAL 5 MINUTE
GROUP BY e.feature_id, b.baseline_avg, b.baseline_std
HAVING z_score > 3;

z スコアが 3 を超える機能はベースラインから大きく外れているため、上流（モデル切り替え、プロンプト変更、ネットワーク）で何か起きているサインです。アラート閾値を z=3 に設定すれば、誤検知を抑えつつ本物の異常を捕捉できます。

マルチテナント環境のコスト配賦 — チャージバックと顧客単位の利益率

SaaS としてサービス提供している場合、テナント単位のコスト配賦が経営上の死活問題になります。workspace_id を ORDER BY の先頭に置いた設計が、ここで真価を発揮します。

-- テナント単位の月次コストランキング
SELECT
    workspace_id,
    sum(cost_usd) AS api_cost_usd,
    sum(input_tokens + output_tokens) AS total_tokens,
    countDistinct(user_id) AS active_users,
    sum(cost_usd) / nullif(countDistinct(user_id), 0) AS cost_per_user
FROM claude_api_events
WHERE ts >= toStartOfMonth(now())
GROUP BY workspace_id
ORDER BY api_cost_usd DESC
LIMIT 50;

cost_per_user が突出して高いテナントは、料金プランと実利用量の不一致を意味します。私のチームでは、四半期ごとにこのレポートを CFO 室に共有して料金プランの見直しに使っています。実際にこのクエリで「無制限プランで実コストの 3 倍以上を消費していたエンタープライズ顧客」を 2 件発見し、契約改定で年額換算 480 万円相当の損失を回避しました。

赤字テナントの定義は事業ごとに異なりますが、概ね「月次サブスクリプション収益 < API コスト × 1.5」を超えているテナントは要警戒です。マージン率を SQL で常時監視できる体制があると、料金プランの設計判断が一気にデータドリブンになります。

Anthropic の請求と突き合わせる — 取りこぼしを 1% 未満に抑える

ClickHouse 上の集計と Anthropic コンソールの請求金額が一致しないと、ボードや CFO の信頼を一気に失います。月次のリコンサイル（突き合わせ）クエリを必ず仕込んでおきます。

-- 月単位・モデル別の集計（Anthropic コンソールと比較する）
SELECT
    toStartOfMonth(ts) AS month,
    model,
    sum(input_tokens) AS input_tokens,
    sum(output_tokens) AS output_tokens,
    sum(cache_read_tokens) AS cache_read_tokens,
    sum(cache_creation_tokens) AS cache_creation_tokens,
    round(sum(cost_usd), 2) AS estimated_cost_usd
FROM claude_api_events
WHERE ts >= now() - INTERVAL 3 MONTH
GROUP BY month, model
ORDER BY month, model;

経験上、差異の原因として頻出するのは次の 3 つです。第一にフォールバック KV からの再送漏れで、cron の障害で数千イベントが取りこぼされるケースがあります。第二にネットワークタイムアウト時のローカル計測ミス（API は課金されたがレスポンスが Workers に届かなかったケース）です。第三に価格表の更新漏れで、Anthropic がプライシングを変更したのに PRICES_PER_MTOK 定数を更新していないというヒューマンエラーです。

リコンサイルの差異が 5% を超えたらアラートを出す運用にすると、データ品質の劣化に早く気付けます。

運用クックブック — 週次・月次のルーティン

ダッシュボードを作って終わり、ではなく、定期的に同じレポートを見ることがコスト最適化の鍵です。私のチームで運用しているルーティンを共有します。

毎週月曜の午前中に、先週との比較レポートを Slack に流します。クエリは以下のとおりです。

-- 先週と今週の比較（feature_id 別）
WITH last_week AS (
    SELECT feature_id, sum(cost_usd) AS cost
    FROM claude_api_events
    WHERE ts BETWEEN now() - INTERVAL 14 DAY AND now() - INTERVAL 7 DAY
    GROUP BY feature_id
),
this_week AS (
    SELECT feature_id, sum(cost_usd) AS cost
    FROM claude_api_events
    WHERE ts >= now() - INTERVAL 7 DAY
    GROUP BY feature_id
)
SELECT
    coalesce(t.feature_id, l.feature_id) AS feature_id,
    l.cost AS last_week_cost,
    t.cost AS this_week_cost,
    (t.cost - l.cost) / nullif(l.cost, 0) * 100 AS pct_change
FROM this_week t
FULL OUTER JOIN last_week l USING (feature_id)
ORDER BY this_week_cost DESC;

毎月初めに、前月のトータルコストと、コスト上位 10 機能のコード変更履歴を突き合わせるレビューを 30 分で行っています。コスト増加と Git のコミット履歴を並べると「先月の v3.2 リリース以降に summarize 機能のコストが 1.8 倍になった」のような関連性が見えてきます。これがあるとリグレッション検出の解像度が劇的に上がります。

四半期ごとには、プロンプトキャッシュのヒット率が 40% を下回る機能の棚卸しを行います。キャッシュキーが頻繁に変わる構造になっていないか、システムプロンプトと会話履歴の境界が適切に切れているかを点検する時間を意図的に作っています。

本番でハマったポイント

実運用で詰まった 5 つのポイントを共有します。

ひとつめは ClickHouse Cloud の「Idle」課金を見落とすことです。ClickHouse Cloud には接続がない時間にスケールダウンする仕組みがありますが、Materialized View が定期的にバックグラウンド処理を走らせるため、アイドル状態にならないケースがあります。SETTINGS background_pool_size を絞り、夜間のテレメトリ取り込みを cron でバッチ化することで、私のチームでは月額を約 28% 削減できました。

ふたつめは INSERT を 1 行ずつ送るとパーティションが断片化することです。Cloudflare Workers から 1 リクエスト = 1 INSERT で送ると、ClickHouse が背後で頻繁に Merge を走らせて CPU を食います。Workers Queue を挟んで 1〜5 秒間隔でバッチ INSERT するのが本番のセオリーです。Workers Queue のバッチサイズを 100、タイムアウトを 5 秒に設定するのが私の標準です。

みっつめは LowCardinality を多用しすぎるとメモリを食うことです。辞書を全カーディナリティ列で持つと、特定のクエリで MEMORY_LIMIT_EXCEEDED を引きます。feature_id のように値が 100 程度に収まる列のみに絞るのが安全です。user_id のようにカーディナリティが数万を超える列に LowCardinality を付けると逆効果になります。

よっつめはタイムスタンプの精度ずれで重複検知ができないことです。ReplacingMergeTree で event_id をキーに重複排除する場合、ts のミリ秒精度を揃えていないと別レコードとして扱われます。DateTime64(3) を必ず使い、ISO 文字列から DateTime64 への変換時の桁数を確認してください。

いつつめは個人情報をうっかり入れることです。prompt_template_id だけ入れて、本文は絶対に入れないこと。Workers 側で構造化ログとして送る前にフィルタを 1 段挟むのが安全です。私は最初に「ユーザー入力の最初の 50 文字」を入れてしまい、GDPR 対応で全行削除する羽目になりました。

実際の障害対応の流れ — テレメトリがあったときと無かったときの違い

抽象論よりも具体例の方が伝わると思うので、私が実際に遭遇したコスト急増事案を時系列で共有します。

ある月曜日の朝、Slack で「先週末のコストが想定の 2.3 倍になっています」とアラートが上がりました。テレメトリがある状態だったので、対応は次のように進みました。

午前 9 時 5 分、コスト推移クエリを実行し claude-opus-4-6 の利用量が金曜深夜から急増していることを確認しました。午前 9 時 15 分、feature_id 別の内訳から report-generator という機能が突出していると特定しました。午前 9 時 30 分、prompt_template_id を見ると report-v4 という新しいバージョンが先週金曜にデプロイされていたことが判明しました。午前 9 時 45 分、git log で v4 のリリースコミットを確認すると、システムプロンプトに 800 トークンの追加例が入っていました。午前 10 時、プロンプトを v3 に戻すホットフィックスをデプロイし、午前 10 時 30 分にはコストが正常に戻りました。

トータルで 1 時間 25 分の対応です。テレメトリが無かった時代の同種事案では、原因特定だけで丸 2 日かかっていたことを考えると、ROI は明らかでした。

ここで重要なのは「データさえあれば原因は SQL が教えてくれる」という点です。ダッシュボードを眺めて気付くのではなく、再現性のある SQL でドリルダウンする運用にしておくと、誰が対応してもブレなく原因特定までたどり着けます。

次にやること

まずは ClickHouse Cloud の無料枠（30 日・$300 クレジット）でこのスキーマを 1 つ作り、本番の Workers から ctx.waitUntil でテレメトリを 1 週間流してみてください。1 週間分のデータがあれば、上記の SQL をそのまま流すだけで「コストが想定外に高い feature_id」「キャッシュが効いていないテンプレート」が高確率で見つかります。それを 1 つ修正するだけでも、月額数万円の節約は珍しくありません。

ダッシュボードの構築は Grafana の ClickHouse プラグインが手早く、社内向けなら Metabase でも十分な品質のものが組めます。書籍として体系的に

ひとつ実務上のコツを共有しておきます。ClickHouse Cloud のクラスタを立てるときは、テレメトリ投入用に別のデータベース（少なくとも別のユーザー）を必ず分けてください。Worker からは events テーブルへの INSERT 権限だけで十分です。ダッシュボード用の読み取り専用認証情報と、投入用の書き込み専用認証情報を分けておくことは、漏洩時のローテーションや「誰が DROP TABLE を打てるのか」の監査ログ的観点で小さくない効果があります。

複数環境（本番とステージング、あるいはセルフホストの dev クラスタと ClickHouse Cloud の併用）を運用するなら、スキーマに deployment カラム（prod / staging / dev）を追加して、WHERE deployment = 'prod' で同じクエリを使い回せるようにする方がメンテナンスしやすいです。環境ごとにテーブルを分ける構成は、環境横断の比較がしにくく、スキーマ変更のたびに複数テーブルの調整が必要になるため避けています。

最後に、テレメトリパイプライン自体を本番システムとして扱う点が肝心です。KV フォールバックキューには独立した監視を設定し（深さが増えたらアラート）、価格表定数は Git 管理とコードレビューのチェックリストで「価格表編集を必ずレビューする」フローに組み込み、リコンサイルクエリは毎月スケジュール実行して Slack に差異を投稿します。観測されないテレメトリは徐々に使い物にならなくなる傾向があります。「数字が信用できない」と感じた瞬間に、そのテレメトリは死にます。

関連する実装パターンとして、Claude API のコスト最適化を本番運用で効かせる設計パターンと Claude API + OpenTelemetry で AI 観測性基盤を構築するガイドもあわせて読むと、計測 → 分析 → 最適化の循環全体が見えてくるはずです。