기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
루비를 SDK 위한 X-Ray 설정하기
SDKRuby용 X-Ruby에는 글로벌 레코더를 XRay.recorder
제공하는 클래스가 있습니다. 수신 전화를 위한 세그먼트를 생성하는 미들웨어를 사용자 지정하도록 글로벌 레코더를 구성할 수 있습니다. HTTP
서비스 플러그인
plugins
을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.
플러그인
-
Amazon EC2 — 인스턴스 ID 및 가용 영역을
ec2
추가합니다. -
Elastic Beanstalk –
elastic_beanstalk
이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다. -
Amazon ECS — 컨테이너 ID를
ecs
추가합니다.
플러그인을 사용하려면 레코더로 전달하는 구성 객체에서 해당 플러그인을 지정합니다.
예 main.rb – 플러그인 구성
my_plugins = %I[ec2 elastic_beanstalk]
config = {
plugins: my_plugins,
name: 'my app',
}
XRay.recorder.configure(config)
또한 코드에 설정된 값보다 우선하는 환경 변수를 사용하여 레코더를 구성할 수 있습니다.
SDK또한 플러그인 설정을 사용하여 세그먼트에 origin
필드를 설정합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK 는 다음 해결 순서를 사용하여 출처를 결정합니다 ( ElasticBeanstalk > EKS ECS >)EC2.
샘플링 규칙
는 X-Ray 콘솔에서 정의한 샘플링 규칙을 SDK 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. X-Ray 콘솔에서 추가 규칙을 생성하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.
는 정의된 순서대로 사용자 지정 규칙을 SDK 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 는 첫 번째 규칙만 SDK 적용합니다.
참고
샘플링 규칙을 가져오기 위해 X-Ray에 연결할 SDK 수 없는 경우 1초마다 첫 번째 요청의 기본 로컬 규칙으로 되돌아가고 호스트당 추가 요청의 5% 로 되돌아갑니다. 이는 호스트가 샘플링을 APIs 호출할 권한이 없거나 에서 걸려온 호출에 대한 TCP API 프록시 역할을 하는 X-Ray 데몬에 연결할 수 없는 경우에 발생할 수 있습니다. SDK
문서에서 샘플링 규칙을 SDK 로드하도록 를 구성할 수도 있습니다JSON. 는 X-Ray 샘플링을 사용할 SDK 수 없는 경우 로컬 규칙을 백업으로 사용하거나 로컬 규칙만 사용할 수 있습니다.
예 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 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.
백업 규칙을 구성하려면 레코더로 전달하는 구성 객체에서 문서에 대한 해시를 정의합니다.
예 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)
샘플링 규칙을 독립적으로 저장하려면 별도 파일에 해시를 정의하고 파일이 애플리케이션으로 해시를 가져오도록 합니다.
예 config/sampling-rules.rb
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}
예 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
를 구성합니다.
예 main.rb – 로컬 샘플링 규칙
require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config)
또한 샘플링을 비활성하하고 모든 수신 요청을 구성하도록 전역 레코더를 구성할 수 있습니다.
예 main.rb – 샘플링 비활성화
require 'aws-xray-sdk'
config = {
sampling: false,
name: 'my app',
}
XRay.recorder.configure(config)
로깅
기본적으로 레코더는 정보 레벨 이벤트를 $stdout
로 출력합니다. 레코더로 전달하는 구성 객체에서 로거
예 main.rb – 로깅
require 'aws-xray-sdk'
config = {
logger: my_logger,
name: 'my app',
}
XRay.recorder.configure(config)
디버그 로그를 사용하여 수동으로 하위 세그먼트를 생성할 때 미완료 하위 세그먼트와 같은 문제를 식별할 수 있습니다.
코드의 레코더 구성
XRay.recorder
에 대한 configure
메서드에서 추가 설정을 사용할 수 있습니다.
-
context_missing
– 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면LOG_ERROR
로 설정합니다. -
daemon_address
– X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. -
name
- 세그먼트에 사용할 서비스 이름을 설정합니다. SDK -
naming_pattern
– 동적 이름 지정을 사용하려면 도메인 이름 패턴을 설정합니다. -
plugins
– 플러그인을 사용하여 애플리케이션의 AWS 리소스에 대한 정보를 기록합니다. -
sampling
– 샘플링을 비활성화하려면false
로 설정합니다. -
sampling_rules
– 샘플링 규칙이 포함된 해시를 설정합니다.
예 main.rb – 컨텍스트 누락 예외 비활성화
require 'aws-xray-sdk'
config = {
context_missing: 'LOG_ERROR'
}
XRay.recorder.configure(config)
Rails를 사용한 레코더 구성
Rails 프레임워크를 사용하는 경우 app_root/initializers
아래의 Ruby 파일을 사용하여 전역 레코더의 옵션을 구성할 수 있습니다. SDKX-Ray는 Rails와 함께 사용하기 위한 추가 구성 키를 지원합니다.
-
active_record
– Active Record 데이터베이스 트랜잭션에 대한 하위 세그먼트를 기록하려면true
로 설정합니다.
이름이 Rails.application.config.xray
인 구성 객체에서 사용 가능한 설정을 구성합니다.
예 config/initializers/aws_xray.rb
Rails.application.config.xray = {
name: 'my app',
patch: %I[net_http aws_sdk],
active_record: true
}
환경 변수
환경 변수를 사용하여 SDK Ruby용 X-Ray를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.
-
AWS_XRAY_TRACING_NAME
— 세그먼트에 사용할 서비스 이름을 설정합니다. SDK 서블릿 필터의 세그먼트 이름 지정 전략에 설정한 서비스 이름을 재정의합니다. AWS_XRAY_DAEMON_ADDRESS
– X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 는 추적 데이터를 로 SDK 보냅니다127.0.0.1:2000
. 다른 포트에서 수신 대기하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.AWS_XRAY_CONTEXT_MISSING
– 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면RUNTIME_ERROR
로 설정합니다.유효한 값
-
RUNTIME_ERROR
— 런타임 예외가 발생합니다. -
LOG_ERROR
– 오류를 기록하고 계속합니다 (기본값). -
IGNORE_ERROR
— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.
-
환경 변수는 코드에 설정된 값을 재정의합니다.