기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 적응형 샘플링 구성
이상 스파이크 중에 중요한 추적이 누락되면 근본 원인 분석이 어려울 수 있습니다. 그러나 샘플링 속도를 높게 유지하려면 비용이 많이 듭니다. X-Ray 적응형 샘플링은 이상 현상에 대한 완전한 가시성을 제공하고 정상 운영 중에 비용을 제어합니다. 적응형 샘플링을 사용하면 최대 샘플링 속도를 설정하면 X-Ray가 해당 제한 내에서 자동으로 조정됩니다. X-Ray는 오류 추적을 캡처하는 데 필요한 최소 부스트를 계산합니다. 기준 속도가 충분한 데이터를 캡처하면 부스트가 발생하지 않습니다. 필요한 경우에만 추가 샘플링 비용을 지불합니다.
적응형 샘플링 사용의 이점:
+ 전체 인시던트 가시성 - 인시던트 발생 시 수동 개입 없이 전체 추적을 얻을 수 있습니다. X-Ray는 샘플링 속도를 자동으로 조정하여 오류 추적을 캡처한 다음 정상 속도로 돌아갑니다.
+ 근본 원인 가시성 - 항상 문제의 원인을 확인합니다. X-Ray는 전체 추적 샘플링이 트리거되지 않은 경우에도 중요한 오류 데이터를 캡처합니다.
+ 비용 최적화 - 짧은 샘플링 부스트(최대 1분) 및 자동 휴지 기간이 오버샘플링을 방지합니다. 문제를 진단하는 데 필요한 데이터에 대해서만 비용을 지불합니다.
**Topics**
+ [지원되는 SDK 및 플랫폼](#adaptive-sampling-supported-sdks)
+ [적응형 샘플링 접근 방식 선택](#adaptive-sampling-features)
+ [로컬 SDK 구성](#local-sdk-configuration)
## 지원되는 SDK 및 플랫폼
**지원되는 SDK** - 적응형 샘플링에는 AWS Distro for OpenTelemetry(ADOT) SDK가 필요합니다.
**지원되는 언어**
+ Java(버전 [v2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) 이상)
+ Python(버전 [v0.15.0](https://github.com/aws-observability/aws-otel-python-instrumentation/releases/tag/v0.15.0) 이상)
애플리케이션은 지원되는 ADOT SDK로 계측되고 Amazon CloudWatch 에이전트 또는 OpenTelemetry Collector와 함께 실행되어야 합니다.
예를 들어 Amazon EC2, Amazon ECS 및 Amazon EKS는 AWS Application Signals가 ADOT SDK 및 Amazon CloudWatch 에이전트를 활성화하기 위한 지침을 제공하는 일반적인 플랫폼입니다.
## 적응형 샘플링 접근 방식 선택
적응형 샘플링은 샘플링 부스트와 이상 스팬 캡처라는 두 가지 접근 방식을 지원합니다. 이들은 독립적으로 적용하거나 함께 결합할 수 있습니다.
### 샘플링 부스트
적응형 샘플링 부스트는 샘플링 규칙을 기반으로 하며 기존 X-Ray 헤드 기반 샘플링 모델과 함께 작동합니다. 헤드 기반 샘플링은 루트 서비스에서 샘플링 결정을 내리고 샘플링 플래그가 콜 체인의 모든 서비스에 다운스트림으로 전달됨을 의미합니다.
+ **규칙 기반 부스팅** - 부스팅은 항상 특정 X-Ray 샘플링 규칙과 연결됩니다. 각 규칙은 자체 최대 부스트 속도와 휴지 동작을 정의할 수 있습니다.
+ **헤드 기반 샘플링** - 샘플링 결정은 루트 서비스에서 이루어지며 샘플링 플래그는 콜 체인의 모든 서비스에 다운스트림으로 전달됩니다.
+ **이상 중심** - X-Ray는 SDK를 사용하여 이상 통계를 보고합니다. X-Ray는 오류 또는 높은 지연 시간과 같은 이상을 감지하면 이러한 통계를 사용하여 적절한 부스트 속도(구성된 최대 수치까지)를 계산합니다.
**이상 보고**
직접 호출 체인의 모든 애플리케이션 서비스는 필요한 SDK를 통해 이상 통계를 내보낼 수 있습니다.
+ **루트 서비스** - 샘플링 부스트를 활성화하려면 지원되는 SDK 및 플랫폼에서 실행해야 합니다. 루트 서비스가 지원되지 않으면 부스트가 발생하지 않습니다.
+ **다운스트림 서비스** - 다운스트림 서비스는 이상만 보고하며 샘플링 결정을 내릴 수는 없습니다. 다운스트림 서비스가 지원되는 SDK를 실행 중인 경우 이상 현상이 감지되면 샘플링 부스트가 트리거될 수 있습니다. 다운스트림 서비스가 지원되지 않는 경우(예: 이전 SDK 실행) 해당 서비스의 이상 현상은 부스트를 트리거하지 않습니다. 이러한 서비스는 표준 컨텍스트 전파(예: W3C 추적 컨텍스트 및 배기지)를 따를 때 여전히 다운스트림으로 컨텍스트를 전파할 수 있습니다. 이렇게 하면 추가 다운스트림 서비스에서 지원되는 SDK가 부스트를 트리거하는 이상 현상을 보고할 수 있습니다.
**부스트 타이밍 및 범위**
+ **트리거 지연** - X-Ray가 이상을 감지한 후 최소 10초 후에 샘플링 부스트가 시작될 것으로 예상할 수 있습니다.
+ **부스트 기간** - X-Ray가 부스트를 트리거한 후 최대 1분 동안 지속된 후 기본 샘플링 속도로 돌아갑니다.
+ **휴지 부스트 -** 부스트가 발생한 후 휴지 기간이 경과할 때까지 X-Ray는 동일한 규칙에 대해 다른 부스트를 트리거하지 않습니다.
예를 들어 `cooldown`을 10분으로 설정하면 부스트가 종료되면 다음 10분 기간까지 새 부스트를 트리거할 수 없습니다.
특수 사례: `cooldown`을 1분으로 설정한 경우 부스트 자체가 최대 1분 동안 지속될 수 있으므로 이상이 지속되면 부스트가 계속 효과적으로 트리거될 수 있습니다.
**참고**
루트 서비스에 지원되는 SDK 및 플랫폼을 사용합니다. 샘플링 부스트는 지원되는 SDK 및 플랫폼에서만 작동합니다. 샘플링 부스트는 이상 추적을 캡처할 가능성이 높지만 모든 이상 추적을 캡처하지는 못할 수 있습니다.
**가시성 향상**
샘플링 규칙이 적응형 샘플링 부스트로 구성된 경우 X-Ray는 부스트 활동을 모니터링할 수 있는 판매 지표를 자동으로 내보냅니다.
+ **메트릭 이름** – `SamplingRate`
+ **차원** - `RuleName`(실제 규칙 이름으로 설정됨)
`SamplingRateBoost`가 활성화된 각 규칙은 기준 비율과 임시 부스트를 모두 포함하여 유효 샘플링 비율을 게시합니다. 다음 작업을 수행할 수 있습니다.
+ 부스트가 트리거될 때 추적
+ 각 규칙의 유효 샘플링 속도 모니터링
+ 부스트를 애플리케이션 이상(예: 오류 급증 또는 지연 시간 이벤트)과 연관시킵니다.
**Amazon CloudWatch Metrics의 AWS/X-Ray 네임스페이스에서 이러한 지표를 볼 수 있습니다. 지표 값은 유효 샘플링 속도를 나타내는 0과 1 사이의 부동 소수점 숫자입니다**.
**X-Ray 샘플링 규칙을 사용하여 샘플링 부스트 구성**
새 `SamplingRateBoost` 필드를 추가하여 기존 X-Ray 샘플링 규칙에서 직접 적응형 샘플링을 활성화할 수 있습니다. 자세한 내용은 [샘플링 규칙 사용자 지정](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom)을 참조하세요. 이를 통해 애플리케이션 코드를 수정하거나 애플리케이션 배포를 적용하지 않고도 적응형 샘플링을 활성화할 수 있는 중앙 집중식 방법을 제공합니다. 적응형 샘플링을 활성화하면 X-Ray는 구성된 최대값 내에서 샘플링 속도를 유지하면서 오류 급증 또는 지연 시간 이상치와 같은 이상 현상 중에 샘플링을 자동으로 늘립니다. `SamplingRateBoost`는 `Default` 샘플링 규칙을 제외한 모든 사용자 지정 샘플링 규칙에 적용할 수 있습니다.
`SamplingRateBoost` 필드는 이상 중심 샘플링에 대한 상한 및 동작을 정의합니다.
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10,
"DisableDefaultAnomalyDetection": false
}
```
`MaxRate`는 이상을 감지할 때 X-Ray가 적용할 최대 샘플링 속도를 정의합니다. 값 범위는 `0.0`\~`1.0`입니다. 예를 들어 `"MaxRate": 0.25`는 이상 기간 동안 샘플링이 요청의 최대 25%까지 증가하도록 허용합니다. X-Ray는 이상 활동에 따라 기준과 최대값 사이의 적절한 비율을 결정합니다.
`CooldownWindowMinutes`는 샘플링 속도 부스트를 하나만 트리거할 수 있는 기간(분)을 정의합니다. 부스트가 발생한 후에는 다음 기간까지 추가 부스트가 허용되지 않습니다. 값 유형은 *정수(분)*입니다.
는 ADOT SDK가 기본 제공 기본 이상 조건(HTTP 5xx 장애 응답)을 사용하여 샘플링 부스트를 트리거할지 여부를 `DisableDefaultAnomalyDetection` 제어합니다. 값 유형은 *부울*이고 기본값은 입니다`false`. 로 설정하면 SDK는 기본적으로 HTTP 5xx 응답에 대한 샘플링`true`을 더 이상 부스팅하지 않습니다. 이 경우 부스트는를 통해 명시적으로 정의한 이상 조건에 의해서만 트리거됩니다[로컬 SDK 구성](#local-sdk-configuration). 이상을 구성하는 항목(예: 특정 오류 코드 또는 지연 시간 임계값만)을 완전히 제어하고 모든 5xx 응답에 대한 부스트를 방지하려는 경우이 옵션을 사용합니다.
**적응형 샘플링을 사용하는 규칙 예제**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
이 예제에서 기준 샘플링은 5%(`FixedRate: 0.05`)입니다. 이상 발생 시 X-Ray는 샘플링을 최대 25%(`MaxRate: 0.25`)까지 늘릴 수 있습니다. 10분마다 한 번만 부스트합니다.
**이상 조건 구성**
이상 조건 구성이 제공되지 않은 경우 ADOT SDK는 **HTTP 5xx 오류 코드**를 기본 이상 조건으로 사용하여 샘플링 부스트를 트리거합니다. `SamplingRateBoost` 필드에서 `DisableDefaultAnomalyDetection`를 로 설정하여이 기본값을 비활성화할 수 `true` 있습니다.
환경 변수를 사용하여 지원되는 ADOT SDK에서 이상 조건을 로컬로 미세 조정할 수도 있습니다. 자세한 내용은 [로컬 SDK 구성](#local-sdk-configuration) 단원을 참조하십시오.
### 이상 스팬 캡처
이상 스팬 캡처를 사용하면 전체 추적이 샘플링되지 않더라도 이상을 나타내는 중요한 스팬이 항상 기록됩니다. 이 기능은 향후 추적에 대한 샘플링을 늘리는 대신 이상 현상 자체를 캡처하는 데 집중하여 샘플링 부스트를 보완합니다.
ADOT SDK는 이상을 감지하면 샘플링 결정에 관계없이 즉시 해당 스팬을 방출합니다. SDK는 이상과 관련된 스팬만 내보내므로 이러한 추적은 전체 종단 간 트랜잭션이 아니라 부분 추적입니다.
ADOT SDK가 이상 스팬을 감지하면 동일한 추적에서 가능한 한 많은 스팬을 내보내려고 시도합니다. 이 기능에서 내보내는 모든 스팬에는 속성 `aws.trace.flag.sampled = 0`으로 태그가 지정됩니다. 이를 통해 트랜잭션 검색 및 분석에서 부분 추적(이상 캡처)과 전체 추적(정상 샘플링)을 쉽게 구별할 수 있습니다.
부분 추적을 보고 쿼리하려면 [트랜잭션 검색](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html)을 온보딩하는 것이 좋습니다. 다음 예제는 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) 콘솔의 서비스 페이지를 보여줍니다. ServiceC는 이상 스팬 캡처로 구성되며 샘플링 부스트가 적용되는 콜 체인의 일부입니다. 이 구성은 전체 추적과 부분 추적을 모두 생성합니다. `aws.trace.flag.sampled` 속성을 사용하여 추적 유형을 구분할 수 있습니다.
이상 스팬 캡처는 [로컬 SDK 구성](#local-sdk-configuration)을 통해서만 활성화하거나 사용자 지정할 수 있습니다.
## 로컬 SDK 구성
환경 변수를 통해 YAML 구성을 제공하여 ADOT SDK에서 적응형 샘플링 기능을 구성할 수 있습니다. 로컬 구성은 이상 조건, 임계값을 세밀하게 제어할 수 있습니다.
이는 *이상 스팬 캡처*에 필요하며 *샘플링 부스트* 조건을 사용자 지정하기 위한 선택 사항입니다. 다음은 구성의 예입니다.
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
필드 정의는 다음과 같습니다.
+ `version` - 해당 구성 파일의 스키마 버전입니다.
+ `anomalyConditions` - 이상이 감지되는 조건과 사용 방법을 정의합니다.
+ `errorCodeRegex` - 이상으로 간주되는 HTTP 상태 코드를 정의하는 정규 표현식입니다.
+ `operations` - 조건이 적용되는 작업 또는 엔드포인트 목록이빈다.
+ `highLatencyMs` - 스팬이 이상으로 처리되는 지연 시간 임계값(밀리초)입니다.
+ `usage` - 조건이 적용되는 기능을 정의합니다.
+ `both` - **샘플링 부스트** 및 **이상 스팬 캡처**에 적용됩니다(사용이 지정되지 않은 경우 기본값).
+ `sampling-boost` - 샘플링 부스트를 트리거하는 데만 사용됩니다.
+ `anomaly-span-capture` - 이상 스팬 캡처에만 사용됩니다.
+ `anomalyCaptureLimit` - 이상 스팬이 방출되는 추적 수에 대한 제한을 정의합니다.
`anomalyTracesPerSecond` - 과도한 스팬 볼륨을 방지하기 위해 초당 캡처된 이상 스팬이 있는 최대 추적 수입니다(anomalyCaptureLimit이 없는 경우 기본값은 1).
**참고**
`AnomalyConditions`는 샘플링 부스트(HTTP 5xx)에 대한 기본 이상 조건을 **재정의**합니다. 로컬 구성을 사용하는 동안 기본 조건을 유지하려면 `AnomalyConditions`의 모든 항목에 명시적으로 포함해야 합니다.
각 `anomalyConditions` 항목에 대해:
`operations` 필드를 **생략**하면 조건이 **모든 작업**(서비스 수준)에 적용됩니다.
`operations` 필드가 있지만 **빈 목록**으로 설정된 경우 조건은 **작업 없음**에 적용되므로 해당 항목이 작동하지 않습니다.
`errorCodeRegex` 및 `highLatencyMs`를 모두 생략하면 조건에 평가할 이상 기준이 없으므로 해당 항목이 작동하지 않습니다.
논리적 관계:
`anomalyConditions`의 항목 간 관계는 **OR**입니다.
단일 항목 내에서 여러 필드(예: `errorCodeRegex` 및 `highLatencyMs`)가 **AND**로 결합됩니다.
예제:
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
이 조건은 **상태 코드가 429 또는 5xx와 일치하고 지연 시간이 ≥ 300ms임**을 의미합니다.
### ADOT SDK에 로컬 구성 적용
환경 변수 `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG`를 설정하여 ADOT SDK에 로컬 구성을 적용할 수 있습니다. 값은 유효한 YAML 문서(인라인 또는 중첩)여야 합니다.
예를 들어 Amazon EC2 및 Amazon ECS는 환경 변수를 직접 설정합니다.
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
Amazon EKS의 경우 포드 사양 내의 환경 변수를 중첩된 YAML로 정의합니다.
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```