기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# AWS X-Ray 데몬 구성
<a name="xray-daemon-configuration"></a>

**참고**  
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.

명령줄 옵션 또는 구성 파일을 사용하여 X-Ray 대몬(daemon)의 동작을 사용자 지정할 수 있습니다. 두 가지 방법 모두 대부분의 옵션을 사용할 수 있지만, 구성 파일에만 사용하는 옵션도 있고 명령줄에만 사용하는 옵션도 있습니다.

대몬(daemon)이 X-Ray에 트레이스 데이터를 전송할 때 사용할 리전을 설정하는 `-n` 또는 `--region` 옵션만 알면 시작할 수 있습니다.

```
~/xray-daemon$ ./xray -n us-east-2
```

대몬(daemon)을 Amazon EC2가 아니라 로컬로 실행 중인 경우, `-o` 옵션을 추가해 인스턴스 프로파일 자격 증명 확인을 건너뛰도록 하여 대몬(daemon)을 훨씬 빠르게 준비할 수 있습니다.

```
~/xray-daemon$ ./xray -o -n us-east-2
```

나머지 명령줄 옵션은 로깅을 구성하거나, 다른 포트에서 수신하거나, 데몬이 사용할 수 있는 메모리의 양을 제한하거나, 트레이스 데이터를 다른 계정으로 보내는 역할을 맡는 데 사용할 수 있습니다.

대몬(daemon)에 구성 파일을 전달해 고급 구성 옵션에 액세스하고, X-Ray에 대한 동시 호출 수 제한, 로그 순환 비활성화 및 프록시에 트래픽 전송 등의 작업을 수행할 수 있습니다.

