コンテンツにスキップ

Studio セルフモニタリング設定とメトリクス説明

本ドキュメントでは、デプロイメントプランの Studio 側でセルフモニタリング設定が有効かどうかを確認する方法と、セルフモニタリングのメジャーメント df_studio における API、Celery 非同期タスク、Redis/Broker、ビジネスタスク、エクスポートチェーンに関連するメトリクス、タグ、単位、およびモニタリングの推奨事項について説明します。

適用バージョン

  • セルフモニタリングのアクティブメトリクス機能は、2026 年 5 月 20 日リリースバージョンから提供されています。
  • 2026 年 5 月 13 日リリースバージョンでは、このアクティブメトリクス機能はまだサポートされていません。
  • Lark のチケットで、最新のデプロイメントプラン v1.130.225 がこの機能をサポートしていることが確認されています。このバージョンは Studio の現在のシステムコミット 60a71d992 に対応しており、本ドキュメントのメトリクスと設定はこのコミットに基づいて確認済みです。
  • 環境が v1.130.225 より低い場合は、アップグレードしてから設定することを推奨します。

収集チェーン

Studio アプリケーション側は、外部サービスにメトリクスを能動的にプッシュしません。推奨されるチェーンは以下の通りです。

Studio API / Celery / WebSocket / Snapshot
  -> アプリケーション内軽量メトリクス記録
  -> Redis メトリクスキャッシュ
  -> inner /metrics Prometheus テキストエクスポート
  -> Datakit 定期プル
  -> セルフモニタリングワークスペース
  -> ダッシュボード / モニター / アラート

Datakit のプルアドレスは以下の通りです。

http://<inner-service-ip>:5000/api/v1/inner/metrics?from=datakit&type=df_studio

Prometheus テキストエクスポートは、例えば df_studio_celery_task_published_total のような完全なメトリクス名を出力します。Guance UI または DQL では、通常「メジャーメント + フィールド」でクエリします。つまり、メジャーメントは df_studio、フィールドは celery_task_published_total となります。

セルフモニタリング設定が有効かどうかを確認する方法

1. Studio バックエンド設定の確認

Studio バックエンドの設定項目は SelfMonitorMetricsSet です。デフォルトでは無効になっており、ユーザーは enable を明示的に有効にする必要があります。

SelfMonitorMetricsSet:
  enable: true

その他の設定はデフォルトのままで問題ありません。各設定の意味は以下の通りです。

設定項目 デフォルト値 単位 説明
enable false ブール値 セルフモニタリングの統一スイッチ。true の場合のみ、API、Celery、ビジネスタスク、/metrics エクスポート関連のメトリクスが記録されます。
expireSeconds 3600 秒 Redis における周期増分メトリクスの保持ウィンドウ。
stateExpireSeconds 604800 秒 beat の最終公開時刻、ビジネスタスクの最終成功/失敗時刻などの状態メトリクスの保持ウィンドウ。
beatMissedLagThresholdSeconds 300 秒 beat 公開後、実行が開始されていないと判断するためのデフォルトの遅延しきい値。
beatMissedIntervalMultiplier 2 倍数 低頻度 beat のスケジュール漏れを判断する際に使用する、最新の公開間隔の倍数。
celeryQueues celery、correlation_task、snapshot_queue、compute_task リスト キュー長と最長待機時間を読み取る必要がある Celery キュー。

環境変数で上書きすることも可能です。

STUDIO__SelfMonitorMetricsSet__enable=true

注意: enable はブール値の true または false である必要があります。不正な文字列や null は設定の読み込みに失敗する原因となります。

2. /metrics がセルフモニタリングメトリクスを出力しているか確認

クラスタ内で inner サービスにアクセスします。

curl 'http://management-backend.forethought-core:5000/api/v1/inner/metrics?from=datakit&type=df_studio'

有効になっており、エクスポートが正常な場合、レスポンスに以下のような内容が表示されるはずです。

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="success"} 1
df_studio_self_monitor_export_duration_seconds{exporter="prometheus_inner",result="success"} ...
df_studio_self_monitor_export_last_success_timestamp_seconds{exporter="prometheus_inner"} ...

エクスポート中に例外が発生した場合、インターフェースは fail-open し、可能な限り失敗メトリクスを返します。

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="failure"} 1
df_studio_self_monitor_export_error_total{exception_type="...",exporter="prometheus_inner"} 1
df_studio_self_monitor_export_last_failure_timestamp_seconds{exception_type="...",exporter="prometheus_inner"} ...

3. 従来のヘルスチェックインターフェースの確認

