Skills 監視と可観測性
Skill を公開した後、それがうまく機能しているかどうかをどうやって知るのでしょうか?頻繁にエラーが発生していないか?どのステップが最も遅いか?
この記事では、Skill に可観測性を構築し、ログとメトリクスを通じて実行状態を把握する方法を紹介します。
可観測性の3つの次元
| 次元 | 答えられる質問 | 実装方法 |
|---|---|---|
| ログ | 何が発生したか?何がエラーか? | 構造化JSONログファイル |
| メトリクス | 何回実行されたか?所要時間は?成功率は? | メトリクスファイルへの追記 |
| 実行記録(トレース) | 各実行でどのステップを経たか?各ステップの所要時間は? | ステップレベルのタイムスタンプ記録 |
構造化ログの出力仕様
Skill スクリプトは実行ログを固定パスのファイルに書き込み、後で確認しやすくする必要があります。
例
# ファイルパス:scripts/skill_logger.py
import json
import os
import sys
from datetime import datetime, timezone
LOG_FILE = "/home/claude/skill_run.log"
def log(level: str, event: str, skill: str = "", **context):
"""
構造化ログエントリを書き込む
パラメータ:
level: ログレベル(info / warning / error)
event: イベント名(snake_case)
skill: Skill 名
context: 任意の追加フィールド
"""
entry = {
"ts": datetime.now(timezone.utc).isoformat(),
"level": level,
"event": event,
"skill": skill,
**context
}
line = json.dumps(entry, ensure_ascii=False)
# stderr(リアルタイムで確認可能)とログファイル(永続化)の両方に出力
print(line, file=sys.stderr)
with open(LOG_FILE, "a", encoding="utf-8") as f:
f.write(line + "\n")
# 使用例
if __name__ == "__main__":
log("info", "skill_start", skill="data-analyzer",
file="/mnt/user-data/uploads/サンプル.csv")
log("info", "step_complete", skill="data-analyzer",
step="clean", rows_removed=3, elapsed_ms=240)
log("info", "skill_complete", skill="data-analyzer",
output="/mnt/user-data/outputs/report.xlsx", elapsed_ms=1830)
log("error", "step_failed", skill="data-analyzer",
step="generate_chart", error="openpyxl not found")
import json
import os
import sys
from datetime import datetime, timezone
LOG_FILE = "/home/claude/skill_run.log"
def log(level: str, event: str, skill: str = "", **context):
"""
構造化ログエントリを書き込む
パラメータ:
level: ログレベル(info / warning / error)
event: イベント名(snake_case)
skill: Skill 名
context: 任意の追加フィールド
"""
entry = {
"ts": datetime.now(timezone.utc).isoformat(),
"level": level,
"event": event,
"skill": skill,
**context
}
line = json.dumps(entry, ensure_ascii=False)
# stderr(リアルタイムで確認可能)とログファイル(永続化)の両方に出力
print(line, file=sys.stderr)
with open(LOG_FILE, "a", encoding="utf-8") as f:
f.write(line + "\n")
# 使用例
if __name__ == "__main__":
log("info", "skill_start", skill="data-analyzer",
file="/mnt/user-data/uploads/サンプル.csv")
log("info", "step_complete", skill="data-analyzer",
step="clean", rows_removed=3, elapsed_ms=240)
log("info", "skill_complete", skill="data-analyzer",
output="/mnt/user-data/outputs/report.xlsx", elapsed_ms=1830)
log("error", "step_failed", skill="data-analyzer",
step="generate_chart", error="openpyxl not found")
{"ts": "2026-05-18T10:23:05+00:00", "level": "info", "event": "skill_start", "skill": "data-analyzer", "file": "/mnt/user-data/uploads/サンプル.csv"}
{"ts": "2026-05-18T10:23:05+00:00", "level": "info", "event": "step_complete", "skill": "data-analyzer", "step": "clean", "rows_removed": 3, "elapsed_ms": 240}
{"ts": "2026-05-18T10:23:07+00:00", "level": "info", "event": "skill_complete", "skill": "data-analyzer", "output": "/mnt/user-data/outputs/report.xlsx", "elapsed_ms": 1830}
{"ts": "2026-05-18T10:23:07+00:00", "level": "error", "event": "step_failed", "skill": "data-analyzer", "step": "generate_chart", "error": "openpyxl not found"}
メトリクス集約:実行回数と成功率の集計
ログファイルから主要なメトリクスを抽出し、Skill の全体的な実行状況を把握します。
例
# ファイルパス:scripts/metrics_report.py
# ログファイルから Skill の実行メトリクスを集計
import json
import os
from collections import defaultdict
LOG_FILE = "/home/claude/skill_run.log"
def generate_metrics_report(log_file: str) -> dict:
"""ログファイルを読み込み、メトリクスのサマリーを生成"""
if not os.path.exists(log_file):
return {"error": f"ログファイルが存在しません:{log_file}"}
counts = defaultdict(int) # 各種イベントのカウント
errors = [] # エラー記録
elapsed = [] # 実行所要時間リスト(ms)
with open(log_file, encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line:
continue
try:
entry = json.loads(line)
except json.JSONDecodeError:
continue
event = entry.get("event", "")
counts[event] += 1
if entry.get("level") == "error":
errors.append({
"ts": entry.get("ts"),
"event": event,
"error": entry.get("error", ""),
"step": entry.get("step", "")
})
if event == "skill_complete" and "elapsed_ms" in entry:
elapsed.append(entry["elapsed_ms"])
total_runs = counts.get("skill_start", 0)
total_errors = len(errors)
success_rate = round((total_runs - total_errors) / total_runs * 100, 1) \
if total_runs > 0 else 0
return {
"total_runs": total_runs,
"total_errors": total_errors,
"success_rate": f"{success_rate}%",
"avg_elapsed_ms": round(sum(elapsed) / len(elapsed)) if elapsed else 0,
"recent_errors": errors[-5:] # 直近5件のエラー
}
if __name__ == "__main__":
report = generate_metrics_report(LOG_FILE)
print(json.dumps(report, ensure_ascii=False, indent=2))
# ログファイルから Skill の実行メトリクスを集計
import json
import os
from collections import defaultdict
LOG_FILE = "/home/claude/skill_run.log"
def generate_metrics_report(log_file: str) -> dict:
"""ログファイルを読み込み、メトリクスのサマリーを生成"""
if not os.path.exists(log_file):
return {"error": f"ログファイルが存在しません:{log_file}"}
counts = defaultdict(int) # 各種イベントのカウント
errors = [] # エラー記録
elapsed = [] # 実行所要時間リスト(ms)
with open(log_file, encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line:
continue
try:
entry = json.loads(line)
except json.JSONDecodeError:
continue
event = entry.get("event", "")
counts[event] += 1
if entry.get("level") == "error":
errors.append({
"ts": entry.get("ts"),
"event": event,
"error": entry.get("error", ""),
"step": entry.get("step", "")
})
if event == "skill_complete" and "elapsed_ms" in entry:
elapsed.append(entry["elapsed_ms"])
total_runs = counts.get("skill_start", 0)
total_errors = len(errors)
success_rate = round((total_runs - total_errors) / total_runs * 100, 1) \
if total_runs > 0 else 0
return {
"total_runs": total_runs,
"total_errors": total_errors,
"success_rate": f"{success_rate}%",
"avg_elapsed_ms": round(sum(elapsed) / len(elapsed)) if elapsed else 0,
"recent_errors": errors[-5:] # 直近5件のエラー
}
if __name__ == "__main__":
report = generate_metrics_report(LOG_FILE)
print(json.dumps(report, ensure_ascii=False, indent=2))
{
"total_runs": 42,
"total_errors": 3,
"success_rate": "92.9%",
"avg_elapsed_ms": 1650,
"recent_errors": [
{"ts": "2026-05-18T09:12:00+00:00", "event": "step_failed", "step": "generate_chart", "error": "openpyxl not found"}
]
}
実行トレース:各ステップの所要時間を記録
特定の実行が特に遅い場合、ステップレベルの所要時間記録によりボトルネックを迅速に特定できます。
例
# ファイルパス:scripts/tracer.py
import time
import json
import sys
from skill_logger import log
class ExecutionTracer:
"""Skill 実行中の各ステップの所要時間を記録"""
def __init__(self, skill_name: str):
self.skill_name = skill_name
self.steps = []
self.start_time = time.perf_counter()
def step(self, step_name: str):
"""ステップの開始をマークし、前のステップの所要時間を自動的に記録"""
now = time.perf_counter()
if self.steps:
# 前のステップの所要時間を計算
self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
del self.steps[-1]["_start"]
self.steps.append({"name": step_name, "_start": now})
log("info", "step_start", skill=self.skill_name, step=step_name)
def finish(self):
"""実行の終了をマークし、完全なトレースレポートを出力"""
now = time.perf_counter()
if self.steps:
self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
del self.steps[-1]["_start"]
total_ms = int((now - self.start_time) * 1000)
report = {"skill": self.skill_name,
"total_ms": total_ms, "steps": self.steps}
log("info", "trace_complete", skill=self.skill_name,
total_ms=total_ms, steps=self.steps)
return report
# 使用例
if __name__ == "__main__":
tracer = ExecutionTracer("data-analyzer")
tracer.step("ファイル読み込み")
time.sleep(0.3) # 時間のかかる操作をシミュレート
tracer.step("データクレンジング")
time.sleep(0.1)
tracer.step("レポート生成")
time.sleep(0.8)
report = tracer.finish()
print(json.dumps(report, ensure_ascii=False, indent=2))
import time
import json
import sys
from skill_logger import log
class ExecutionTracer:
"""Skill 実行中の各ステップの所要時間を記録"""
def __init__(self, skill_name: str):
self.skill_name = skill_name
self.steps = []
self.start_time = time.perf_counter()
def step(self, step_name: str):
"""ステップの開始をマークし、前のステップの所要時間を自動的に記録"""
now = time.perf_counter()
if self.steps:
# 前のステップの所要時間を計算
self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
del self.steps[-1]["_start"]
self.steps.append({"name": step_name, "_start": now})
log("info", "step_start", skill=self.skill_name, step=step_name)
def finish(self):
"""実行の終了をマークし、完全なトレースレポートを出力"""
now = time.perf_counter()
if self.steps:
self.steps[-1]["elapsed_ms"] = int((now - self.steps[-1]["_start"]) * 1000)
del self.steps[-1]["_start"]
total_ms = int((now - self.start_time) * 1000)
report = {"skill": self.skill_name,
"total_ms": total_ms, "steps": self.steps}
log("info", "trace_complete", skill=self.skill_name,
total_ms=total_ms, steps=self.steps)
return report
# 使用例
if __name__ == "__main__":
tracer = ExecutionTracer("data-analyzer")
tracer.step("ファイル読み込み")
time.sleep(0.3) # 時間のかかる操作をシミュレート
tracer.step("データクレンジング")
time.sleep(0.1)
tracer.step("レポート生成")
time.sleep(0.8)
report = tracer.finish()
print(json.dumps(report, ensure_ascii=False, indent=2))
{
"skill": "data-analyzer",
"total_ms": 1203,
"steps": [
{"name": "读取文件", "elapsed_ms": 312},
{"name": "数据清洗", "elapsed_ms": 108},
{"name": "生成报告", "elapsed_ms": 783}
]
}
その他の拡張可観測性は大規模システムだけに必要なわけではありません。個人で使用する Skill であっても、問題が発生した場合、明確なログファイルがあれば、調査時間を数時間から数分に短縮できることがよくあります。