zenlm/zen-code-docs
1
0
Fork 0
mirror of https://github.com/zenlm/zen-code-docs.git synced 2026-10-30 14:58:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
zen-code-docs/website/content/ja/telemetry.md
T
pomelo-nwu ccdd00f0d9 feat: update docs
2025-09-12 17:56:29 +08:00

15 KiB
Raw Permalink Blame History

Qwen Code 可観測性ガイド

テレメトリは、Qwen Code のパフォーマンス、健全性、使用状況に関するデータを提供します。これを有効にすることで、トレース、メトリクス、構造化ログを通じて、操作の監視、問題のデバッグ、ツール使用の最適化が可能になります。

Qwen Code のテレメトリシステムは OpenTelemetry (OTEL) 標準に基づいて構築されており、任意の互換性のあるバックエンドにデータを送信できます。

テレメトリの有効化

テレメトリは複数の方法で有効化できます。設定は主に .qwen/settings.json ファイル と環境変数で管理されますが、CLI フラグで特定のセッションに対してこれらの設定を上書きできます。

優先順位

テレメトリ設定の適用順序は以下の通りで、上位に記載された項目ほど優先度が高いです：

  1. CLI フラグ (qwen コマンド用):

    • --telemetry / --no-telemetry: telemetry.enabled を上書きします。
    • --telemetry-target <local|gcp>: telemetry.target を上書きします。
    • --telemetry-otlp-endpoint <URL>: telemetry.otlpEndpoint を上書きします。
    • --telemetry-log-prompts / --no-telemetry-log-prompts: telemetry.logPrompts を上書きします。
    • --telemetry-outfile <path>: テレメトリ出力をファイルにリダイレクトします。詳しくは Exporting to a file を参照してください。

  2. 環境変数:

    • OTEL_EXPORTER_OTLP_ENDPOINT: telemetry.otlpEndpoint を上書きします。

  3. ワークスペース設定ファイル (.qwen/settings.json): このプロジェクト固有のファイル内の telemetry オブジェクトの値が使用されます。

  4. ユーザー設定ファイル (~/.qwen/settings.json): このグローバルなユーザー設定ファイル内の telemetry オブジェクトの値が使用されます。

  5. デフォルト値: 上記いずれの方法でも設定されていない場合に適用されます。

    • telemetry.enabled: false
    • telemetry.target: local
    • telemetry.otlpEndpoint: http://localhost:4317
    • telemetry.logPrompts: true

npm run telemetry -- --target=<gcp|local> スクリプトについて: このスクリプトに渡す --target 引数は、そのスクリプトの実行中および実行目的（つまり、起動する collector の選択）にのみ telemetry.target を上書きします。これは settings.json の設定を永続的に変更するものではありません。スクリプトはまず settings.json 内の telemetry.target を確認し、それをデフォルトとして使用します。

設定例

以下のコードをワークスペース (.qwen/settings.json) またはユーザー (~/.qwen/settings.json) の設定に追加することで、テレメトリを有効化し、出力を Google Cloud に送信できます。

{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  },
  "sandbox": false
}

ファイルへのエクスポート

すべてのテレメトリデータをファイルにエクスポートして、ローカルで確認できます。

ファイルエクスポートを有効にするには、--telemetry-outfile フラグに任意の出力ファイルパスを指定して実行します。このとき、--telemetry-target=local を指定する必要があります。


# 出力先ファイルパスを設定
TELEMETRY_FILE=".qwen/telemetry.log"

# ローカルテレメトリを有効にして Qwen Code を実行

# 注意: --telemetry-otlp-endpoint="" はデフォルトの OTLP エクスポーターを

# 上書きし、テレメトリがローカルファイルに確実に書き込まれるようにするために必要です。
qwen --telemetry \
  --telemetry-target=local \
  --telemetry-otlp-endpoint="" \
  --telemetry-outfile="$TELEMETRY_FILE" \
  --prompt "What is OpenTelemetry?"

OTEL Collector の実行

OTEL Collector は、テレメトリデータを受信、処理、エクスポートするサービスです。
CLI は OTLP/gRPC または OTLP/HTTP プロトコルのいずれかを使ってデータを送信できます。
使用するプロトコルは、--telemetry-otlp-protocol フラグまたは settings.json ファイル内の
telemetry.otlpProtocol 設定で指定できます。詳細については
configuration docs を参照してください。

OTEL exporter の標準設定について詳しくは documentation をご覧ください。

Local