**Topics**
+ [지원되는 환경 변수](#xray-daemon-configuration-variables)
+ [명령줄 옵션 사용](#xray-daemon-configuration-commandline)
+ [구성 파일 사용](#xray-daemon-configuration-configfile)

## 지원되는 환경 변수
<a name="xray-daemon-configuration-variables"></a>

X-Ray 대몬(daemon)은 다음과 같은 환경 변수를 지원합니다.
+ `AWS_REGION` – X-Ray 서비스 엔드포인트의 [AWS 리전](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration-region)을 지정합니다.
+ `HTTPS_PROXY` – 세그먼트 업로드에 이용할 대몬(daemon)의 프록시 주소를 지정합니다. 이것은 DNS 데몬 이름일 수도 있고, 프록시 서버에서 사용하는 IP 주소와 포트 번호일 수도 있습니다.

## 명령줄 옵션 사용
<a name="xray-daemon-configuration-commandline"></a>

로컬에서 또는 사용자 데이터 스크립트를 사용하여 데몬을 실행할 때 이러한 옵션을 데몬에 전달합니다.

**명령줄 옵션**
+ `-b`, `--bind` – 다른 UDP 포트에서 세그먼트 문서를 수신 대기합니다.

  ```
  --bind "127.0.0.1:{{3000}}"
  ```

  기본값 – `2000`.
+ `-t`, `--bind-tcp` – 다른 TCP 포트에서 X-Ray 서비스에 대한 호출을 수신 대기합니다.

  ```
  -bind-tcp "127.0.0.1:{{3000}}"
  ```

  기본값 – `2000`.
+ `-c`, `--config` – 지정된 경로에서 구성 파일을 로드합니다.

  ```
  --config "{{/home/ec2-user/xray-daemon.yaml}}"
  ```
+ `-f`, `--log-file` – 지정된 파일 경로로 로그를 출력합니다.

  ```
  --log-file "{{/var/log/xray-daemon.log}}"
  ```
+ `-l`, `--log-level` – 로그 레벨(최대 상세에서 최소 상세까지) dev, debug, info, warn, error, prod.

  ```
  --log-level {{warn}}
  ```

  기본값 - `prod`
+ `-m`, `--buffer-memory` – 버퍼가 사용할 수 있는 메모리 용량(단위: MB, 최소 3)을 변경합니다.

  ```
  --buffer-memory {{50}}
  ```

  기본값 – 가용 메모리의 1%.
+ `-o`, `--local-mode` – EC2 인스턴스 메타데이터는 선택하지 마십시오.
+ `-r`, `--role-arn` – 지정된 IAM 역할을 맡아 세그먼트를 다른 계정으로 업로드합니다.

  ```
  --role-arn "arn:aws:iam::{{123456789012}}:role/{{xray-cross-account}}"
  ```
+ `-a`, `--resource-arn`- 데몬을 실행하는 리소스의 Amazon AWS 리소스 이름(ARN)입니다.
+ `-p`, `--proxy-address`- 프록시를 AWS X-Ray 통해에 세그먼트를 업로드합니다. 프록시 서버의 프로토콜을 지정해야 합니다.

  ```
  --proxy-address "{{http://192.0.2.0:3000}}"
  ```
+ `-n`, `--region` – 세그먼트를 특정 리전의 X-Ray 서비스로 전송합니다.
+ `-v`, AWS X-Ray `--version`- 데몬 버전을 표시합니다.
+ `-h`, `--help` – 도움말 화면을 표시합니다.

## 구성 파일 사용
<a name="xray-daemon-configuration-configfile"></a>

YAML 형식 파일을 사용하여 데몬을 구성할 수도 있습니다. `-c` 옵션을 사용하여 구성 파일을 데몬으로 전달합니다.

```
~$ ./xray -c ~/xray-daemon.yaml
```

**구성 파일 옵션**
+ `TotalBufferSizeMB` – 최대 버퍼 크기(단위: MB, 최소 3). 호스트 메모리의 1%를 사용하려면 0을 선택합니다.
+ `Concurrency` - 세그먼트 문서를 업로드하기 AWS X-Ray 위한에 대한 최대 동시 호출 수입니다.
+ `Region` - 세그먼트를 특정 리전의 AWS X-Ray 서비스로 전송합니다.
+ `Socket` – 대몬(daemon)의 바인딩을 구성합니다.
  + `UDPAddress` – 대몬(daemon)이 수신 대기하는 포트를 변경합니다.
  + `TCPAddress` – 다른 TCP 포트에서 [X-Ray 서비스에 대한 호출](xray-api-sampling.md)을 수신 대기합니다.
+ `Logging` – 로깅 동작을 구성합니다.
  + `LogRotation` – 로그 순환을 비활성화하려면 `false`로 설정합니다.
  + `LogLevel` – 로그 수준을 가장 자세한 수준부터 가장 낮은 수준까지 변경합니다(`dev`, `debug`, `info` 또는 `prod`, `warn`, `error`, `prod`). 기본값은 `prod`이며, `info`와 동일합니다.
  + `LogPath` – 지정된 파일 경로로 로그를 출력합니다.
+ `LocalMode` – EC2 인스턴스 메타데이터 확인을 건너뛰려면 `true`로 설정합니다.
+ `ResourceARN` - 데몬을 실행하는 리소스의 Amazon AWS 리소스 이름(ARN)입니다.
+ `RoleARN` – 지정된 IAM 역할을 맡아 세그먼트를 다른 계정으로 업로드합니다.
+ `ProxyAddress` - 프록시를 AWS X-Ray 통해에 세그먼트를 업로드합니다.
+ `Endpoint` – 대몬(daemon)이 세그먼트 문서를 전송하는 X-Ray 서비스 엔드포인트를 변경합니다.
+ `NoVerifySSL` – TLS 인증서 확인을 비활성화합니다.
+ `Version` – 대몬(daemon) 구성 파일 형식 버전. 파일 형식 버전은 **필수** 입력 사항입니다.

**Example xray-daemon.yaml**  
구성 파일은 데몬의 수신 포트를 3000으로 변경하고, 인스턴스 메타데이터 확인을 끄고, 세그먼트 업로드에 사용할 역할을 설정하고, 리전 및 로깅 옵션을 변경합니다.  

```
Socket:
  UDPAddress: "127.0.0.1:3000"
  TCPAddress: "127.0.0.1:3000"
Region: "us-west-2"
Logging:
  LogLevel: "warn"
  LogPath: "/var/log/xray-daemon.log"
LocalMode: true
RoleARN: "arn:aws:iam::123456789012:role/xray-cross-account"
Version: 2
```