> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# テレメトリ

> CLI が収集する匿名の製品使用状況テレメトリの内容と、収集を無効にする方法について説明します。

XBOX CLI は、どのコマンドが使用されているか、それらの信頼性、所要時間を Microsoft が把握できるように、
限られた匿名の使用状況テレメトリを収集します。テレメトリは[無効にする](#opt-out)ことができます。テレメトリによって
コマンドの出力や終了コードが変わることはありません。

Microsoft は、[Microsoft のプライバシーに関する声明](https://go.microsoft.com/fwlink/?LinkID=824704)に記載されているとおりに
このデータを取り扱います。ソフトウェアによるデータ収集については、リポジトリの
[プライバシーに関する通知](https://github.com/xbox/cli/blob/v0.4.2/PRIVACY.md)で説明しています。

## 収集される内容

`xbox` を実行するたびに、最大 1 つのイベント `xbox.cli.command_invocation` が作成されます。このイベントには次のフィールドのみが
含まれ、それ以外は含まれません。

| フィールド | 内容 |
| - | - |
| `xbox.cli.schema_version` | イベントのスキーマ バージョン (`3`) |
| 時刻 | コマンドが実行された時刻 (時間単位で切り捨て) |
| `service.version` | CLI のバージョン |
| `os.type`, `os.version` | `windows` などのオペレーティング システムのファミリーと、そのメジャー バージョンのみ |
| `host.arch` | プロセッサ アーキテクチャ: `amd64`、`arm64`、または `unknown` |
| `process.runtime.name`, `process.runtime.version` | .NET ランタイムとそのバージョン |
| `xbox.cli.command` | コマンド ツリー内でのコマンドのパスをハイフンでつないだもの (`playfab-economy-inventory-transaction-list` など)。`xbox` のみの場合は `root`、コマンドが認識されなかった場合は `unknown` |
| `xbox.cli.auth_mode` | CLI のサインイン方法: `user`、`githuboidc` などのサービス プリンシパル モード、または `invalid`。テナント、アプリケーション、ID は含まれません |
| `xbox.cli.outcome` | `success`、`failure`、または `cancelled` |
| `process.exit.code` | 終了コード |
| `error.type` | コマンドが失敗した理由 (固定のリストから選択): `usage`、`context`、`auth`、`not_confirmed`、`transport`、`service_rejected`、`service_error`、`local_tool`、`io`、`cancelled`、または `_OTHER`。成功時には送信されません。 |
| `http.response.status_code` | 最後のサービス レスポンスがあった場合は、その状態 |
| `xbox.cli.duration_ms` | コマンドの所要時間 (ミリ秒) |
| `xbox.cli.options` | 指定されたオプションの名前をダッシュなしで並べ替えたもの (`output,verbose` など)。値は含まれません |
| `xbox.cli.context_keys` | オプション、環境変数、保存されたコンテキストのいずれから取得したかにかかわらず、コマンドが持っていたコンテキストの値の種類: `playfab-title-id`、`sandbox-id`、`seller-id`、または `title-id`。値は含まれません |
| `xbox.cli.ci` | `CI` や `TF_BUILD` などのよく知られた CI 変数が設定されている場合は `true`。読み取られるのは設定されているかどうかのみです |

CLI で定義されていないコマンド名やオプション名は、`unknown` として送信されるか除外されるため、誤った場所に
入力された値が送信されることはありません。

### おおよその位置情報

CLI が位置情報を送信することはありません。ただし、Application Insights は、イベントを送信する IP アドレスから
おおよその位置情報 (国、地域または州、都市) を推定し、すべてのイベントに保存します。IP アドレス自体は
保持されず、`0.0.0.0` として保存されます。この位置情報は、各市場での普及状況を把握するためにのみ使用されます。
[オプトアウト](#opt-out)すると、この位置情報を含むすべてのテレメトリが停止します。

## 収集されない内容

CLI は、引数やオプションの値、リクエストやレスポンスの本文、PlayFab タイトル
ID、販売者 ID、サンドボックス ID、ユーザー名、テナント ID やアカウント ID、アクセス トークン、ファイル パス、
構成されたシークレット、エラー メッセージ、マシン名を収集しません。

## イベントが送信されるタイミング

コマンドが成功すると、CLI はイベントをディスクに保存し、後の実行でそのイベントを送信します。そのため、
コマンドがネットワークを待つことはありません。コマンドが失敗すると、CLI はそのイベントと保存済みのイベントの送信を最大 300
ミリ秒待機します。CLI が再度実行されない可能性がある CI では、イベントを保存する代わりに、
終了前にイベントを送信します。エンドポイントが遅い場合は最大で約 5 秒かかることがあり、その時間内に送信されなかった
イベントは破棄されます。

## バージョン ヘッダー

テレメトリとは別に、CLI がアクセス トークンと共に送信するすべてのリクエストには、`XboxDevCLI/0.1.0.9` のような
`User-Agent: XboxDevCLI/<version>` ヘッダーが含まれます。これにより、各サービスはどの CLI バージョンから呼び出されているかを
判別できます。このヘッダーにはそれ以外の情報は含まれず、テレメトリをオプトアウトしても
削除されません。

## 初回実行時の通知

CLI がマシンで初めてテレメトリを収集するときに、次の通知を stderr に 1 回だけ書き込みます。

```text theme={null}
TELEMETRY
  XBOX CLI collects anonymous usage telemetry.
  Learn more or opt out: https://go.xbox/cli/telemetry
```

## オプトアウト

### 1 つのコマンドの場合

`--disable-telemetry` を渡します。

```powershell theme={null}
xbox --disable-telemetry auth status
```

### 現在のシェル セッションの場合

PowerShell で `XBOX_TELEMETRY_OPTOUT` を設定します。

```powershell theme={null}
$env:XBOX_TELEMETRY_OPTOUT = "1"
```

bash または zsh の場合:

```bash theme={null}
export XBOX_TELEMETRY_OPTOUT=1
```

値 `1`、`true`、`yes` は、他の構成にかかわらずテレメトリを無効にします。
`XBOX_TELEMETRY__ENABLED` を `false` に設定しても無効になります。

### すべての新しいターミナルの場合

アカウントに変数を設定します。Windows では次のコマンドを実行してから、ターミナルを開き直します。IDE の統合ターミナルを
使用している場合は IDE も開き直します。

```powershell theme={null}
[Environment]::SetEnvironmentVariable("XBOX_TELEMETRY_OPTOUT", "1", "User")
```

Linux と macOS では、[インストール](https://docs.xbox.com/ja-jp/tools/xbox-cli/installation.md)で CLI を `PATH` に追加したときと同じ方法で、
`~/.zshrc` や `~/.bashrc` などのシェルのスタートアップ ファイルに `export` 行を追加します。

## テレメトリの送信先

リリース ビルドは、Microsoft が所有する Azure Monitor Application Insights リソースにテレメトリを送信します。
この送信先は変更できません。CLI は `APPLICATIONINSIGHTS_CONNECTION_STRING` を無視するため、ホストが
独自のアプリケーション用にこの変数を設定しても、CLI のテレメトリがリダイレクトされることはありません。


## Related topics

- [テレメトリ](https://docs.xbox.com/ja-jp/services/playfab/data-analytics/ingest-data/telemetry-overview.md)
- [Custom Tag を使用してイベントをカスタマイズする](https://docs.xbox.com/ja-jp/services/playfab/data-analytics/ingest-data/playstream-custom-tags.md)
- [テレメトリ キーの削除](https://docs.xbox.com/ja-jp/services/playfab/api-references/rest/events/play-stream-events/delete-telemetry-key.md)
- [テレメトリ キーの取得](https://docs.xbox.com/ja-jp/services/playfab/api-references/rest/events/play-stream-events/get-telemetry-key.md)
- [テレメトリ キーの作成](https://docs.xbox.com/ja-jp/services/playfab/api-references/rest/events/play-stream-events/create-telemetry-key.md)