npm run telemetry -- --target=local コマンドを使用して、ローカルのテレメトリーパイプラインをセットアップするプロセスを自動化できます。このコマンドは、.qwen/settings.json ファイルに必要な設定を行うことも含まれています。内部のスクリプトは otelcol-contrib（OpenTelemetry Collector）と jaeger（トレースを表示するためのJaeger UI）をインストールします。使用方法は以下の通りです：

  1. コマンドを実行： リポジトリのルートから以下のコマンドを実行してください：

    npm run telemetry -- --target=local

    スクリプトは以下の処理を行います：

    • 必要に応じて Jaeger と OTEL をダウンロードします。
    • ローカルに Jaeger インスタンスを起動します。
    • Qwen Code からのデータを受信するように設定された OTEL コレクターを起動します。
    • ワークスペースの設定で自動的にテレメトリーを有効にします。
    • 終了時にはテレメトリーを無効にします。

  2. トレースの確認： Webブラウザを開き、http://localhost:16686 にアクセスして Jaeger UI を表示します。ここでは Qwen Code の操作に関する詳細なトレースを確認できます。

  3. ログとメトリクスの確認： スクリプトは OTEL コレクターの出力（ログとメトリクスを含む）を ~/.qwen/tmp/<projectHash>/otel/collector.log にリダイレクトします。スクリプトは、テレメトリーデータ（トレース、メトリクス、ログ）をローカルで表示するためのリンクとコマンドを提供します。

  4. サービスの停止： スクリプトを実行しているターミナルで Ctrl+C を押すと、OTEL Collector と Jaeger サービスを停止できます。

Google Cloud

npm run telemetry -- --target=gcp コマンドを使用して、ローカルの OpenTelemetry コレクターを自動でセットアップし、データをあなたの Google Cloud プロジェクトに転送する設定を行います。これには .qwen/settings.json ファイルへの必要な設定の追加も含まれます。内部スクリプトは otelcol-contrib をインストールします。使用方法は以下の通りです：

  1. 前提条件:

    • Google Cloud プロジェクト ID を持っていること。
    • 環境変数 GOOGLE_CLOUD_PROJECT をエクスポートして、OTEL コレクターからアクセス可能にしてください。 
      export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"
    • Google Cloud への認証を行ってください（例：gcloud auth application-default login を実行するか、GOOGLE_APPLICATION_CREDENTIALS が設定されていることを確認してください）。
    • 使用する Google Cloud アカウントまたはサービスアカウントに、以下の IAM ロールが付与されていること："Cloud Trace Agent"、"Monitoring Metric Writer"、"Logs Writer"。

  2. コマンドの実行: リポジトリのルートディレクトリから以下のコマンドを実行してください：

    npm run telemetry -- --target=gcp

    スクリプトは以下の処理を行います：

    • 必要に応じて otelcol-contrib バイナリをダウンロードします。
    • Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするように設定された OTEL コレクターを起動します。
    • ワークスペース設定（.qwen/settings.json）で自動的にテレメトリを有効にし、サンドボックスモードを無効にします。
    • Google Cloud Console でトレース、メトリクス、ログを表示するための直接リンクを提供します。
    • 終了時（Ctrl+C）には、元のテレメトリおよびサンドボックス設定を復元しようとします。

  3. Qwen Code の実行: 別のターミナルで Qwen Code コマンドを実行してください。これにより、コレクターがキャプチャするテレメトリデータが生成されます。

  4. Google Cloud でのテレメトリの確認: スクリプトによって提供されたリンクを使用して Google Cloud Console に移動し、トレース、メトリクス、ログを確認してください。

  5. ローカルのコレクターログの確認: スクリプトはローカルの OTEL コレクターの出力を ~/.qwen/tmp/<projectHash>/otel/collector-gcp.log にリダイレクトします。スクリプトは、ローカルでコレクターログを表示したり、tail コマンドを実行するためのリンクとコマンドも提供します。

  6. サービスの停止: スクリプトを実行しているターミナルで Ctrl+C を押すと、OTEL コレクターを停止します。

ログとメトリクスのリファレンス

このセクションでは、Qwen Code 用に生成されるログとメトリクスの構造について説明します。

  • すべてのログとメトリクスには、共通の属性として sessionId が含まれます。

Logs

