おつかれさまです!桑野です!

Claude Codeを組織で使い始めると、「誰がどれくらい使ってるの?」が気になってきますよね!え?見られたくない?ダメダメ!アカンよ!

Claude CodeはOpenTelemetry(OTel)で利用ログを送れるので、送り先と認証まで設定して配っておけば、メンバーはふだんどおり使うだけでログが集まります(あとで出てくるブローカーの形だけは、最初にDatabricksへのログインが要ります)。

じゃあその受け口をDatabricksのZerobus Ingest for OTLP(OTLPを受けてUnity Catalogのテーブルに直接書くサービス)にしたら、収集から分析まで1か所でいけるのでは?と思って、実際にやってみました!

今回の構成

Aは端末からZerobusへ直接、Bは同じく直接で、トークンだけをDatabricks Appsからもらう形、CはOTel Collectorを中継に置く形です。個人で試すならA、組織に配るならB、端末の設定をhttp/jsonのまま変えたくないならCです。

手元はDocker、そして、Claude Code、Collector otel/opentelemetry-collector-contribです(検証したバージョンはDocker 29.9.3、Claude Code 2.1.325、Collector 0.164.0)。

モデルはDatabricksのAI Gateway(/ai-gateway/anthropic)経由で、Sonnet 4.6・Haiku 4.5・Opus 4.6を呼んでいます。

まずは受け皿のテーブルとサービスプリンシパル

Zerobusはテーブルを作らないので、先に作ります。DDLは公式ページのままで、ログ(イベント)とメトリクスの2つだけ作りました。属性はVARIANT型(JSONのような半構造データをそのまま持てる型)の列に入ります。

書き込むサービスプリンシパル(以下SP、システム用のアカウント)を作ってOAuthのシークレットを発行し(手順)、テーブルごとにMODIFYとSELECTを付けます。ALL PRIVILEGESでは足りないので注意!

GRANT USE CATALOG ON CATALOG <catalog> TO `<sp-application-id>`;
GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `<sp-application-id>`;
GRANT MODIFY, SELECT ON TABLE <catalog>.<schema>.cc_otel_logs TO `<sp-application-id>`;
GRANT MODIFY, SELECT ON TABLE <catalog>.<schema>.cc_otel_metrics TO `<sp-application-id>`;

直接送るならhttp/protobufとotelHeadersHelper

では早速Databricksに送ってみましょう!

気をつけるのは2つで、Zerobusは1リクエスト1テーブル(テーブル名をヘッダで渡す)なのと、SPのトークンが1時間で切れることです。プロトコルはhttp/protobufにします(ZerobusのOTLPはJSONを受けず、helperもHTTPのときだけ効くため)。

テーブル名は信号ごとのヘッダ変数に書きます(共通のヘッダとマージされます)。トークンはotelHeadersHelper(ヘッダを出すスクリプトを指定する設定)に任せます。Claude Codeが起動時と(既定で)29分ごとに呼び直してくれるので、1時間で切れても大丈夫です。

今回はmanaged settingsのファイル(Linuxでは/etc/claude-code/managed-settings.json)にこう書きました。

{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
"OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://<workspace-id>.zerobus.<region>.cloud.databricks.com/v1/logs",
"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://<workspace-id>.zerobus.<region>.cloud.databricks.com/v1/metrics",
"OTEL_EXPORTER_OTLP_LOGS_HEADERS": "x-databricks-zerobus-table-name=<catalog>.<schema>.cc_otel_logs",
"OTEL_EXPORTER_OTLP_METRICS_HEADERS": "x-databricks-zerobus-table-name=<catalog>.<schema>.cc_otel_metrics"
},
"otelHeadersHelper": "/app/zerobus_headers.sh"
}

helperのほうはこれです。authorization_detailsにテーブルを2つ並べると、1つのトークンでログとメトリクスの両方に書けました。

curlとjqを使うので入れておき、/app/zerobus_headers.shに置いてchmod +xします。変数はClaude Codeを起動する環境に渡せば、helperがそのまま引き継いで使ってくれました。WORKSPACE_URLはhttps://を付けないホスト名(<workspace>.cloud.databricks.com)です。