管理バックエンドには、引き続き Celery worker のヘルスチェックインターフェースが用意されています。

curl 'http://management-backend.forethought-core:5000/api/v1/const/celery/ping'

このインターフェースは、Redis 内の celery_active_point を読み取り、各キューの最終アクティブ時刻を返します。200 を返す場合は、設定された有効オフセット時間内にアクティブポイントがあることを示します。400 を返す場合は、通常、対応する worker が長時間アクティブポイントを更新していないことを示し、worker が実行されていない、タスクが滞留している、Redis/Broker 接続に異常があるなどの可能性があります。

このインターフェースは互換性のあるヘルスチェックとして適しています。完全なセルフモニタリングとしては、下記の df_studio メトリクスを優先的に使用することを推奨します。

メトリクスとタグの規則

グローバルタグ

タグ 適用範囲 意味 一般的な値 使用推奨事項
service API サービスエントリ名 front、inner、openapi、admin、external、center、aiapi、sse カーディナリティが低いため、サマリーに使用できます。
run_app_code API 現在のプロセス実行エントリ service と同じ カーディナリティが低く、エントリの識別に使用できます。
route_rule API Flask route ルール /api/v1/... 元の URL よりも集約に適しています。
method API HTTP メソッド GET、POST、PUT カーディナリティが低い。
status_class API HTTP ステータスコードクラス 2xx、4xx、5xx 成功率、エラー率の計算に使用します。
queue Celery Celery キュー名 celery、correlation_task、snapshot_queue、compute_task カーディナリティが低く、非同期タスクサマリーの主要ディメンションです。
task Celery / ビジネスタスク Celery タスク名またはビジネスタスク名 forethought.tasks...、statistics_upload カーディナリティが中程度で、タスクレベルのトラブルシューティングに使用します。
status Celery タスクの終了状態 success、failure、retry タスク品質分析に使用します。
exception_type Celery / エクスポートチェーン 例外タイプ TimeoutError、OperationalError 例外 TopN 分析に使用します。
beat_name Celery beat beat エントリ名 設定内の beat entry 名 定期タスクのスケジュール漏れを判断するために使用します。
domain ビジネスタスク ビジネスドメイン archive_report、incidents、billing、cleanup カーディナリティが低く、ビジネスタスクサマリーの主要ディメンションです。
result ビジネスタスク / エクスポートチェーン 実行結果 success、error、failure、partial_success、skipped 成功率と失敗率の計算に使用します。
item_type ビジネスタスク 処理オブジェクトタイプ workspace、report_task、notification カーディナリティが低い。
reason ビジネスタスク 部分的な失敗理由 notify_failed、item_error 列挙を制御することで、アラートに使用できます。
entry 独立エントリ Flask 以外のエントリ websocket、snapshot 独立エントリのヘルスチェックに使用します。
event 独立エントリ エントリイベント connect、disconnect、send_task エントリイベント分析に使用します。
state 状態メトリクス 状態名 size、checked_out、overflow 具体的な意味はメトリクスに依存します。
exporter /metrics エクスポート エクスポーター名 prometheus_inner カーディナリティが低い。
le Histogram bucket バケット上限 0.1、1、5、+Inf _bucket メトリクスのパーセンタイル計算にのみ使用されます。

le は histogram bucket の「以下」の上限を意味し、ビジネスディメンションではありません。例えば、le="1" は 1 秒以下のサンプル累積数を示し、le="+Inf" は全サンプル数を示します。

API メトリクス

メトリクスフィールド 単位 タグ 意味
api_request_count 回 service、api_path 旧 API の非 5xx リクエスト数との互換性維持。
api_request_error_count 回 service、api_path 旧 API の 5xx リクエスト数との互換性維持。
api_requests_total 回 service、run_app_code、route_rule、method、status_class API リクエスト総数、周期増分。
api_errors_total 回 service、run_app_code、route_rule、method、status_class、error_type API エラー数、現在は主に HTTP 5xx をカバー。
api_duration_seconds_bucket 秒 service、run_app_code、route_rule、method、status_class、le API リクエストのレイテンシ分布。
api_duration_seconds_sum 秒 service、run_app_code、route_rule、method、status_class API リクエストのレイテンシ合計。
api_duration_seconds_count 回 service、run_app_code、route_rule、method、status_class API リクエストのレイテンシサンプル数。

Celery キューとタスクメトリクス

