기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS X-Ray .NET용 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는 C\$1 .NET 웹 애플리케이션, .NET Core 웹 애플리케이션 및 .NET Core 함수를 계측하기 위한 라이브러리입니다 AWS Lambda. 이 라이브러리는 트레이스 데이터를 생성하여 [X-Ray 대몬(daemon)](xray-daemon.md)으로 전송하기 위한 클래스 및 메서드를 제공합니다. 여기에는 애플리케이션에서 제공하는 수신 요청과 애플리케이션이 다운스트림 AWS 서비스, HTTP 웹 APIs 및 SQL 데이터베이스에 수행하는 호출에 대한 정보가 포함됩니다.
**참고**
.NET용 X-Ray SDK는 오픈 소스 프로젝트입니다. 프로젝트를 따르고 GitHub([github.com/aws/aws-xray-sdk-dotnet](https://github.com/aws/aws-xray-sdk-dotnet))에서 문제 및 풀 요청을 제출할 수 있습니다.
웹 애플리케이션의 경우 [메시지 핸들러를 ](xray-sdk-dotnet-messagehandler.md) 웹 구성에 추가하여 수신 요청을 트레이스하는 것부터 시작합니다. 메시지 핸들러는 각 트레이스 요청에 대한 [세그먼트](xray-concepts.md#xray-concepts-segments)를 생성하고, 응답이 전송되면 세그먼트를 완료합니다. 세그먼트가 열려 있는 동안에는 SDK 클라이언트의 메서드를 이용해 정보를 세그먼트에 추가하고 하위 세그먼트를 만들어 다운스트림 호출을 트레이스할 수 있습니다. 또한 SDK는 세그먼트가 열려 있는 동안 애플리케이션에서 발생하는 예외를 자동으로 기록합니다.
계측되는 애플리케이션 또는 서비스에 의해 호출되는 Lambda 함수의 경우, Lambda는 [추적 헤더](xray-concepts.md#xray-concepts-tracingheader)를 읽고 샘플링된 요청을 자동으로 추적합니다. 그 밖의 함수의 경우 수신 요청을 샘플링 및 추적하도록 [Lambda를 구성](xray-services-lambda.md)합니다. 어느 경우든, Lambda는 세그먼트를 생성하여 X-Ray SDK에 제공합니다.
**참고**
Lambda의 X-Ray SDK는 선택 사항입니다. 이를 함수에 사용하지 않는 경우 여전히 서비스 맵에 Lambda 서비스용 노드와 각 Lambda 함수용 노트 하나가 포함됩니다. SDK를 추가하면 함수 코드를 계측하여 Lambda에 의해 기록되는 함수 세그먼트에 하위 세그먼트를 추가할 수 있습니다. 자세한 정보는 [AWS Lambda 및 AWS X-Ray](xray-services-lambda.md)을 참조하세요.
그런 다음, X-Ray SDK for .NET를 사용하여 [AWS SDK for .NET 클라이언트를 계측](xray-sdk-dotnet-sdkclients.md) 합니다. 계측된 클라이언트를 사용하여 다운스트림 AWS 서비스 또는 리소스를 호출할 때마다 SDK는 하위 세그먼트에 호출에 대한 정보를 기록합니다. AWS 서비스 및 서비스 내에서 액세스하는 리소스는 트레이스 맵에 다운스트림 노드로 표시되므로 개별 연결에서 오류 및 제한 문제를 식별하는 데 도움이 됩니다.
또한 .NET용 X-Ray SDK은 [HTTP 웹 API](xray-sdk-dotnet-httpclients.md) 및 [SQL 데이터베이스](xray-sdk-dotnet-sqlqueries.md)에 대한 다운스트림 호출의 계측도 제공합니다. `System.Net.HttpWebRequest`에 대한 `GetResponseTraced` 확장 메서드는 발신 HTTP 호출을 트레이스합니다. .NET용 X-Ray SDK 버전의 `SqlCommand`를 사용하여 SQL 쿼리를 계측할 수 있습니다.
SDK를 사용하기 시작한 후에, [레코더와 메시지 핸들러를 구성](xray-sdk-dotnet-configuration.md)하여 SDK 동작을 구성하십시오. 플러그인을 추가해 애플리케이션을 실행하는 컴퓨팅 리소스에 대한 데이터를 기록하고, 샘플링 규칙을 정의해 샘플링 동작을 구성하고, 로그 레벨을 설정해 애플리케이션 로그의 SDK에서 표시되는 정보 수준을 조절할 수 있습니다.
요청에 대한 추가 정보와 애플리케이션이 [주석 및 메타데이터](xray-sdk-dotnet-segment.md)에서 하는 작업을 기록합니다. 주석은 [필터 표현식](xray-console-filters.md)과 함께 사용할 수 있도록 인덱싱된 단순한 키 값 쌍이기 때문에, 특정 데이터를 포함한 트레이스를 검색할 수 있습니다. 메타데이터 항목은 제한이 적으며 JSON으로 직렬화할 수 있는 모든 객체와 어레이를 기록할 수 있습니다.
**주석 및 메타데이터**
주석 및 메타데이터는 X SDK를 사용하여 세그먼트에 추가하는 임의의 텍스트입니다. 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 메타데이터는 인덱싱되지 않지만 X-Ray 콘솔 또는 API를 사용하여 원시 세그먼트에서 볼 수 있습니다. X-Ray에 대한 읽기 액세스가 부여된 사용자는 누구나 이 데이터를 볼 수 있습니다.
코드에 구성된 클라이언트가 많이 있다면, 구성된 클라이언트로 만든 각 요청의 하위 세그먼트를 대량으로 보관하는 요청 세그먼트 하나를 만들 수 있습니다. [사용자 지정 하위 세그먼트](xray-sdk-dotnet-subsegments.md)의 클라이언트 호출을 래핑해 하위 세그먼트를 조직하고 그룹화할 수 있습니다. 전체 함수나 특정 코드 부분에 대한 사용자 지정 하위 세그먼트를 만들고, 상위 세그먼트에 모든 것을 적는 대신 하위 세그먼트에 메타데이터와 주석을 기록할 수 있습니다.
SDK의 클래스 및 메서드에 대한 참조 문서는 다음을 참조하십시오.
+ [AWS X-Ray SDK for .NET API 참조](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray SDK for .NET Core API 참조](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)
동일한 패키지에서 NET 및 .NET Core를 둘 다 지원하지만, 사용되는 클래스는 다릅니다. 이 장의 예제는 클래스가 .NET Core로 국한된 경우가 아니면 .NET API 참조로 연결됩니다.
## 요구 사항
.NET용 X-Ray SDK에는 .NET Framework 4.5 이상 및가 필요합니다 AWS SDK for .NET.
.NET Core 애플리케이션 및 함수의 경우, SDK에는 .NET Core 2.0 이상이 필요합니다.
## 애플리케이션에 .NET용 X-Ray SDK 추가하기
NuGet을 사용하여 애플리케이션에 .NET용 X-Ray SDK를 추가하세요.
**Visual Studio의 NuGet 패키지 관리자를 사용하여 .NET용 X-Ray SDK를 설치하려면**
1. [**Tools**], [**NuGet Package Manager**], [**Manage NuGet Packages for Solution**]을 선택합니다.
1. **AWSXRayRecorder**를 검색하세요.
1. 패키지를 선택하고 **Install(설치)**을 선택합니다.
## 종속성 관리
.NET용 X-Ray SDK는 [Nuget](https://www.nuget.org/packages/AWSXRayRecorder/)에서 사용할 수 있습니다. 패키지 관리자를 사용하여 SDK를 설치합니다:
```
Install-Package AWSXRayRecorder -Version 2.10.1
```
`AWSXRayRecorder v2.10.1` nuget 패키지에는 다음과 같은 종속성을 가지고 있습니다:
### NET Framework 4.5
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
|
|-- AWSXRayRecorder.Handlers.AspNet (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- EntityFramework (>= 6.2.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
### NET Framework 2.0
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
| |-- Microsoft.AspNetCore.Http (>= 2.0.0)
| |-- Microsoft.Extensions.Configuration (>= 2.0.0)
| |-- System.Net.Http (>= 4.3.4)
|
|-- AWSXRayRecorder.Handlers.AspNetCore (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.AspNetCore.Http.Extensions (>= 2.0.0)
| |-- Microsoft.AspNetCore.Mvc.Abstractions (>= 2.0.0)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.EntityFrameworkCore.Relational (>= 3.1.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- System.Data.SqlClient (>= 4.4.0)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
종속성 관리에 대한 자세한 내용은 [Nuget 종속성](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies) 및 [Nuget 종속성 해결](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution)에 대한 Microsoft 의 문서를 참조하십시오.