#!/usr/bin/env bash
# 環境変数: DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET / WORKSPACE_URL / WORKSPACE_ID / CATALOG / SCHEMA
set -euo pipefail
T="$CATALOG.$SCHEMA.cc"
details='[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"'$CATALOG'"},
{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"'$CATALOG.$SCHEMA'"},
{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"'${T}_otel_logs'"},
{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"'${T}_otel_metrics'"}]'
token=$(curl -sf -X POST -u "$DATABRICKS_CLIENT_ID:$DATABRICKS_CLIENT_SECRET" \
-d grant_type=client_credentials -d scope=all-apis \
-d "resource=api://databricks/workspaces/$WORKSPACE_ID/zerobusDirectWriteApi" \
--data-urlencode "authorization_details=$details" \
"https://$WORKSPACE_URL/oidc/v1/token" | jq -r .access_token)
printf '{"Authorization": "Bearer %s"}\n' "$token"

確かめるときは、Claude Codeからモデルを呼べる状態(今回はAI Gateway経由)で、短いプロンプトを1回流してdebugログを見ます。

claude -p "Say hi." --debug-file /tmp/claude-debug.log
grep "3P telemetry" /tmp/claude-debug.log

これでFirst logs export: SUCCESSが出て、テーブルに入りました!!

ただ、この形だとSPのシークレットを各メンバーの端末に置くことになります、、、なので直接送るのは、個人や少人数での運用向けです。

組織に配るならトークンだけを配る

そこで、トークンだけを配る小さな仲介サービス(トークンブローカー)をDatabricks Appsで立てました。ログは端末からZerobusへ直接送ったままで、helperの呼び先だけを替えます。

Appsには専用のSPが付き、そのシークレットはAppsが環境変数で渡します。このSPをZerobusに書く役にすれば、シークレットを端末にもコードにも置かずに済みます! 呼んだ人のメールアドレスも、今回はX-Forwarded-Emailヘッダ(IdPから渡されるメールアドレスのヘッダ)で届きました。

アプリはこんな感じ。

import base64
import json
import os
import time
import urllib.parse
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
HOST = os.environ["DATABRICKS_HOST"].removeprefix("https://").rstrip("/")
WORKSPACE_ID = os.environ["DATABRICKS_WORKSPACE_ID"]
CLIENT_ID = os.environ["DATABRICKS_CLIENT_ID"]
CLIENT_SECRET = os.environ["DATABRICKS_CLIENT_SECRET"]
CATALOG, SCHEMA, PREFIX = os.environ["CATALOG"], os.environ["SCHEMA"], os.environ["TABLE_PREFIX"]
TABLES = [f"{CATALOG}.{SCHEMA}.{PREFIX}_otel_logs", f"{CATALOG}.{SCHEMA}.{PREFIX}_otel_metrics"]
def mint() -> str:
details = [
{"type": "unity_catalog_privileges", "privileges": ["USE CATALOG"], "object_type": "CATALOG", "object_full_path": CATALOG},
{"type": "unity_catalog_privileges", "privileges": ["USE SCHEMA"], "object_type": "SCHEMA", "object_full_path": f"{CATALOG}.{SCHEMA}"},
] + [
{"type": "unity_catalog_privileges", "privileges": ["SELECT", "MODIFY"], "object_type": "TABLE", "object_full_path": t}
for t in TABLES
]
body = urllib.parse.urlencode({
"grant_type": "client_credentials",
"scope": "all-apis",
"resource": f"api://databricks/workspaces/{WORKSPACE_ID}/zerobusDirectWriteApi",
"authorization_details": json.dumps(details),
}).encode()
req = urllib.request.Request(f"https://{HOST}/oidc/v1/token", data=body, method="POST")
req.add_header("Content-Type", "application/x-www-form-urlencoded")
req.add_header("Authorization", "Basic " + base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode())
with urllib.request.urlopen(req, timeout=20) as r:
return json.load(r)["access_token"]
class H(BaseHTTPRequestHandler):
def _send(self, code, obj):
b = json.dumps(obj).encode()
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(b)))
self.end_headers()
self.wfile.write(b)
def do_GET(self):
if self.path == "/healthz":
return self._send(200, {"ok": True})
if self.path != "/token":
return self._send(404, {"error": "not found"})
who = self.headers.get("X-Forwarded-Email") or self.headers.get("X-Forwarded-User")
if not who:
# 呼んだ人が分からないリクエストには配らない
return self._send(403, {"error": "no user identity"})
try:
tok = mint()
except Exception as e: # 失敗の中身はログにだけ出す
print(json.dumps({"ts": time.time(), "event": "mint_failed", "user": who, "error": str(e)[:300]}), flush=True)
return self._send(502, {"error": "mint failed"})
# 誰がいつトークンを取ったかを残す(アプリのログ)
print(json.dumps({"ts": time.time(), "event": "token_issued", "user": who}), flush=True)
self._send(200, {"Authorization": f"Bearer {tok}"})
def log_message(self, *a): # 既定のアクセスログ(トークンは含まない)は出さない
pass
if __name__ == "__main__":
ThreadingHTTPServer(("0.0.0.0", int(os.environ.get("DATABRICKS_APP_PORT", "8000"))), H).serve_forever()
# app.yaml
command: ["python", "app.py"]
env:
- name: CATALOG
value: <catalog>
- name: SCHEMA
value: <schema>
- name: TABLE_PREFIX
value: cc