以下のメトリクスは、コミット 60a71d992 において Celery signals を介して書き込まれ、df_studio メジャーメントからエクスポートされます。worker_queue_count と celery_queue_oldest_wait_seconds は Redis broker キューを直接読み取り、Redis/Broker キュー内の滞留や worker による未消費を検出するために使用されます。Celery タスクライフサイクルメトリクスは、「消費未開始」と「開始後にスタック」をさらに区別するために使用されます。

メトリクスフィールド 単位 タグ 意味
worker_queue_count 個 queue Redis broker キューの現在の長さ。
celery_queue_oldest_wait_seconds 秒 queue キュー内の最古タスクの公開時点からの待機時間。
celery_task_published_total 回 task、queue Celery タスクの公開回数。
celery_task_started_total 回 task、queue Celery タスクの実行開始回数。
celery_task_finished_total 回 task、queue、status Celery タスクの終了回数、ステータス別。
celery_task_active 個 task、queue 現在実行中の Celery タスク数。
celery_task_duration_seconds_bucket 秒 task、queue、le タスク実行レイテンシ分布。
celery_task_duration_seconds_sum 秒 task、queue タスク実行レイテンシ合計。
celery_task_duration_seconds_count 回 task、queue タスク実行レイテンシサンプル数。
celery_task_queue_wait_seconds_bucket 秒 task、queue、le タスク公開から実行開始までのキューイング待機時間分布。
celery_task_queue_wait_seconds_sum 秒 task、queue タスクキューイング待機時間合計。
celery_task_queue_wait_seconds_count 回 task、queue タスクキューイング待機時間サンプル数。
celery_task_failure_exception_total 回 task、queue、exception_type タスク失敗の例外タイプ分布。
celery_task_timeout_total 回 task、queue、timeout_type Celery soft/hard timeout 回数。
celery_task_retry_total 回 task、queue、exception_type タスクリトライ回数。
celery_task_retry_delay_seconds_bucket 秒 task、queue、le タスクリトライ遅延分布。
celery_task_retry_delay_seconds_sum 秒 task、queue タスクリトライ遅延合計。
celery_task_retry_delay_seconds_count 回 task、queue タスクリトライ遅延サンプル数。

Beat と定期タスクメトリクス

メトリクスフィールド 単位 タグ 意味
celery_beat_task_last_publish_timestamp_seconds Unix 秒 beat_name、task beat エントリが最後にタスクを公開した時刻。
celery_beat_task_last_started_timestamp_seconds Unix 秒 beat_name、task beat エントリに対応するタスクが最後に実行を開始した時刻。
celery_beat_lag_seconds 秒 beat_name、task beat がタスクを公開してから worker が実行を開始するまでの遅延。
celery_beat_publish_interval_seconds 秒 beat_name、task beat エントリの最新の 2 つの公開間の実際の間隔。
celery_beat_missed ブール値 beat_name、task スケジュール漏れの疑いがあるかどうか。1 はスケジュール漏れの疑いがあることを示す。

ビジネスタスクメトリクス

メトリクスフィールド 単位 タグ 意味
business_task_runs_total 回 domain、task、result ビジネスタスクの実行回数。
business_task_items_total 個 domain、task、item_type、result ビジネスタスクの処理オブジェクト数。
business_task_duration_seconds_bucket 秒 domain、task、result、le ビジネスタスクのエンドツーエンドレイテンシ分布。
business_task_duration_seconds_sum 秒 domain、task、result ビジネスタスクのエンドツーエンドレイテンシ合計。
business_task_duration_seconds_count 回 domain、task、result ビジネスタスクのエンドツーエンドレイテンシサンプル数。
business_task_last_success_timestamp_seconds Unix 秒 domain、task ビジネスタスクの最終成功時刻。
business_task_last_failure_timestamp_seconds Unix 秒 domain、task、exception_type ビジネスタスクの最終失敗時刻。
business_task_partial_failure_total 回 domain、task、reason タスク全体は失敗していないが、部分的な失敗が発生した回数。

現在接続されているビジネスドメインは以下の通りです。

