data-health-monitor

データヘルスモニター

目的

単一のコマンドで「データは正しく流れていますか？」という問いに回答します。ストリーム、ジョブ、スキーマ、イベントクォータ全体のヘルスシグナルを集約し、統一された実行可能なレポートを作成します。読み取り専用です。

環境

認証済みの API アクセスが必要です。認証情報の解決については、../references/auth.md を参照してください。

フロー

4 つのヘルスチェックをすべて実行してから、統合レポートを提示します。ユーザーが特定の領域について質問した場合は、その項目に焦点を当てつつ、ほかの項目の概要も表示します。

チェック 1：ストリームのヘルス

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/stream" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

各ストリームについて、次のシグナルを評価します。

シグナル	検出方法	重要度
アクティブ	last_msg_ts が過去 1 時間以内	HEALTHY
停滞（継続的）	last_msg_ts が 1～24 時間前	WARNING
停滞（バッチ）	last_msg_ts が 2～7 日前	WARNING
停止	last_msg_ts が 24 時間より前（継続的）または 7 日より前（バッチ）	ERROR
受信履歴なし	ct == 0	ERROR

ストリームに関連付けられたジョブに定期スケジュールがあるか確認し、バッチか継続的かを判別します。

問題のあるストリームについては、詳細を確認するために直近の統計情報を取得します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/stream/${STREAM_NAME}/stats" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

チェック 2：ジョブのヘルス

# Active jobs (default: non-terminal states)
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Also check recently failed jobs
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job?show_completed=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

各ジョブを評価します。

ステータス	重要度	アクション
runnable	HEALTHY	正常に実行中
sleeping	HEALTHY	スケジュール済み。次の実行を待機中
paused	WARNING	意図的な停止ですが、注意が必要です
fault	ERROR	調査が必要です。ログを取得してください
failed	ERROR	終了状態の失敗です。ログを取得してください
killed	INFO	手動で停止済み

障害が発生したジョブや失敗したジョブについては、ログを取得します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/job/${JOB_ID}/logs" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

また、停滞しているジョブがないか確認します。runnable ジョブの updated が 1 時間以上前の場合、処理が停止している可能性があります。

チェック 3：スキーマのヘルス

# Get all fields with metadata
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

次を確認します。

• 識別子フィールド：IsIdentifier == true のフィールド数を数えます。2 つ未満の場合は警告します。
• PII フィールド：注意喚起のため、IsPII == true とマークされたフィールド数を数えます。
• 古いフィールド：Modified タイムスタンプが 30 日より前で、現在も使用されているフィールドを確認します。

カバレッジをさらに詳しく分析する場合：

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldinfo" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

フィールドの存在率と欠落率を確認します。カバレッジが非常に低く、セグメントの FilterQL に登場するフィールドには警告します。

チェック 4：イベントクォータ

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/control/eventquota/thresholds" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

現在の使用量を、しきい値（50%、75%、100%、125%）と照らし合わせて報告します。

任意：メトリクスの詳細分析

ユーザーが傾向や詳細な分析を求めている場合：

# Stream throughput over last 24h
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=stream&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Job execution metrics over last 24h
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=works&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

# Segment size trends
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/metric?dimension=segment&range=now-24h" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

傾向として提示します。「ストリームのスループットは昨日と比べて 40% 低下しています」や「セグメントのサイズは安定しています」など。

出力形式

次の形式でレポートを提示します。

## Data Health Report

### Overall: HEALTHY | NEEDS ATTENTION | UNHEALTHY

### Streams (N total)
  HEALTHY: X streams actively receiving data
  WARNING: 'stream_name' -- last event 3 days ago
  ERROR: 'stream_name' -- never received events

### Jobs (N active)
  HEALTHY: X jobs running normally
  FAULT: 'job_name' -- error message from logs
  PAUSED: 'job_name' -- paused since date

### Schema (user table, N fields)
  Identity fields: N configured (field1, field2, ...)
  Low coverage: 'field' at X%
  Stale: 'field' not updated in N days

### Event Quota
  Current usage: X% of monthly quota

### Recommendations
1. Specific actionable recommendation
2. Another recommendation
3. ...

重要度の判定ロジック

全体ステータス	判定基準
HEALTHY	すべてのストリームがアクティブで、すべてのジョブが実行中、障害がなく、クォータが 75% 未満
NEEDS ATTENTION	次のいずれかに該当：停滞したストリーム、一時停止中のジョブ、カバレッジの低いフィールド、クォータが 75～100%
UNHEALTHY	次のいずれかに該当：障害が発生したジョブまたは失敗したジョブ、停止したストリーム、クォータが 100% 超

推奨事項の生成

検出結果に基づき、具体的で実行可能な推奨事項を生成します。

• 障害が発生したジョブ → 「ジョブ 'job_name' の障害を調査してください。認証情報を確認するか、ジョブを再起動してください。」
• 停止したストリーム → 「ストリーム 'name' は N 日間データを受信していません。ソース連携を確認してください。」
• イベント数ゼロのストリーム → 「ストリーム 'name' は設定されていますが、データを一度も受信していません。連携が正しく設定されていることを確認してください。」
• 識別子フィールドが少ない → 「設定されている識別子フィールドは N 個のみです。プロファイルの解決精度を高めるため、追加のフィールドを識別子として設定することを検討してください。」
• クォータが上限に接近 → 「イベントクォータは X% に達しています。イベント量の多いストリームを見直すか、プランのアップグレードを検討してください。」
• 古いフィールド → 「フィールド 'name' は N 日間更新されていません。ソース連携が引き続き有効か確認してください。」

エラー処理

• いずれかのチェックで API エラーが発生した場合：該当する項目のエラーを報告し、ほかのチェックを続行します。1 つのチェックの失敗によってレポート全体を中断しないでください。
• 応答が空の場合：「[streams/jobs/fields] が見つかりません」と報告します。新規アカウント、または未設定のアカウントである可能性があります。
• タイムアウト：チェックに時間がかかりすぎる場合は、注記を添えてスキップし、続行します。

Dependencies

• Composes: stream-inspector skill, job-manager skill, schema-manager skill
• References: ../references/auth.md, ../references/api-client.md