huawei-cloud-agentarts-obs-diagnosis

Huawei Cloud AgentArts のオブザーバビリティにおけるデータ欠落の診断

概要

このスキルでは、Huawei Cloud AgentArts のエージェント運用プラットフォームでメトリクス、ログ、トレース／セッションが欠落する問題を体系的に診断します。サブスクリプションのメタデータ確認 → データパイプラインのトラブルシューティング → クエリパラメーターの検証という3段階の診断フローに沿って、APM（トレース／メトリクス）、AOM（メトリクス）、LTS（ログ）の3つのデータソースを対象にします。

アーキテクチャ

Application (OTel SDK/Collector)
  │
  ├── Traces:  OTEL SDK → APM (OTLP) → deliverConfig → Kafka → agent-ops
  ├── Metrics: Application → AOM (Prometheus) → agent-ops
  └── Logs:    Application → LTS → agent-ops (requires logGroup/logStream metadata)

データソースとメタデータ

データ型	ソース	必要なメタデータ
トレース／セッション	APM	apmBusiness、apmToken
メトリクス	AOM	promInstance、aomAccessCode
ログ	LTS	logGroup、logStream

前提条件

1. Huawei Cloud の認証情報

export HUAWEI_ACCESS_KEY="<your-access-key-id>"
read -rs HUAWEI_SECRET_KEY; export HUAWEI_SECRET_KEY
export HUAWEI_REGION="cn-north-4"

2. hcloud CLI（KooCLI）

インストール：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html

3. IAM 権限

最小権限のポリシーについては、references/iam-policies.md を参照してください。

ワークフロー

ステップ 1：欠落しているデータ型を特定する

AskUserQuestion を使用して、欠落しているデータ型を確認します。

選択肢	データ型	データソース
A	メトリクス（metrics）	AOM / APM
B	ログ（logs）	LTS
C	トレース／セッション（traces/session）	APM
D	すべて欠落	すべてのソース

症状を記録します。完全に欠落しているか一部が欠落しているか、エラーコード、発生時刻を記録してください。

ステップ 2：環境のコンテキストを確認する

パラメーター	デフォルト	説明
region	cn-north-4	クエリのリージョン（データ取り込みのリージョンと一致する必要があります）
domain_id	—	IAM ドメイン ID
project_id	—	LTS クエリ用のプロジェクト ID
start_time / end_time	—	ミリ秒単位のタイムスタンプ（13桁。10桁の秒単位ではありません）

ステップ 3：サブスクリプションのメタデータを確認する（フェーズ 1 — 必ず最初に実施）

サブスクリプションのメタデータ欠落は、データが取得できない問題で最も一般的な根本原因です。

APM のビジネスとトークンを確認する：

hcloud APM ListBusiness --cli-region=cn-north-4

ビジネスが存在しない場合 → APM がサブスクライブされていません。ビジネスを作成します：

hcloud APM CreateBusiness --cli-region=cn-north-4 \
  --name="obs-diagnosis-check" \
  --display_name="obs-diagnosis-check" \
  --descp="diagnosis" \
  --cmdb_datasource_type=OTEL

ビジネストークンを確認します：

hcloud APM ShowToken --cli-region=cn-north-4 \
  --x-business-id={business_id}

AOM の Prometheus インスタンスとアクセスコードを確認する：

hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0
hcloud AOM ListAccessCode --cli-region=cn-north-4

PromInstance が存在しない場合 → AOM が設定されていません。Prometheus インスタンスを作成します （--prom_type は ECS／CCE／REMOTE_WRITE／CLOUD_SERVICE／ACROSS_ACCOUNT のいずれかである必要があります。 --region ヘッダーは必須で、--cli-region と一致する必要があります）：

hcloud AOM CreatePromInstance --cli-region=cn-north-4 \
  --prom_name="obs-diagnosis" \
  --prom_type=REMOTE_WRITE \
  --region=cn-north-4

LTS のロググループとストリームを確認する：

hcloud LTS ListLogGroups --cli-region=cn-north-4
hcloud LTS ListLogStreams --cli-region=cn-north-4 --log_group_id={group_id}

logGroup／logStream が存在しない場合 → エージェント運用向けに LTS がサブスクライブされていません。

ステップ 4：データ型ごとに診断する（フェーズ 2 — パイプラインの確認）

4A. メトリクスのデータ欠落診断

パイプラインを下から上へ確認します。