domain 代表的なタスク 注目ポイント
archive_report アーカイブレポート v2/v3、初回周期通知、遅延通知 レポートのトリガー、スクリーンショット、通知が成功したか、部分的な失敗がないか。
incidents インシデントオンコールポリシー分析、インシデントキュー同期、インシデント通知送信 インシデント通知チェーンが成功したか、滞留していないか。
billing 課金統計レポート 時間通りか、成功したか、処理されたワークスペース数。
workspace_usage OpenAPI API Key 使用量のデータベース更新 使用量更新が成功したか、処理されたバケットとアクセスキー数。
cleanup ダッシュボード履歴クリーンアップなど クリーンアップタスクが長期にわたって失敗またはスキップされていないか。
sync_config インテグレーションテンプレート同期 設定同期が成功したか。
notification Status Page ステータス変更通知 通知タスクが成功したか、失敗したか。
keyevent キーイベント未復旧非同期クエリ キーイベント非同期クエリに異常がないか。
cloud_collector クラウドコレクター非同期操作 非同期操作の分割、ロック待機、成功/失敗。
catalog 統合カタログエンティティ健全性 エンティティ健全性タスクが時間通りか、成功したか、処理量に異常がないか。
snapshot ダッシュボードスクリーンショット、チャートスクリーンショット、チャートデータ生成 スナップショットサービスのスクリーンショット/チャートデータタスクの結果。

独立エントリと依存関係健全性メトリクス

メトリクスフィールド 単位 タグ 意味
service_entry_events_total 回 entry、event、result WebSocket、snapshot などの Flask 以外のエントリイベント回数。
service_entry_active 個/ブール値 entry、state Flask 以外のエントリの現在のアクティブ状態。
dependency_db_pool_connections 個 pool、state exporter が存在するプロセスのデータベース接続プールの現在の状態。state には size、checked_in、checked_out、overflow が含まれます。
self_monitor_export_total 回 exporter、result /metrics の今回のエクスポート結果。
self_monitor_export_points_total 個 exporter、result /metrics で今回正常にエクスポートされた Prometheus サンプル数。
self_monitor_export_duration_seconds 秒 exporter、result /metrics の今回のエクスポートにかかった時間。
self_monitor_export_last_success_timestamp_seconds Unix 秒 exporter 最終正常エクスポート時刻。
self_monitor_export_last_failure_timestamp_seconds Unix 秒 exporter、exception_type 最終 fail-open 失敗エクスポート時刻。
self_monitor_export_error_total 回 exporter、exception_type 今回の fail-open 失敗イベント。

非同期タスクと Redis/Broker モニタリングに関する推奨事項

お客様が注目する「非同期タスクに異常がないか、Redis が切断されていないか、worker がハングアップしていないか」は、単一のメトリクスだけで判断するのではなく、組み合わせ条件で判断することを推奨します。

シナリオ 優先的に観察するメトリクス 推奨ディメンション 判断方法
worker が消費しない、または消費能力が不足している worker_queue_count、celery_queue_oldest_wait_seconds、celery_task_published_total、celery_task_started_total queue、task キュー長と最長待機時間が継続的に上昇し、published は増加しているが started が非常に低い場合、通常は worker が消費していない、消費不足、または broker との接続に異常があることを示します。
Redis/Broker は読み取り可能だが worker が切断されている worker_queue_count、celery_queue_oldest_wait_seconds、celery_task_active queue exporter がキューを読み取れ、キュー滞留が増加しているが、active が長期間 0 または明らかに低い場合、worker 側の切断、ハングアップ、または未起動を優先的に疑います。
Redis/Broker が完全に使用不可、または exporter の読み取りに失敗 self_monitor_export_total、self_monitor_export_error_total、self_monitor_export_last_failure_timestamp_seconds、self_monitor_export_points_total exporter、exception_type /metrics が fail-open し、失敗時刻が更新され、サンプル数が明らかに減少している場合、収集チェーン自体が Redis、DB、またはメトリクスソースへのアクセスに失敗している可能性があります。
タスク開始後にハングアップし終了しない celery_task_active、celery_task_started_total、celery_task_finished_total、celery_task_duration_seconds_bucket queue、task active が長時間低下せず、started は増加するが finished が増加しない、またはレイテンシ P99 が継続的に上昇している場合、タスクが外部呼び出し、ロック、DB、またはループロジックでスタックしている可能性があります。
タスク失敗またはリトライストーム celery_task_finished_total、celery_task_failure_exception_total、celery_task_retry_total、celery_task_retry_delay_seconds_bucket task、exception_type failure/retry が同時に上昇し、かつ例外タイプが集中している場合、タスクが失敗リトライループに入っている可能性があります。
beat は正常に公開しているが worker が開始していない celery_beat_task_last_publish_timestamp_seconds、celery_beat_task_last_started_timestamp_seconds、celery_beat_lag_seconds、celery_beat_missed beat_name、task last_publish は更新されるが last_started が更新されず、lag が上昇するか missed=1 の場合、定期タスクは配信されたが worker が消費を開始していないことを示します。
beat が公開を停止、または低頻度タスクのスケジュール漏れ celery_beat_publish_interval_seconds、celery_beat_task_last_publish_timestamp_seconds、celery_beat_missed beat_name、task publish interval が履歴周期を超えている、または last_publish が古すぎる場合、beat が停止している、設定が有効でない、またはスケジューラーに異常がある可能性があります。
ビジネスタスクは全体的に成功しているが、一部のオブジェクトで失敗 business_task_partial_failure_total、business_task_items_total、business_task_runs_total domain、task、reason、item_type partial failure が増加しているが、タスク全体は partial_success のままである可能性があり、具体的なビジネスオブジェクトの失敗理由を確認する必要があります。
ビジネスタスクが長時間成功していない business_task_last_success_timestamp_seconds、business_task_last_failure_timestamp_seconds、business_task_runs_total domain、task last_success が現在時刻から大きく遅れ、かつ last_failure が更新されているか、runs に success がない場合、そのビジネスチェーンがサイレントに失敗している可能性があります。