デプロイしたら、アプリのSPに同じGRANTで2つのテーブルの権限を付け、アプリのCAN USEをメンバーのグループに与えます。端末のhelperは、自分のログインでブローカーを呼ぶだけです。managed settingsはotelHeadersHelperをこれに替え、ブローカーのURLをBROKER_URLとしてhelperを起動する環境に渡します(今回はDockerコンテナの環境変数で渡しました)。送れたかは、直接のときと同じくdebugログで見ます。

#!/usr/bin/env bash
set -euo pipefail
ut=$(databricks auth token -p "${DATABRICKS_PROFILE:-DEFAULT}" | jq -r .access_token)
curl -sf -H "Authorization: Bearer $ut" "$BROKER_URL/token"

ブローカーを試した結果と気をつけるところ

確かめたこと結果
ログインなしで/tokenを呼ぶ302(配らない)
自分のログインで呼ぶ200。アプリのログに呼んだ人のメールアドレス
もらったトークンで、許したテーブルに書く200
同じトークンで、別のスキーマのテーブルに書く403
同じトークンで、SQLやUnity CatalogのAPIを呼ぶ400 Invalid Token
SPのシークレットの無いDockerコンテナのClaude Codeから送る両方SUCCESS

最後の行だけは、Dockerコンテナの中にCLIのログインが無いので、ホストで取った自分のトークンを環境変数で渡しました。

実運用では、止まったときと、端末の前提に気をつけます。

  • ブローカーが落ちてhelperが失敗すると、helperが直るまでそのセッションのログは送られません。Appsは水平スケーリングで1〜5台に増やせますので、2台以上での冗長をしましょう
  • メンバーにdatabricks auth loginを済ませてもらう必要があります。社内のIdP(Oktaなどの認証基盤)の仕組みがあるなら、ブローカーはそちらに置いてもいいと思います!

ほかの選択肢: Collectorを挟む

端末とZerobusの間にCollectorを置く形も動きました。受けるのは共有トークンで照合、送信はCollectorがSPのOAuthで行います。今回はDocker Composeで、端末役のDockerコンテナと同じプロジェクトに置いて試しました。

services:
collector:
image: otel/opentelemetry-collector-contrib:0.164.0
command: ["--config=/etc/otelcol/collector.yaml"]
volumes: ["./collector.yaml:/etc/otelcol/collector.yaml:ro"]
environment: [DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET, WORKSPACE_URL, WORKSPACE_ID, REGION, CATALOG, SCHEMA, TABLE_PREFIX, INGEST_TOKEN]
claude: # 端末役。Claude Code を入れたイメージ(docker compose run claude claude -p "..." で動かす)
image: <Claude Code を入れたイメージ>
volumes: ["./managed-settings.json:/etc/claude-code/managed-settings.json:ro"]

