> ## 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`를 실행할 때마다 최대 하나의 이벤트 `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, 액세스 토큰, 파일 경로,
구성된 비밀, 오류 메시지 또는 컴퓨터 이름을 수집하지 않습니다.

## 이벤트가 전송되는 시기

명령이 성공하면 CLI는 이벤트를 디스크에 저장하고 이후 실행에서 전송하므로,
명령이 네트워크를 기다리지 않습니다. 명령이 실패하면 CLI는 해당 이벤트와 저장된 이벤트를 보내기 위해 최대 300밀리초
동안 기다립니다. CLI가 다시 실행되지 않을 수 있는 CI에서는 이벤트를 저장하는 대신
종료하기 전에 전송합니다. 엔드포인트가 느린 경우 최대 약 5초가 추가될 수 있으며, 이 시간 내에
전송되지 않으면 이벤트가 삭제됩니다.

## 버전 헤더

원격 분석과 별도로, CLI가 액세스 토큰과 함께 보내는 모든 요청에는
`XboxDevCLI/0.1.0.9`와 같은 `User-Agent: XboxDevCLI/<version>` 헤더가 포함되어 해당 서비스가
어떤 CLI 버전이 호출하는지 알 수 있습니다. 이 헤더에는 다른 정보가 포함되지 않으며, 원격 분석을 옵트아웃해도
제거되지 않습니다.

## 첫 실행 시 공개

CLI가 컴퓨터에서 처음으로 원격 분석을 수집할 때 다음 알림을 stderr에 한 번 작성합니다.

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

## 옵트아웃

### 명령 하나에 대해

`--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/ko/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/ko/services/playfab/data-analytics/ingest-data/playstream-custom-tags.md)
- [원격 분석 키 삭제](https://docs.xbox.com/ko/services/playfab/api-references/rest/events/play-stream-events/delete-telemetry-key.md)
- [원격 분석 키 나열](https://docs.xbox.com/ko/services/playfab/api-references/rest/events/play-stream-events/list-telemetry-keys.md)
- [원격 분석 키 활성 설정](https://docs.xbox.com/ko/services/playfab/api-references/rest/events/play-stream-events/set-telemetry-key-active.md)
- [원격 분석 키 만들기](https://docs.xbox.com/ko/services/playfab/api-references/rest/events/play-stream-events/create-telemetry-key.md)