少なくとも以下のアラートを設定することを推奨します。

アラート項目 推奨レベル 推奨条件
セルフモニタリングエクスポート失敗 P0 self_monitor_export_total{result="failure"} または self_monitor_export_error_total が発生した場合。
セルフモニタリングが長時間成功していない P0 現在時刻から self_monitor_export_last_success_timestamp_seconds を引いた値が、Datakit のプル周期の 2 ～ 3 倍を超えた場合。
Celery キュー滞留 P0 worker_queue_count がしきい値を継続的に超えている、または celery_queue_oldest_wait_seconds が業務上許容される待機時間を継続的に超えている場合。
worker が消費していない疑い P0 celery_task_published_total に増加があるが、celery_task_started_total が長時間増加せず、同時にキュー長または最長待機時間が上昇している場合。
worker がハングアップした疑い P0 celery_task_active が長時間 0 より大きく低下せず、celery_task_finished_total が増加せず、タスクレイテンシ P99 が継続的に上昇している場合。
beat スケジュール漏れ P0 celery_beat_missed=1、または celery_beat_lag_seconds がタスクの許容しきい値を超えた場合。
Celery タスク失敗率上昇 P1 celery_task_finished_total{status!="success"} の割合が複数周期連続してしきい値を超えた場合。
Celery リトライストーム P1 celery_task_retry_total が連続して上昇し、同じ task または exception_type に集中している場合。
ビジネスタスクが長時間成功していない P0/P1 重要なタスクで business_task_last_success_timestamp_seconds が長時間更新されていない場合。
DB pool が枯渇しそう P1 dependency_db_pool_connections{state="checked_out"} が state="size" に近づいている、または state="overflow" > 0 が継続的に発生している場合。

よく使う DQL サンプル

各キューの現在の滞留を確認する。

M::`df_studio`:(max(`worker_queue_count`)) BY `queue`

各キューの最古タスク待機時間を確認する。

M::`df_studio`:(max(`celery_queue_oldest_wait_seconds`)) BY `queue`

タスクの公開と実行開始の差異を確認する。

M::`df_studio`:(sum(`celery_task_published_total`), sum(`celery_task_started_total`)) BY `queue`,`task`

タスク失敗の例外 TopN を確認する。

M::`df_studio`:(sum(`celery_task_failure_exception_total`)) BY `task`,`exception_type`

beat のスケジュール漏れを確認する。

M::`df_studio`:(max(`celery_beat_missed`), max(`celery_beat_lag_seconds`)) BY `beat_name`,`task`

セルフモニタリングのエクスポートステータスを確認する。

M::`df_studio`:(max(`self_monitor_export_total`), max(`self_monitor_export_points_total`), max(`self_monitor_export_duration_seconds`)) BY `exporter`,`result`

ビジネスタスクの最終成功時刻を確認する。

M::`df_studio`:(max(`business_task_last_success_timestamp_seconds`)) BY `domain`,`task`

既存のセルフモニタリングドキュメントとの関係

デプロイメントプランにおける完全なセルフモニタリングの導入手順については、同じディレクトリ内の「デプロイメントプラン自身の可観測性を有効にする」を参照してください。このドキュメントでは、DataKit のデプロイ、Prometheus プル設定、APM、RUM、Synthetic テスト、モニター、テンプレートインポートなどの一般的な手順をカバーしています。本ドキュメントでは、Studio バックエンド自体が出力する df_studio メトリクス、設定スイッチ、タグ単位、および非同期タスク/Redis/Broker モニタリングの基準についてのみ補足します。

フィードバック

このページは役に立ちましたか？