collector.yamlは公式ページのHTTPの例に、受けの認証(bearertokenauth)を足したものです。exporterの名前は、0.164.0で警告が出ないotlp_httpにしました。

# 環境変数: INGEST_TOKEN(端末と共有するトークン)、DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET(SP)、
# WORKSPACE_URL / WORKSPACE_ID / REGION / CATALOG / SCHEMA / TABLE_PREFIX
extensions:
bearertokenauth/in:
scheme: Bearer
token: ${env:INGEST_TOKEN}
oauth2client/logs:
client_id: ${env:DATABRICKS_CLIENT_ID}
client_secret: ${env:DATABRICKS_CLIENT_SECRET}
token_url: https://${env:WORKSPACE_URL}/oidc/v1/token
scopes: ['all-apis']
endpoint_params:
resource: 'api://databricks/workspaces/${env:WORKSPACE_ID}/zerobusDirectWriteApi'
authorization_details:
- '[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"${env:CATALOG}"},{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"${env:CATALOG}.${env:SCHEMA}"},{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_logs"}]'
oauth2client/metrics:
client_id: ${env:DATABRICKS_CLIENT_ID}
client_secret: ${env:DATABRICKS_CLIENT_SECRET}
token_url: https://${env:WORKSPACE_URL}/oidc/v1/token
scopes: ['all-apis']
endpoint_params:
resource: 'api://databricks/workspaces/${env:WORKSPACE_ID}/zerobusDirectWriteApi'
authorization_details:
- '[{"type":"unity_catalog_privileges","privileges":["USE CATALOG"],"object_type":"CATALOG","object_full_path":"${env:CATALOG}"},{"type":"unity_catalog_privileges","privileges":["USE SCHEMA"],"object_type":"SCHEMA","object_full_path":"${env:CATALOG}.${env:SCHEMA}"},{"type":"unity_catalog_privileges","privileges":["SELECT","MODIFY"],"object_type":"TABLE","object_full_path":"${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_metrics"}]'
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
auth:
authenticator: bearertokenauth/in
processors:
batch:
timeout: 5s
exporters:
otlp_http/logs:
endpoint: https://${env:WORKSPACE_ID}.zerobus.${env:REGION}.cloud.databricks.com:443
auth:
authenticator: oauth2client/logs
headers:
x-databricks-zerobus-table-name: '${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_logs'
otlp_http/metrics:
endpoint: https://${env:WORKSPACE_ID}.zerobus.${env:REGION}.cloud.databricks.com:443
auth:
authenticator: oauth2client/metrics
headers:
x-databricks-zerobus-table-name: '${env:CATALOG}.${env:SCHEMA}.${env:TABLE_PREFIX}_otel_metrics'
service:
extensions: [bearertokenauth/in, oauth2client/logs, oauth2client/metrics]
pipelines:
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlp_http/logs]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlp_http/metrics]

Collectorは受け側でJSONもProtobufも受けて、Zerobusへ送るときにProtobufにしてくれます。なので端末側はhttp/jsonのままでよく、設定は送り先と共有トークンだけです。便利。

{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "http://collector:4318/v1/metrics",
"OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "http://collector:4318/v1/logs",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <共有トークン>"
}
}

トークンなしと間違ったトークンのリクエストは、どちらも401となり、SPのトークンを持つのはCollectorだけになります。