Logs は特定のイベントのタイムスタンプ付き記録です。Qwen Code では以下のイベントがログに記録されます：

  • qwen-code.config: このイベントは CLI の起動時に一度だけ発生し、CLI の設定情報を含みます。

    • Attributes:
      • model (string)
      • embedding_model (string)
      • sandbox_enabled (boolean)
      • core_tools_enabled (string)
      • approval_mode (string)
      • api_key_enabled (boolean)
      • vertex_ai_enabled (boolean)
      • code_assist_enabled (boolean)
      • log_prompts_enabled (boolean)
      • file_filtering_respect_git_ignore (boolean)
      • debug_mode (boolean)
      • mcp_servers (string)

  • qwen-code.user_prompt: このイベントはユーザーが prompt を送信したときに発生します。

    • Attributes:
      • prompt_length
      • prompt (この attribute は log_prompts_enabled が false の場合、除外されます)
      • auth_type

  • qwen-code.tool_call: このイベントは各 function call に対して発生します。

    • Attributes:
      • function_name
      • function_args
      • duration_ms
      • success (boolean)
      • decision (string: "accept", "reject", "auto_accept", または "modify"。適用される場合)
      • error (適用される場合)
      • error_type (適用される場合)
      • metadata (適用される場合、string -> any の dictionary)

  • qwen-code.api_request: このイベントは Qwen API へのリクエスト時に発生します。

    • Attributes:
      • model
      • request_text (適用される場合)

  • qwen-code.api_error: このイベントは API リクエストが失敗した場合に発生します。

    • Attributes:
      • model
      • error
      • error_type
      • status_code
      • duration_ms
      • auth_type

  • qwen-code.api_response: このイベントは Qwen API からレスポンスを受信した際に発生します。

    • Attributes:
      • model
      • status_code
      • duration_ms
      • error (optional)
      • input_token_count
      • output_token_count
      • cached_content_token_count
      • thoughts_token_count
      • tool_token_count
      • response_text (適用される場合)
      • auth_type

  • qwen-code.flash_fallback: このイベントは Qwen Code が fallback として flash に切り替えたときに発生します。

    • Attributes:
      • auth_type

  • qwen-code.slash_command: このイベントはユーザーが slash command を実行したときに発生します。

    • Attributes:
      • command (string)
      • subcommand (string, 適用される場合)

Metrics

Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code では以下の Metrics が収集されます（互換性のため、metric 名は qwen-code.* のままです）：

  • qwen-code.session.count (Counter, Int): CLI 起動時に 1 インクリメントされます。

  • qwen-code.tool.call.count (Counter, Int): ツール呼び出しの回数をカウントします。

    • Attributes:
      • function_name
      • success (boolean)
      • decision (string: "accept", "reject", または "modify"。該当する場合)
      • tool_type (string: "mcp" または "native"。該当する場合)

  • qwen-code.tool.call.latency (Histogram, ms): ツール呼び出しのレイテンシを測定します。

    • Attributes:
      • function_name
      • decision (string: "accept", "reject", または "modify"。該当する場合)

  • qwen-code.api.request.count (Counter, Int): すべての API リクエストの回数をカウントします。

    • Attributes:
      • model
      • status_code
      • error_type (該当する場合)

  • qwen-code.api.request.latency (Histogram, ms): API リクエストのレイテンシを測定します。

    • Attributes:
      • model

  • qwen-code.token.usage (Counter, Int): 使用されたトークン数をカウントします。

    • Attributes:
      • model
      • type (string: "input", "output", "thought", "cache", または "tool")

  • qwen-code.file.operation.count (Counter, Int): ファイル操作の回数をカウントします。

    • Attributes:
      • operation (string: "create", "read", "update"): ファイル操作の種類。
      • lines (Int, 該当する場合): ファイルの行数。
      • mimetype (string, 該当する場合): ファイルの mimetype。
      • extension (string, 該当する場合): ファイルの拡張子。
      • ai_added_lines (Int, 該当する場合): AI によって追加・変更された行数。
      • ai_removed_lines (Int, 該当する場合): AI によって削除・変更された行数。
      • user_added_lines (Int, 該当する場合): ユーザーが AI の提案変更で追加・変更した行数。
      • user_removed_lines (Int, 該当する場合): ユーザーが AI の提案変更で削除・変更した行数。

  • qwen-code.chat_compression (Counter, Int): チャット圧縮操作の回数をカウントします。

    • Attributes:
      • tokens_before: (Int): 圧縮前のコンテキスト内のトークン数。
      • tokens_after: (Int): 圧縮後のコンテキスト内のトークン数。
Reference in New Issue View Git Blame Copy Permalink