기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# .NET용 X-Ray SDK 구성
**참고**
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)을 참조하세요.
애플리케이션이 실행되는 서비스에 대한 정보를 포함하거나, 기본 샘플링 동작을 수정하거나 요청에 적용되는 샘플링 규칙을 특정 경로에 추가하도록 플러그인을 사용하여 .NET용 X-Ray SDK를 구성할 수 있습니다.
.NET 웹 애플리케이션의 경우 키를 `Web.config` 파일의 `appSettings` 섹션에 추가합니다.
**Example Web.config**
```
```
.NET Core의 경우, `XRay`를 최상위 키로 지정하여 `appsettings.json` 파일을 생성합니다.
**Example .NET appsettings.json**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin",
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
그런 다음 애플리케이션 코드에서 구성 객체를 빌드하고 이 객체를 사용하여 X 레코더를 초기화합니다. [레코더를 초기화하기](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs) 전에 이 작업을 수행합니다.
**Example .NET Core Program.cs – 레코더 구성**
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```
.NET Core 웹 애플리케이션을 계측하는 경우 [메시지 핸들러를 구성](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs)할 때 `UseXRay` 메서드에 구성 개체를 전달할 수도 있습니다. Lambda 함수의 경우 위와 같이 `InitializeInstance` 메서드를 사용합니다.
.NET Core 구성 API에 대한 자세한 내용은 docs.microsoft.com에서 [ASP.NET Core 앱 구성](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration)을 참조하세요.
**Topics**
+ [플러그인](#xray-sdk-dotnet-configuration-plugins)
+ [샘플링 규칙](#xray-sdk-dotnet-configuration-sampling)
+ [로깅 (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [로깅(.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [환경 변수](#xray-sdk-dotnet-configuration-envvars)
## 플러그인
플러그인을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 데이터를 추가합니다.
**플러그인**
+ Amazon EC2 — `EC2Plugin`은 인스턴스 ID, 가용 영역 및 CloudWatch Logs 그룹을 추가합니다.
+ Elastic Beanstalk – `ElasticBeanstalkPlugin`이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.
+ Amazon ECS — `ECSPlugin`이 컨테이너 ID를 추가합니다.
플러그인을 사용하려면 `AWSXRayPlugins` 설정을 추가하여 .NET용 X-Ray SDK 클라이언트를 구성합니다. 여러 플러그인을 애플리케이션에 적용하는 경우 플러그인을 모두 동일 설정 안에 쉼표로 구분하여 지정합니다.
**Example Web.config - 플러그인**
```
```
**Example .NET Core appsettings.json – 플러그인**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
}
}
```
## 샘플링 규칙
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 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.
에서는 샘플링 속도를 수정할 수 AWS Lambda없습니다. 구성된 서비스가 함수를 호출하는 경우 해당 서비스에서 샘플링한 요청을 생성한 호출이 Lambda에 의해 기록됩니다. 활성 추적이 활성화되고 트레이스 헤더가 없는 경우 Lambda에서 샘플링 결정을 내립니다.
백업 규칙을 구성하려면 `SamplingRuleManifest` 설정을 사용하여 파일에서 샘플링 규칙을 로드하도록 .NET용 X-Ray SDK에 지시합니다.
**Example .NET Web.config - 샘플링 규칙**
```
```
**Example .NET Core appsettings.json – 샘플링 규칙**
```
{
"XRay": {
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
로컬 규칙만 사용하려면 `LocalizedSamplingStrategy`를 사용하여 레코더를 빌드합니다. 백업 규칙을 구성한 경우 해당 구성을 제거합니다.
**Example .NET global.asax – 로컬 샘플링 규칙**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy({{"samplingrules.json"}})).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
```
**Example .NET Core Program.cs – 로컬 샘플링 규칙**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy({{"sampling-rules.json"}})).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);
```
## 로깅 (.NET)
.NET용 X-Ray SDK는 [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)와 동일한 로깅 메커니즘을 사용합니다. AWS SDK for .NET 출력을 로깅하도록 애플리케이션을 이미 구성한 경우 .NET용 X-Ray SDK의 출력에 동일한 구성이 적용됩니다.
로깅을 구성하려면 `aws`라는 구성 섹션을 `App.config` 파일이나 `Web.config` 파일에 추가합니다.
**Example Web.config - 로깅**
```
...
```
자세한 내용은 *AWS SDK for .NET 개발자 안내서*의 [AWS SDK for .NET 애플리케이션 구성](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html)을 참조하십시오.
## 로깅(.NET Core)
.NET용 X-Ray SDK는 [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging)와 동일한 로깅 옵션을 사용합니다. .NET Core 응용 프로그램의 로깅을 구성하려면 로깅 옵션을 `AWSXRayRecorder.RegisterLogger` 메서드에 전달하십시오.
예를 들어 log4net을 사용하려면 로거, 출력 형식 및 파일 위치를 정의하는 구성 파일을 생성합니다.
**Example .NET Core log4net.config**
```
```
그런 다음 로거를 생성하고 프로그램 코드에 해당 구성을 적용합니다.
**Example .NET Core Program.cs — 로깅**
```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
class Program
{
private static ILog log;
static Program()
{
var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
log = LogManager.GetLogger(typeof(Program));
AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
}
static void Main(string[] args)
{
...
}
}
```
log4net 구성에 대한 자세한 내용은 logging.apache.org의 [구성](https://logging.apache.org/log4net/release/manual/configuration.html)을 참조하십시오.
## 환경 변수
환경 변수를 사용하여 .NET용 X-Ray SDK를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.
+ `AWS_XRAY_TRACING_NAME` – SDK가 세그먼트에 사용할 서비스 이름을 설정합니다. 서블릿 필터의 [세그먼트 이름 지정 전략](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming)에 설정한 서비스 이름을 재정의합니다.
+ `AWS_XRAY_DAEMON_ADDRESS` – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 SDK는 추적 데이터(UDP)와 샘플링(TCP) 모두에 `127.0.0.1:2000`을 사용합니다. [다른 포트에서 수신 대기](xray-daemon-configuration.md)하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.
**형식**
+ **동일한 포트** – `{{address}}:{{port}}`
+ **다른 포트** – `tcp:{{address}}:{{port}} udp:{{address}}:{{port}}`
+ `AWS_XRAY_CONTEXT_MISSING` – 열려 있는 세그먼트가 없는 경우 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 `RUNTIME_ERROR`로 설정합니다.
**유효한 값**
+ `RUNTIME_ERROR`— 런타임 예외가 발생합니다.
+ `LOG_ERROR` – 오류를 기록하고 계속합니다 (기본값).
+ `IGNORE_ERROR`— 오류를 무시하고 계속합니다.
열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.