なお今回のCollectorは手元のDockerで、端末役のDockerコンテナから同じDockerのネットワーク越しに平文のHTTP(http://collector:4318)で送りました。組織に配るならTLSがあったほうがいいです。
ログがすべてCollectorを経由するので、止まったときの影響はブローカーより大きいため、運用はしっかりしましょうね!

溜まったログを眺める

分析用に、5人(2チーム)・3モデルでclaude -pを16回実行。14回はCollector経由、2回は直接で、1回はこのワークスペースで使えないモデルをわざと指定してエラーにしています。

入ったのはログ233行、メトリクス190行です!ログのイベントは、APIを1回呼ぶごとのapi_requestが41件、ツールの結果のtool_resultが20件、プロンプトのuser_promptが16件、エラーのapi_errorが1件などでした。

プロンプトの本文は16件すべて<REDACTED>。OTEL_LOG_USER_PROMPTSを有効にしない限り送られません。

もう1つ、user.emailはOAuthでサインインしたときに付く属性で、AI Gateway経由の今回は来ません、、、なのでOTEL_RESOURCE_ATTRIBUTES=user.email=alice@example.com,team.id=platformのように、架空のメンバー名を付けました。

整形はビューで

Databricksなら、生のテーブルはそのまま残して、整形はビューにすればOK。これならテーブルの形を作り直したくなっても、取り込み直しは要りません!

CREATE OR REPLACE VIEW <catalog>.<schema>.cc_api_requests AS
SELECT
attributes:['event.timestamp']::timestamp AS ts,
attributes:['user.email']::string AS user_email,
attributes:['team.id']::string AS team,
attributes:['session.id']::string AS session_id,
attributes:model::string AS model,
attributes:input_tokens::bigint AS input_tokens,
attributes:output_tokens::bigint AS output_tokens,
attributes:cache_read_tokens::bigint AS cache_read_tokens,
attributes:cache_creation_tokens::bigint AS cache_creation_tokens,
attributes:cost_usd::double AS cost_usd,
attributes:duration_ms::bigint AS duration_ms
FROM <catalog>.<schema>.cc_otel_logs
WHERE attributes:['event.name']::string = 'api_request';

分析はSQLで

まずメンバー別の分析。

SELECT team, user_email, count(DISTINCT session_id) AS sessions, count(*) AS api_requests,
round(sum(cost_usd), 4) AS est_cost_usd
FROM <catalog>.<schema>.cc_api_requests
GROUP BY ALL ORDER BY est_cost_usd DESC;
teamuser_emailsessionsapi_requestsest_cost_usd
datadave@example.com240.2926
platformalice@example.com4110.1749
datacarol@example.com390.1406
dataerin@example.com3100.0915
platformbob@example.com370.0414

呼び出しがいちばん少ないdaveが1位w daveの2セッションはどちらもOpusで、モデル別に並べると、Opusは1セッションあたりの推定コストがいちばん高いんですよね。

モデル別に並べると一目

SELECT model, count(*) AS api_requests, round(avg(duration_ms)) AS avg_ms,
round(sum(cache_read_tokens) / sum(input_tokens + cache_read_tokens + cache_creation_tokens), 3) AS cache_read_ratio,
round(sum(cost_usd) / count(DISTINCT session_id), 4) AS est_cost_per_session
FROM <catalog>.<schema>.cc_api_requests
GROUP BY 1 ORDER BY api_requests DESC;
modelapi_requestsavg_msキャッシュ読み取り率推定コスト(USD/セッション)
claude-sonnet-4-6243,2630.9660.0468
claude-haiku-4-5133,0390.9600.0148
claude-opus-4-643,8080.7270.1463

キャッシュ読み取り率は入力側のトークン(input_tokens+cache_read_tokens+cache_creation_tokens)のうちキャッシュから読めた割合です。ツールの成功率(Write 11回で1.0、Bash 9回で0.889)や書き足した行数(メトリクスのclaude_code.lines_of_code.count)も、同じノリで出せました!

cost_usdは定価で換算した推定値で、請求額ではありません。ただ完了した15回分の合計は、claude -pが返したtotal_cost_usdの合計と小数第7位まで同じ(0.7410283ドル)で、16セッションすべてのログも入っていました。契約単価に寄せるなら、managed settingsのmodelPricingが使えます。

ということで、Claude Codeのログ分析もDatabricksにおまかせ!

「ログを保存する」し、「生データを貯める」のを、ZerobusとUnity Catalogのテーブルがまとめてやってくれました!
ためてそのままSQLで分析できるので、収集から集計まで一気通貫に行けちゃいます!

特に分析の基盤がもうDatabricksにあるなら受け口もそこに寄せられる、という選択肢の1つだと思ってもらえればと!

最後に例として、同じビューをAI/BIのダッシュボードとGenieに載せてみました。SQLを書かない人でも、こんなふうに見られます!

参考

コメントをどうぞ

Trending