기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # OpenTelemetry .NET으로 마이그레이션 .NET 애플리케이션에서 X-Ray 추적을 사용하는 경우 수동 작업이 포함된 X-Ray .NET SDK가 계측에 사용됩니다. 이 섹션에서는 X-Ray 수동 계측 솔루션에서 .NET용 OpenTelemetry 수동 계측 솔루션으로 마이그레이션하기 위한 [SDK를 사용한 수동 계측 솔루션](#manual-instrumentation-dotnet) 섹션의 코드 예제를 제공합니다. 또는 [제로 코드 자동 계측 솔루션](#zero-code-instrumentation-dotnet) 섹션에서 애플리케이션 소스 코드를 수정할 필요 없이 X-Ray 수동 계측에서 OpenTelemetry 자동 계측 솔루션으로 마이그레이션하여 .NET 애플리케이션을 계측할 수 있습니다. **Topics** + [제로 코드 자동 계측 솔루션](#zero-code-instrumentation-dotnet) + [SDK를 사용한 수동 계측 솔루션](#manual-instrumentation-dotnet) + [추적 데이터 수동 생성](#manual-trace-creation-dotnet) + [수신 요청 추적(ASP.NET 및 ASP.NET 코어 계측)](#tracing-incoming-requests-dotnet) + [AWS SDK 계측](#aws-sdk-instrumentation-dotnet) + [발신 HTTP 호출 구성](#http-instrumentation-dotnet) + [다른 라이브러리에 대한 계측 지원](#other-libraries-dotnet) + [Lambda 계측](#lambda-instrumentation) ## 제로 코드 자동 계측 솔루션 OpenTelemetry는 제로 코드 자동 계측 솔루션을 제공합니다. 이러한 솔루션은 애플리케이션 코드를 변경할 필요 없이 요청을 추적합니다. **OpenTelemetry 기반 자동 계측 옵션** 1. .NET용 AWS Distro for OpenTelemetry(ADOT) 자동 계측 사용 - .NET 애플리케이션을 자동으로 계측하려면 [AWS Distro for OpenTelemetry .NET Auto-Instrumentation을 사용하여 추적 및 지표를 참조하세요](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr). (선택 사항) ADOT .NET 자동 계측 AWS 을 사용하여에서 애플리케이션을 자동으로 계측할 때 CloudWatch Application Signals를 활성화하여 다음을 수행합니다. + 현재 애플리케이션 상태 모니터링 + 비즈니스 목표를 기준으로 장기 애플리케이션 성능 추적 + 애플리케이션, 서비스 및 종속성에 대한 통합된 애플리케이션 중심 보기 가져오기 + 애플리케이션 상태 모니터링 및 분류 자세한 내용은 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)를 참조하세요. 1. OpenTelemetry .Net 제로 코드 자동 계측 사용 - OpenTelemetry .Net을 사용하여 자동으로 계측하려면 [AWS Distro for OpenTelemetry .NET Auto-Instrumentation을 사용하여 추적 및 지표를 참조하세요](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr). ## SDK를 사용한 수동 계측 솔루션 ------ #### [ Tracing configuration with X-Ray SDK ] .NET 웹 애플리케이션의 경우 X-Ray SDK는 `Web.config` 파일의 appSettings 섹션에 구성됩니다. Web.config 예제 ``` ``` .NET Core의 경우 `appsettings.json`이라는 최상위 키가 있는 `XRay`라는 파일이 사용된 다음 X-Ray 레코더를 초기화하기 위해 구성 객체가 빌드됩니다. .NET `appsettings.json`용 예제 ``` { "XRay": { "AWSXRayPlugins": "EC2Plugin" } } ``` .NET Core Program.cs 예제 – 레코더 구성 ``` using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration); ``` ------ #### [ Tracing configuration with OpenTelemetry SDK ] **** 다음 종속성을 추가합니다. ``` dotnet add package OpenTelemetry dotnet add package OpenTelemetry.Contrib.Extensions.AWSXRay dotnet add package OpenTelemetry.Sampler.AWS --prerelease dotnet add package OpenTelemetry.Resources.AWS dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package OpenTelemetry.Instrumentation.AspNetCore ``` .NET 애플리케이션의 경우 Global TracerProvider를 설정하여 OpenTelemetry SDK를 구성합니다. 다음 예제 구성은 `ASP.NET Core`에 대한 계측도 활성화합니다. `ASP.NET`을 계측하려면 [수신 요청 추적(ASP.NET 및 ASP.NET 코어 계측)](#tracing-incoming-requests-dotnet) 섹션을 참조하세요. OpenTelemetry를 다른 프레임워크와 함께 사용하려면 [레지스트리](https://opentelemetry.io/ecosystem/registry/)에서 지원되는 프레임워크에 대한 추가 라이브러리를 참조하세요. 다음 구성 요소를 구성하는 것이 좋습니다. + `An OTLP Exporter` - CloudWatch 에이전트/OpenTelemetry Collector로 추적을 내보내는 데 필요합니다. + AWS X-Ray 전파기 - 추적 컨텍스트를 [AWS X-Ray와 통합된 서비스로 전파하는](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) 데 필요합니다. + AWS X-Ray 원격 샘플러 - [X-Ray 샘플링 규칙을 사용하여 요청을 샘플링](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)해야 하는 경우 필요합니다. + `Resource Detectors`(예: Amazon EC2 Resource Detector) - 애플리케이션을 실행하는 호스트의 메타데이터를 감지하는 방법입니다. ``` using OpenTelemetry; using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace; using OpenTelemetry.Sampler.AWS; using OpenTelemetry.Trace; using OpenTelemetry.Resources; var builder = WebApplication.CreateBuilder(args); var serviceName = "MyServiceName"; var serviceVersion = "1.0.0"; var resourceBuilder = ResourceBuilder .CreateDefault() .AddService(serviceName: serviceName) .AddAWSEC2Detector(); builder.Services.AddOpenTelemetry() .ConfigureResource(resource => resource .AddAWSEC2Detector() .AddService( serviceName: serviceName, serviceVersion: serviceVersion)) .WithTracing(tracing => tracing .AddSource(serviceName) .AddAspNetCoreInstrumentation() .AddOtlpExporter() .SetSampler(AWSXRayRemoteSampler.Builder(resourceBuilder.Build()) .SetEndpoint("http://localhost:2000") .Build())); Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator ``` 콘솔 앱에 OpenTelemetry를 사용하려면 프로그램을 시작할 때 다음 OpenTelemetry 구성을 추가합니다. ``` using OpenTelemetry; using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace; using OpenTelemetry.Trace; using OpenTelemetry.Resources; var serviceName = "MyServiceName"; var resourceBuilder = ResourceBuilder .CreateDefault() .AddService(serviceName: serviceName) .AddAWSEC2Detector(); var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource(serviceName) .ConfigureResource(resource => resource .AddAWSEC2Detector() .AddService( serviceName: serviceName, serviceVersion: serviceVersion ) ) .AddOtlpExporter() // default address localhost:4317 .SetSampler(new TraceIdRatioBasedSampler(1.00)) .Build(); Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure X-Ray propagator ``` ------ ## 추적 데이터 수동 생성 ------ #### [ With X-Ray SDK ] X-Ray SDK를 사용하면 X-Ray 세그먼트 및 하위 세그먼트를 수동으로 생성하는 데 `BeginSegment` 및 `BeginSubsegment` 메서드가 필요했습니다. ``` using Amazon.XRay.Recorder.Core; AWSXRayRecorder.Instance.BeginSegment("segment name"); // generates `TraceId` for you try { // Do something here // can create custom subsegments AWSXRayRecorder.Instance.BeginSubsegment("subsegment name"); try { DoSometing(); } catch (Exception e) { AWSXRayRecorder.Instance.AddException(e); } finally { AWSXRayRecorder.Instance.EndSubsegment(); } } catch (Exception e) { AWSXRayRecorder.Instance.AddException(e); } finally { AWSXRayRecorder.Instance.EndSegment(); } ``` ------ #### [ With OpenTelemetry SDK ] .NET에서는 활동 API를 사용하여 사용자 지정 스팬을 생성함으로써 계측 라이브러리로 캡처되지 않은 내부 활동의 성능을 모니터링할 수 있습니다. 스팬 종류 서버만 X-Ray 세그먼트로 변환되고 다른 모든 스팬은 X-Ray 하위 세그먼트로 변환됩니다. 필요한 만큼 `ActivitySource` 인스턴스를 생성할 수 있지만 전체 애플리케이션/서비스에 대해 하나만 사용하는 것이 좋습니다. ``` using System.Diagnostics; ActivitySource activitySource = new ActivitySource("ActivitySourceName", "ActivitySourceVersion"); ... using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment { // Do something here using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment { // Do something here } } ``` **OpenTelemetry SDK를 사용하여 추적에 주석 및 메타데이터 추가** 활동에서 `SetTag` 메서드를 사용하여 사용자 지정 키-값 페어를 스팬에 속성으로 추가할 수도 있습니다. 기본적으로 모든 스팬 속성은 X-Ray 원시 데이터의 메타데이터로 변환됩니다. 속성이 메타데이터가 아닌 주석으로 변환되도록 하려면 해당 속성의 키를 `aws.xray.annotations` 속성 목록에 추가할 수 있습니다. ``` using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment { activity.SetTag("metadataKey", "metadataValue"); activity.SetTag("annotationKey", "annotationValue"); string[] annotationKeys = {"annotationKey"}; activity.SetTag("aws.xray.annotations", annotationKeys); // Do something here using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment { // Do something here } } ``` **OpenTelemetry 자동 계측 사용** .NET용 OpenTelemetry 자동 계측 솔루션을 사용하고 애플리케이션에서 수동 계측을 수행해야 하는 경우, 예를 들어 자동 계측 라이브러리에서 다루지 않는 섹션의 애플리케이션 자체 내에서 코드를 계측해야 하는 경우입니다. 하나의 글로벌 `TracerProvider`만 있을 수 있으므로 수동 계측은 자동 계측과 함께 사용하는 경우 자체 `TracerProvider`를 인스턴스화해서는 안 됩니다. `TracerProvider`를 사용하는 경우 사용자 지정 수동 추적은 OpenTelemetry SDK를 통해 자동 계측 또는 수동 계측을 사용할 때와 동일한 방식으로 작동합니다. ------ ## 수신 요청 추적(ASP.NET 및 ASP.NET 코어 계측) ------ #### [ With X-Ray SDK ] ASP.NET 애플리케이션에서 제공하는 요청을 계측하려면 [https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html) 섹션에서 `global.asax` 파일의 `Init` 메서드에서 `RegisterXRay`를 직접적으로 호출하는 방법에 대한 자세한 내용을 참조하세요. ``` AWSXRayASPNET.RegisterXRay(this, "MyApp"); ``` ASP.NET 코어 애플리케이션에서 제공하는 요청을 계측하기 위해 `UseXRay` 메서드는 Startup 클래스의 `Configure` 메서드에 있는 다른 미들웨어보다 먼저 직접적으로 호출됩니다. ``` app.UseXRay("MyApp"); ``` ------ #### [ With OpenTelemetry SDK ] 또한 OpenTelemetry는 ASP.NET 및 ASP.NET 코어에 대한 수신 웹 요청에 대한 추적을 수집하는 계측 라이브러리를 제공합니다. 다음 섹션에서는 Tracer 공급자를 생성할 때 [ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) 또는 [ASP.NET](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0) 코어 계측을 추가하는 방법을 포함하여 OpenTelemetry 구성에 이러한 라이브러리 계측을 추가하고 활성화하는 데 필요한 단계를 나열합니다. OpenTelemetry.Instrumentation.AspNet을 활성화하는 방법에 대한 자세한 내용은 [OpenTelemetry.Instrumentation.AspNet을 활성화하는 단계](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)를 참조하고, OpenTelemetry.Instrumentation.AspNetCore를 활성화하는 방법에 대한 자세한 내용은 [OpenTelemetry.Instrumentation.AspNetCore를 활성화하는 단계](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore)를 참조하세요. ------ ## AWS SDK 계측 ------ #### [ With X-Ray SDK ] 를 호출하여 모든 AWS SDK 클라이언트를 설치합니다`RegisterXRayForAllServices()`. ``` using Amazon.XRay.Recorder.Handlers.AwsSdk; AWSSDKHandler.RegisterXRayForAllServices(); //place this before any instantiation of AmazonServiceClient AmazonDynamoDBClient client = new AmazonDynamoDBClient(RegionEndpoint.USWest2); // AmazonDynamoDBClient is automatically registered with X-Ray ``` 특정 AWS 서비스 클라이언트 계측에는 다음 방법 중 하나를 사용합니다. ``` AWSSDKHandler.RegisterXRay(); // Registers specific type of AmazonServiceClient : All instances of IAmazonDynamoDB created after this line are registered AWSSDKHandler.RegisterXRayManifest(String path); // To configure custom AWS Service Manifest file. This is optional, if you have followed "Configuration" section ``` ------ #### [ With OpenTelemetry SDK ] 다음 코드 예제의 경우 다음 종속성이 필요합니다. ``` dotnet add package OpenTelemetry.Instrumentation.AWS ``` AWS SDK를 계측하려면 Global TracerProvider가 설정된 OpenTelemetry SDK 구성을 업데이트합니다. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddAWSInstrumentation() ... ``` ------ ## 발신 HTTP 호출 구성 ------ #### [ With X-Ray SDK ] X-Ray .NET SDK는 `System.Net.HttpWebRequest`를 사용할 경우 확장 메서드 `GetResponseTraced()` 또는 `GetAsyncResponseTraced()`를 통해 또는 `System.Net.Http.HttpClient`를 사용할 경우 `HttpClientXRayTracingHandler` 핸들러를 사용하여 발신 HTTP 직접 호출을 추적합니다. ------ #### [ With OpenTelemetry SDK ] 다음 코드 예제의 경우 다음 종속성이 필요합니다. ``` dotnet add package OpenTelemetry.Instrumentation.Http ``` `System.Net.Http.HttpClient` 및 `System.Net.HttpWebRequest`를 계측하려면 Global TracerProvider가 설정된 OpenTelemetry SDK 구성을 업데이트합니다. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddHttpClientInstrumentation() ... ``` ------ ## 다른 라이브러리에 대한 계측 지원 .NET Instrumentation 라이브러리용 OpenTelemetry 레지스트리를 검색하고 필터링하여 OpenTelemetry가 라이브러리에 대한 계측을 지원하는지 확인할 수 있습니다. [레지스트리](https://opentelemetry.io/ecosystem/registry/)를 참조하여 검색을 시작합니다. ## Lambda 계측 ------ #### [ With X-Ray SDK ] Lambda와 함께 X-Ray SDK를 사용하려면 다음 절차가 필요했습니다. 1. Lambda 함수에서 *추적 활성화* 1. Lambda 서비스는 핸들러의 간접 호출을 나타내는 세그먼트를 생성합니다. 1. X-Ray SDK를 사용하여 하위 세그먼트 또는 계측 라이브러리 생성 ------ #### [ With OpenTelemetry-based solutions ] AWS 벤딩된 Lambda 계층으로 Lambda를 자동으로 계측할 수 있습니다. 두 가지 해결 방법이 있습니다. + (권장) [AWS OpenTelemetry용 Lambda 계층](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) + 성능 향상을 위해 `OpenTelemetry Manual Instrumentation`을 사용하여 Lambda 함수에 대한 OpenTelemetry 추적을 생성하는 것이 좋습니다. ------ ** AWS Lambda용 OpenTelemetry 수동 계측** 다음은 Lambda 함수 코드(계측 제외) 예제입니다. ``` using System; using System.Text; using System.Threading.Tasks; using Amazon.Lambda.Core; using Amazon.S3; using Amazon.S3.Model; // Assembly attribute to enable Lambda function logging [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))] namespace ExampleLambda; public class ListBucketsHandler { private static readonly AmazonS3Client s3Client = new(); // new Lambda function handler passed in public async Task HandleRequest(object input, ILambdaContext context) { try { var DoListBucketsAsyncResponse = await DoListBucketsAsync(); context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}"); context.Logger.LogInformation($"Successfully called ListBucketsAsync"); return "Success!"; } catch (Exception ex) { context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}"); throw; } } private async Task DoListBucketsAsync() { try { var putRequest = new ListBucketsRequest { }; var response = await s3Client.ListBucketsAsync(putRequest); return response; } catch (AmazonS3Exception ex) { throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex); } } } ``` Lambda 핸들러와 Amazon S3 클라이언트를 수동으로 계측하려면 다음을 수행합니다. 1. TracerProvider 인스턴스화 - TracerProvider는 `XrayUdpSpanExporter`, ParentBased Always On Sampler 및 `service.name`이 Lambda 함수 이름으로 설정된 `Resource`로 구성하는 것이 좋습니다. 1. 를 호출하여에 SDK 클라이언트 계측을 `AddAWSInstrumentation()` 추가하여 OpenTemetry AWS AWS SDK 계측으로 Amazon S3 클라이언트 계측 `TracerProvider` 1. 원래 Lambda 함수와 동일한 서명으로 래퍼 함수를 생성합니다. `AWSLambdaWrapper.Trace()` API를 직접적으로 호출하고 원래 Lambda 함수인 `TracerProvider`와 해당 입력을 파라미터로 전달합니다. 래퍼 함수를 Lambda 핸들러 입력으로 설정합니다. 다음 코드 예제의 경우 다음 종속성이 필요합니다. ``` dotnet add package OpenTelemetry.Instrumentation.AWSLambda dotnet add package OpenTelemetry.Instrumentation.AWS dotnet add package OpenTelemetry.Resources.AWS dotnet add package AWS.Distro.OpenTelemetry.Exporter.Xray.Udp ``` 다음 코드는 필요한 변경 후 Lambda 함수를 보여줍니다. 추가 사용자 지정 스팬을 생성하여 자동으로 제공되는 스팬을 보완할 수 있습니다. ``` using Amazon.Lambda.Core; using Amazon.S3; using Amazon.S3.Model; using OpenTelemetry; using OpenTelemetry.Instrumentation.AWSLambda; using OpenTelemetry.Trace; using AWS.Distro.OpenTelemetry.Exporter.Xray.Udp; using OpenTelemetry.Resources; // Assembly attribute to enable Lambda function logging [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))] namespace ExampleLambda; public class ListBucketsHandler { private static readonly AmazonS3Client s3Client = new(); TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder() .AddAWSLambdaConfigurations() .AddProcessor( new SimpleActivityExportProcessor( // AWS_LAMBDA_FUNCTION_NAME Environment Variable will be defined in AWS Lambda Environment new XrayUdpExporter(ResourceBuilder.CreateDefault().AddService(Environment.GetEnvironmentVariable("AWS_LAMBDA_FUNCTION_NAME")).Build()) ) ) .AddAWSInstrumentation() .SetSampler(new ParentBasedSampler(new AlwaysOnSampler())) .Build(); // new Lambda function handler passed in public async Task HandleRequest(object input, ILambdaContext context) => await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context); public async Task OriginalHandleRequest(object input, ILambdaContext context) { try { var DoListBucketsAsyncResponse = await DoListBucketsAsync(); context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}"); context.Logger.LogInformation($"Successfully called ListBucketsAsync"); return "Success!"; } catch (Exception ex) { context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}"); throw; } } private async Task DoListBucketsAsync() { try { var putRequest = new ListBucketsRequest { }; var response = await s3Client.ListBucketsAsync(putRequest); return response; } catch (AmazonS3Exception ex) { throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex); } } } ``` 이 Lambda를 간접적으로 호출하면 CloudWatch 콘솔의 추적 맵에 다음 추적이 표시됩니다. ![\[.Net용 CloudWatch 콘솔의 추적 맵\]](http://docs.aws.amazon.com/ko_kr/xray/latest/devguide/images/deprecation_dotnet.png)