1. アプリケーション側：OTEL メトリクス SDK／Prometheus エクスポーターが設定されていますか？
2. AOM 側：

   hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0
   hcloud AOM ListAccessCode --cli-region=cn-north-4
   hcloud AOM ListMetadataAomPromGet --cli-region=cn-north-4
   

   • Prometheus インスタンスは有効ですか？
   • アクセスコードは有効ですか？
   • エンドポイントに到達できますか？
3. クエリ側：Prometheus クエリを使用して、データが存在することを確認します：

   hcloud AOM ListInstantQueryAomPromGet --cli-region=cn-north-4 \
     --query="up" \
     --prom_instance_id={prom_id}
   

4. agent-ops のフィルター：metric_name が一致しているか（resource_tokens、model_tokens、 session_tokens、trace_tokens）、フィルターラベルが一致しているか（gen_ai_resource_type、 resource_id、model_id）を確認します。

4B. ログのデータ欠落診断

1. アプリケーション側：ICAgent／OTEL ログエクスポーターが設定されていますか？
2. LTS 側：

   hcloud LTS ListLogGroups --cli-region=cn-north-4
   hcloud LTS ListLogStreams --cli-region=cn-north-4 --log_group_id={group_id}
   hcloud LTS ListLogs --cli-region=cn-north-4 \
     --log_group_id={group_id} \
     --log_stream_id={stream_id} \
     --start_time=1720000000000 \
     --end_time=1720600000000
   

3. クエリパラメーター：agentRunId、agentId、traceId、logType、 キーワード構文（LTS クエリ言語）を確認します。
4. エラーコード：
   • LTS.2446 → サポートされていないクエリ構文 — キーワード構文を修正します
   • 403 → 権限がありません — エージェンシートークン（ops_admin_trust）を確認します

4C. トレース／セッションのデータ欠落診断

1. アプリケーション側：

   hcloud APM SearchAgent --cli-region=cn-north-4 --x-business-id={business_id}
   

   OTEL SDK に正しいエンドポイントとトークンが設定されていますか？
2. APM deliverConfig：
   • deliverConfig で deliver_otel_trace=true になっていますか？
   • Kafka に到達できますか（bootstrap-servers、SASL_SSL、トピックの存在）？
3. APM データの検証：

   hcloud APM SearchTransaction --cli-region=cn-north-4 \
     --x-business-id={business_id} \
     --start_time=1720000000000 \
     --end_time=1720600000000
   

4. agent-ops のクエリ側（API のみ — KooCLI では利用できません）：

   curl -X POST ${AGENT_OPS_ENDPOINT}/v1/ops/observation/traces \
     -H "Authorization: Bearer ${IAM_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"start_time": 1720000000000, "end_time": 1720600000000}'
   

ステップ 5：共通チェック（すべてのデータ型）

1. タイムスタンプ形式：13 桁のミリ秒である必要があります（10 桁の秒の場合はデータがありません）
2. リージョンの整合性：取り込みリージョンとクエリリージョンが一致している必要があります
3. 認証：IAM トークン／AppCode は有効ですか？401 → 期限切れ、403 → 権限不足。${IAM_TOKEN} は実行時に IAM トークン／AppCode を取得して置き換える必要があります（上記のステップ 4「agent-ops クエリコマンド」を参照）。置き換えない場合はプレースホルダーのままとなり、リクエストをそのままコピーして実行すると必ず 401 が返されます。
4. 権限チェック：

   hcloud IAM ListPoliciesV5 --cli-region=cn-north-4
   

ステップ 6：診断レポートの生成

レポートの形式については、references/diagnostic-report-template.md を参照してください。

主なコマンド

