Qwen Code 可観測性ガイド
テレメトリは、Qwen Code のパフォーマンス、健全性、使用状況に関するデータを提供します。これを有効にすることで、トレース、メトリクス、構造化ログを通じて、操作の監視、問題のデバッグ、ツール使用の最適化が可能になります。
Qwen Code のテレメトリシステムは OpenTelemetry (OTEL) 標準に基づいて構築されており、任意の互換性のあるバックエンドにデータを送信できます。
テレメトリの有効化
テレメトリは複数の方法で有効化できます。設定は主に .qwen/settings.json
ファイル と環境変数で管理されますが、CLI フラグで特定のセッションに対してこれらの設定を上書きできます。
優先順位
テレメトリ設定の適用順序は以下の通りで、上位に記載された項目ほど優先度が高いです:
-
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 を参照してください。
-
環境変数:
OTEL_EXPORTER_OTLP_ENDPOINT
:telemetry.otlpEndpoint
を上書きします。
-
ワークスペース設定ファイル (
.qwen/settings.json
): このプロジェクト固有のファイル内のtelemetry
オブジェクトの値が使用されます。 -
ユーザー設定ファイル (
~/.qwen/settings.json
): このグローバルなユーザー設定ファイル内のtelemetry
オブジェクトの値が使用されます。 -
デフォルト値: 上記いずれの方法でも設定されていない場合に適用されます。
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)をインストールします。使用方法は以下の通りです:
-
コマンドを実行: リポジトリのルートから以下のコマンドを実行してください:
npm run telemetry -- --target=local
スクリプトは以下の処理を行います:
- 必要に応じて Jaeger と OTEL をダウンロードします。
- ローカルに Jaeger インスタンスを起動します。
- Qwen Code からのデータを受信するように設定された OTEL コレクターを起動します。
- ワークスペースの設定で自動的にテレメトリーを有効にします。
- 終了時にはテレメトリーを無効にします。
-
トレースの確認: Webブラウザを開き、http://localhost:16686 にアクセスして Jaeger UI を表示します。ここでは Qwen Code の操作に関する詳細なトレースを確認できます。
-
ログとメトリクスの確認: スクリプトは OTEL コレクターの出力(ログとメトリクスを含む)を
~/.qwen/tmp/<projectHash>/otel/collector.log
にリダイレクトします。スクリプトは、テレメトリーデータ(トレース、メトリクス、ログ)をローカルで表示するためのリンクとコマンドを提供します。 -
サービスの停止: スクリプトを実行しているターミナルで
Ctrl+C
を押すと、OTEL Collector と Jaeger サービスを停止できます。
Google Cloud
npm run telemetry -- --target=gcp
コマンドを使用して、ローカルの OpenTelemetry コレクターを自動でセットアップし、データをあなたの Google Cloud プロジェクトに転送する設定を行います。これには .qwen/settings.json
ファイルへの必要な設定の追加も含まれます。内部スクリプトは otelcol-contrib
をインストールします。使用方法は以下の通りです:
-
前提条件:
- 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”。
-
コマンドの実行: リポジトリのルートディレクトリから以下のコマンドを実行してください:
npm run telemetry -- --target=gcp
スクリプトは以下の処理を行います:
- 必要に応じて
otelcol-contrib
バイナリをダウンロードします。 - Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするように設定された OTEL コレクターを起動します。
- ワークスペース設定(
.qwen/settings.json
)で自動的にテレメトリを有効にし、サンドボックスモードを無効にします。 - Google Cloud Console でトレース、メトリクス、ログを表示するための直接リンクを提供します。
- 終了時(Ctrl+C)には、元のテレメトリおよびサンドボックス設定を復元しようとします。
- 必要に応じて
-
Qwen Code の実行: 別のターミナルで Qwen Code コマンドを実行してください。これにより、コレクターがキャプチャするテレメトリデータが生成されます。
-
Google Cloud でのテレメトリの確認: スクリプトによって提供されたリンクを使用して Google Cloud Console に移動し、トレース、メトリクス、ログを確認してください。
-
ローカルのコレクターログの確認: スクリプトはローカルの OTEL コレクターの出力を
~/.qwen/tmp/<projectHash>/otel/collector-gcp.log
にリダイレクトします。スクリプトは、ローカルでコレクターログを表示したり、tail コマンドを実行するためのリンクとコマンドも提供します。 -
サービスの停止: スクリプトを実行しているターミナルで
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)
- Attributes:
-
qwen-code.user_prompt
: このイベントはユーザーが prompt を送信したときに発生します。- Attributes:
prompt_length
prompt
(この attribute はlog_prompts_enabled
がfalse
の場合、除外されます)auth_type
- Attributes:
-
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)
- Attributes:
-
qwen-code.api_request
: このイベントは Qwen API へのリクエスト時に発生します。- Attributes:
model
request_text
(適用される場合)
- Attributes:
-
qwen-code.api_error
: このイベントは API リクエストが失敗した場合に発生します。- Attributes:
model
error
error_type
status_code
duration_ms
auth_type
- Attributes:
-
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
- Attributes:
-
qwen-code.flash_fallback
: このイベントは Qwen Code が fallback として flash に切り替えたときに発生します。- Attributes:
auth_type
- Attributes:
-
qwen-code.slash_command
: このイベントはユーザーが slash command を実行したときに発生します。- Attributes:
command
(string)subcommand
(string, 適用される場合)
- Attributes:
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”。該当する場合)
- Attributes:
-
qwen-code.tool.call.latency
(Histogram, ms): ツール呼び出しのレイテンシを測定します。- Attributes:
function_name
decision
(string: “accept”, “reject”, または “modify”。該当する場合)
- Attributes:
-
qwen-code.api.request.count
(Counter, Int): すべての API リクエストの回数をカウントします。- Attributes:
model
status_code
error_type
(該当する場合)
- Attributes:
-
qwen-code.api.request.latency
(Histogram, ms): API リクエストのレイテンシを測定します。- Attributes:
model
- Attributes:
-
qwen-code.token.usage
(Counter, Int): 使用されたトークン数をカウントします。- Attributes:
model
type
(string: “input”, “output”, “thought”, “cache”, または “tool”)
- Attributes:
-
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 の提案変更で削除・変更した行数。
- Attributes:
-
qwen-code.chat_compression
(Counter, Int): チャット圧縮操作の回数をカウントします。- Attributes:
tokens_before
: (Int): 圧縮前のコンテキスト内のトークン数。tokens_after
: (Int): 圧縮後のコンテキスト内のトークン数。
- Attributes: