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

# Ruby용 X-Ray SDK 구성
<a name="xray-sdk-ruby-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)을 참조하세요.

Ruby용 X-Ray SDK에는 전역 레코더를 제공하는 `XRay.recorder`라는 클래스가 있습니다. 수신 HTTP 호출에 대해 세그먼트를 생성하는 미들웨어를 사용자 지정하도록 전역 레코더를 구성할 수 있습니다.

**Topics**
+ [서비스 플러그인](#xray-sdk-ruby-configuration-plugins)
+ [샘플링 규칙](#xray-sdk-ruby-configuration-sampling)
+ [로깅](#xray-sdk-ruby-configuration-logging)
+ [코드의 레코더 구성](#xray-sdk-ruby-configuration-code)
+ [Rails를 사용한 레코더 구성](#xray-sdk-ruby-middleware-configuration-rails)
+ [환경 변수](#xray-sdk-ruby-configuration-envvars)

## 서비스 플러그인
<a name="xray-sdk-ruby-configuration-plugins"></a>

`plugins`을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.

**플러그인**
+ Amazon EC2 – `ec2`이 인스턴스 ID와 가용 영역을 추가합니다.
+ Elastic Beanstalk – `elastic_beanstalk`이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
+ Amazon ECS — `ecs`이 컨테이너 ID를 추가합니다.

![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)


플러그인을 사용하려면 레코더로 전달하는 구성 객체에서 해당 플러그인을 지정합니다.

**Example main.rb – 플러그인 구성**  

```
my_plugins = %I[ec2 elastic_beanstalk]

config = {
  plugins: my_plugins,
  name: 'my app',
}

XRay.recorder.configure(config)
```

또한 코드에 설정된 값보다 우선하는 [환경 변수](#xray-sdk-ruby-configuration-envvars)를 사용하여 레코더를 구성할 수 있습니다.

SDK는 플러그인 설정을 사용하여 세그먼트에 `origin` 필드를 설정하기도 합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK는 ElasticBeanstalk> EKS> ECS> EC2 순서로 확인하여 오리진을 결정합니다.

## 샘플링 규칙
<a name="xray-sdk-ruby-configuration-sampling"></a>

SDK는 X-Ray 콘솔에서 정의하는 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. [X-Ray 콘솔에서 추가 규칙을 생성](xray-console-sampling.md)하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.

SDK는 사용자 지정 규칙을 정의된 순서대로 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 SDK는 첫 번째 규칙만 적용합니다.

**참고**  
SDK가 샘플링 규칙을 가져오기 위해 X-Ray에 연결할 수 없는 경우, 매초 첫 번째 요청과 호스트당 추가 요청의 5%에 대한 기본 로컬 규칙으로 되돌아갑니다. 호스트가 샘플링 API를 직접 호출할 수 있는 권한이 없거나, X-Ray 대몬(daemon)에 연결할 수 없을 경우 이러한 상황이 발생할 수 있고 이 대몬(daemon)은 SDK에서 수행한 API 직접 호출에 대한 TCP 프록시 역할을 합니다.

JSON 문서에서 샘플링 규칙을 불러오도록 SDK를 구성할 수도 있습니다. SDK는 X-Ray 샘플링을 사용할 수 없을 경우 로컬 규칙을 백업으로 사용하거나, 로컬 규칙을 전용으로 사용할 수 있습니다.

**Example sampling-rules.json**  

```
{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}
```

이 예에서는 하나의 사용자 지정 규칙과 기본 규칙을 정의합니다. 사용자 지정 규칙은 최소 추적 요청 수 없이 5% 샘플링 비율을 `/api/move/` 아래 경로에 적용합니다. 기본 규칙은 매초 최초 요청과 추가 요청의 10%를 추적합니다.

로컬로 규칙의 정의할 때의 단점은 고정 대상이 X-Ray 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.

백업 규칙을 구성하려면 레코더로 전달하는 구성 객체에서 문서에 대한 해시를 정의합니다.

**Example main.rb – 백업 규칙 구성**  

```
require 'aws-xray-sdk'
my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}
config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)
```

샘플링 규칙을 독립적으로 저장하려면 별도 파일에 해시를 정의하고 파일이 애플리케이션으로 해시를 가져오도록 합니다.

**Example config/sampling-rules.rb**  

```
my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}
```

**Example main.rb – 파일의 샘플링 규칙**  

```
require 'aws-xray-sdk'
require 'config/sampling-rules.rb'

config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)
```

로컬 규칙만 사용하려면 샘플링 규칙을 요청하고 `LocalSampler`를 구성합니다.

**Example main.rb – 로컬 샘플링 규칙**  

```
require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'

config = {
  sampler: LocalSampler.new,
  name: 'my app',
}
XRay.recorder.configure(config)
```

또한 샘플링을 비활성하하고 모든 수신 요청을 구성하도록 전역 레코더를 구성할 수 있습니다.

**Example main.rb – 샘플링 비활성화**  

```
require 'aws-xray-sdk'
config = {
  sampling: false,
  name: 'my app',
}
XRay.recorder.configure(config)
```

## 로깅
<a name="xray-sdk-ruby-configuration-logging"></a>

기본적으로 레코더는 정보 레벨 이벤트를 `$stdout`로 출력합니다. 레코더로 전달하는 구성 객체에서 [로거](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html)를 정의하여 로깅을 사용자 정의할 수 있습니다.

**Example main.rb – 로깅**  

```
require 'aws-xray-sdk'
config = {
  logger: my_logger,
  name: 'my app',
}
XRay.recorder.configure(config)
```

디버그 로그를 사용하여 [수동으로 하위 세그먼트를 생성](xray-sdk-ruby-subsegments.md)할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.

## 코드의 레코더 구성
<a name="xray-sdk-ruby-configuration-code"></a>

`XRay.recorder`에 대한 `configure` 메서드에서 추가 설정을 사용할 수 있습니다.
+ `context_missing` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `LOG_ERROR`로 설정합니다.
+ `daemon_address` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다.
+ `name` – SDK가 세그먼트에 사용하는 서비스 이름을 설정합니다.
+ `naming_pattern` – [동적 이름 지정](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)을 사용하려면 도메인 이름 패턴을 설정합니다.
+ `plugins` – [플러그인](#xray-sdk-ruby-configuration-plugins)을 사용하여 애플리케이션의 AWS 리소스에 대한 정보를 기록합니다.
+ `sampling` – 샘플링을 비활성화하려면 `false`로 설정합니다.
+ `sampling_rules` – [샘플링 규칙](#xray-sdk-ruby-configuration-sampling)이 포함된 해시를 설정합니다.

**Example main.rb – 컨텍스트 누락 예외 비활성화**  

```
require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)
```

## Rails를 사용한 레코더 구성
<a name="xray-sdk-ruby-middleware-configuration-rails"></a>

Rails 프레임워크를 사용하는 경우 `app_root/initializers` 아래의 Ruby 파일을 사용하여 전역 레코더의 옵션을 구성할 수 있습니다. X-Ray SDK는 Rails와 함께 사용할 수 있는 추가 구성 키를 지원합니다.
+ `active_record` – Active Record 데이터베이스 트랜잭션에 대한 하위 세그먼트를 기록하려면 `true`로 설정합니다.

이름이 `Rails.application.config.xray`인 구성 객체에서 사용 가능한 설정을 구성합니다.

**Example config/initializers/aws\$1xray.rb**  

```
Rails.application.config.xray = {
  name: 'my app',
  patch: %I[net_http aws_sdk],
  active_record: true
}
```

## 환경 변수
<a name="xray-sdk-ruby-configuration-envvars"></a>

환경 변수를 사용하여 Ruby용 X-Ray SDK를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다: 
+ `AWS_XRAY_TRACING_NAME` – SDK가 세그먼트에 사용할 서비스 이름을 설정합니다. 서블릿 필터의 [세그먼트 이름 지정 전략](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)에 설정한 서비스 이름을 재정의합니다.
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 SDK는 `127.0.0.1:2000`에 트레이스 데이터를 보냅니다. [다른 포트에서 수신 대기](xray-daemon-configuration.md)하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
+ `AWS_XRAY_CONTEXT_MISSING` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `RUNTIME_ERROR`로 설정합니다.

**유효한 값**
  + `RUNTIME_ERROR`— 런타임 예외가 발생합니다.
  + `LOG_ERROR` – 오류를 기록하고 계속합니다 (기본값).
  + `IGNORE_ERROR`— 오류를 무시하고 계속합니다.

  열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.

환경 변수는 코드에 설정된 값을 재정의합니다.