コマンド	目的	モード
hcloud APM ListBusiness --cli-region=cn-north-4	APM ビジネスの一覧表示	CLI
hcloud APM ShowBusinessDetail --cli-region=cn-north-4	ビジネスの詳細を表示	CLI
hcloud APM ShowToken --cli-region=cn-north-4	ビジネストークンを取得	CLI
hcloud APM ShowAccessPoint --cli-region=cn-north-4	アクセスポイントを取得	CLI
hcloud APM SearchAgent --cli-region=cn-north-4	エージェントを検索	CLI
hcloud APM SearchTransaction --cli-region=cn-north-4	トランザクション（トレース）を検索	CLI
hcloud APM ShowSpanSearch --cli-region=cn-north-4	スパンを検索	CLI
hcloud APM ListOpenRegion --cli-region=cn-north-4	オープンリージョンを一覧表示	CLI
hcloud AOM ListPromInstance --cli-region=cn-north-4 --Enterprise-Project-Id=0	Prometheus インスタンスを一覧表示	CLI
hcloud AOM ListAccessCode --cli-region=cn-north-4	アクセスコードを一覧表示	CLI
hcloud AOM ListInstantQueryAomPromGet --cli-region=cn-north-4	Prometheus の瞬時クエリ	CLI
hcloud AOM ListRangeQueryAomPromGet --cli-region=cn-north-4	Prometheus の範囲クエリ	CLI
hcloud AOM ListMetadataAomPromGet --cli-region=cn-north-4	Prometheus メタデータを一覧表示	CLI
hcloud LTS ListLogGroups --cli-region=cn-north-4	ロググループを一覧表示	CLI
hcloud LTS ListLogStreams --cli-region=cn-north-4	ログストリームを一覧表示	CLI
hcloud LTS ListLogs --cli-region=cn-north-4	ログを一覧表示	CLI
hcloud IAM ListPoliciesV5 --cli-region=cn-north-4	IAM ポリシーを一覧表示	CLI
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/traces	agent-ops でトレースをクエリ	API
POST {AGENT_OPS_ENDPOINT}/v1/ops/observation/metrics/trend	メトリクスの傾向をクエリ	API

パラメーターの確認

パラメーター	必須	説明	例
region	はい	クエリリージョン	cn-north-4
business_id	はい（トレース）	APM ビジネス ID	ListBusiness から取得
prom_instance_id	はい（メトリクス）	AOM Prometheus インスタンス ID	ListPromInstance から取得
log_group_id	はい（ログ）	LTS ロググループ ID	ListLogGroups から取得
log_stream_id	はい（ログ）	LTS ログストリーム ID	ListLogStreams から取得
start_time	はい	開始時刻（ミリ秒タイムスタンプ）	1720000000000
end_time	はい	終了時刻（ミリ秒タイムスタンプ）	1720600000000
metric_name	いいえ（メトリクス）	クエリ対象のメトリクス名	resource_tokens
keywords	いいえ（ログ）	LTS キーワード検索	error AND timeout
trace_id	いいえ（トレース）	トレース ID フィルター	—

KooCLI コマンド形式の標準

hcloud <Service> <Operation> --cli-region=<region> [--key=value ...]

機能	説明	例
サービス名	KooCLI サービス名（大文字）	APM、AOM、LTS、IAM
オペレーション名	パスカルケース	ListBusiness、ShowToken
リージョンパラメーター	--cli-region=<value>	--cli-region=cn-north-4
単純なパラメーター	--key=value	--business_id=xxx

参考資料

• references/iam-policies.md — 最小権限の IAM ポリシー
• references/cli-installation-guide.md — hcloud CLI のインストールガイド
• references/verification-method.md — 検証方法と API のステータス
• references/dataflow-diagram.md — Mermaid データフローと診断フロー
• references/acceptance-criteria.md — 診断の受け入れ基準
• references/diagnostic-report-template.md — 診断レポートのテンプレート

エッジケース

シナリオ	対処方法
すべてのデータ型が欠落している	まずサブスクリプションのステータスを確認し、その後ネットワーク接続を確認します
一部のデータが欠落している（一部のアプリ）	エージェントのデプロイと service.name のマッピングを確認します
LTS.2446 エラー	キーワードの構文（エスケープ、引用符、演算子）を修正します
403 エラー（claw 以外）	IAM テナントの権限とサブスクリプションのステータスを確認します
403 エラー（claw）	agency（ops_admin_trust）と STS の設定を確認します
RESOURCE_NOT_EXIST	リソースレコードがありません — CreateClawTenantRelation を確認します
メタデータがない	先にサブスクライブします（SubscribeOpsObservation）
タイムスタンプが10桁	13桁のミリ秒に変換します
リージョンが一致しない	データの取り込みとクエリで同じリージョンを使用します

注意事項

• 優先順位：サブスクリプションのメタデータ → データパイプライン → クエリパラメーター → 権限
• 最も一般的な根本原因：サブスクリプションのメタデータ（apmBusiness、promInstance、logGroup）の欠落
• タイムスタンプの落とし穴：13桁のミリ秒ではなく、10桁の秒を使用している
• 認証情報のセキュリティ：AK/SK をハードコードしないでください。環境変数または CLI プロファイルから読み込んでください。
• 最小権限：必要な権限については、references/iam-policies.md を参照してください。