OpenTelemetry .NET으로 마이그레이션 - AWS X-Ray
제로 코드 자동 계측 솔루션SDK를 사용한 수동 계측 솔루션추적 데이터 수동 생성수신 요청 추적(ASP.NET 및 ASP.NET 코어 계측)AWS SDK 계측발신 HTTP 호출 구성다른 라이브러리에 대한 계측 지원Lambda 계측

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

OpenTelemetry .NET으로 마이그레이션

.NET 애플리케이션에서 X-Ray 추적을 사용하는 경우 수동 작업이 포함된 X-Ray .NET SDK가 계측에 사용됩니다.

이 섹션에서는 X-Ray 수동 계측 솔루션에서 .NET용 OpenTelemetry 수동 계측 솔루션으로 마이그레이션하기 위한 SDK를 사용한 수동 계측 솔루션 섹션의 코드 예제를 제공합니다. 또는 제로 코드 자동 계측 솔루션 섹션에서 애플리케이션 소스 코드를 수정할 필요 없이 X-Ray 수동 계측에서 OpenTelemetry 자동 계측 솔루션으로 마이그레이션하여 .NET 애플리케이션을 계측할 수 있습니다.

제로 코드 자동 계측 솔루션

OpenTelemetry는 제로 코드 자동 계측 솔루션을 제공합니다. 이러한 솔루션은 애플리케이션 코드를 변경할 필요 없이 요청을 추적합니다.

OpenTelemetry 기반 자동 계측 옵션

  1. .NET용 AWS Distro for OpenTelemetry(ADOT) 자동 계측 사용 - .NET 애플리케이션을 자동으로 계측하려면 AWS Distro for OpenTelemetry .NET Auto-Instrumentation을 사용하여 추적 및 지표를 참조하세요.

    (선택 사항) ADOT .NET 자동 계측 AWS 을 사용하여에서 애플리케이션을 자동으로 계측할 때 CloudWatch Application Signals를 활성화하여 다음을 수행합니다.

    • 현재 애플리케이션 상태 모니터링

    • 비즈니스 목표를 기준으로 장기 애플리케이션 성능 추적

    • 애플리케이션, 서비스 및 종속성에 대한 통합된 애플리케이션 중심 보기 가져오기

    • 애플리케이션 상태 모니터링 및 분류

    자세한 내용은 Application Signals를 참조하세요.

  2. OpenTelemetry .Net 제로 코드 자동 계측 사용 - OpenTelemetry .Net을 사용하여 자동으로 계측하려면 AWS Distro for OpenTelemetry .NET Auto-Instrumentation을 사용하여 추적 및 지표를 참조하세요.

SDK를 사용한 수동 계측 솔루션

Tracing configuration with X-Ray SDK

.NET 웹 애플리케이션의 경우 X-Ray SDK는 Web.config 파일의 appSettings 섹션에 구성됩니다.

Web.config 예제


<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin"/>
  </appSettings>
</configuration>

.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 코어 계측). OpenTelemetry를 다른 프레임워크와 함께 사용하려면 레지스트리에서 지원되는 프레임워크에 대한 추가 라이브러리를 참조하세요.

다음 구성 요소를 구성하는 것이 좋습니다.


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 애플리케이션에서 제공하는 요청을 계측하려면 global.asax 파일의 Init 메서드RegisterXRay에서를 호출하는 방법에 https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html 대한 자세한 내용은 섹션을 참조하세요.


AWSXRayASPNET.RegisterXRay(this, "MyApp");

ASP.NET 코어 애플리케이션에서 제공하는 요청을 계측하기 위해 UseXRay 메서드는 Startup 클래스의 Configure 메서드에 있는 다른 미들웨어보다 먼저 호출됩니다.


app.UseXRay("MyApp");
With OpenTelemetry SDK

또한 OpenTelemetry는 ASP.NET 및 ASP.NET 코어에 대한 수신 웹 요청에 대한 추적을 수집하는 계측 라이브러리를 제공합니다. 다음 섹션에서는 추적기 공급자를 생성할 때 ASP.NET 또는 ASP.NET 코어 계측을 추가하는 방법을 포함하여 OpenTelemetry 구성에 이러한 라이브러리 계측을 추가하고 활성화하는 데 필요한 단계를 나열합니다.

OpenTelemetry.Instrumentation.AspNet,을 활성화하는 방법에 대한 자세한 내용은 OpenTelemetry.Instrumentation.AspNet을 활성화하는 단계 및 OpenTelemetry.Instrumentation.AspNetCore,를 활성화하는 방법에 대한 자세한 내용은 OpenTelemetry.Instrumentation.AspNetCore를 활성화하는 단계를 참조하세요.

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<IAmazonDynamoDB>(); // 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는 확장 메서드를 통해 GetResponseTraced() 또는를 사용할 GetAsyncResponseTraced() 때 System.Net.HttpWebRequest또는를 사용할 때 HttpClientXRayTracingHandler 핸들러를 사용하여 발신 HTTP 호출을 추적합니다System.Net.Http.HttpClient.

With OpenTelemetry SDK

다음 코드 예제의 경우 다음 종속성이 필요합니다.


dotnet add package OpenTelemetry.Instrumentation.Http

System.Net.Http.HttpClient 및를 계측하려면 Global TracerProvider가 설정된 OpenTelemetry SDK 구성을 System.Net.HttpWebRequest업데이트합니다.


builder.Services.AddOpenTelemetry()
    ...
    .WithTracing(tracing => tracing
        .AddHttpClientInstrumentation()
        ...

다른 라이브러리에 대한 계측 지원

.NET 계측 라이브러리용 OpenTelemetry 레지스트리를 검색하고 필터링하여 OpenTelemetry가 라이브러리에 대한 계측을 지원하는지 확인할 수 있습니다. 검색을 시작하려면 레지스트리를 참조하세요.

Lambda 계측

With X-Ray SDK

Lambda와 함께 X-Ray SDK를 사용하려면 다음 절차가 필요했습니다.

  1. Lambda 함수에서 활성 추적 활성화

  2. Lambda 서비스는 핸들러의 호출을 나타내는 세그먼트를 생성합니다.

  3. X-Ray SDK를 사용하여 하위 세그먼트 또는 계측 라이브러리 생성

With OpenTelemetry-based solutions

AWS 벤딩된 Lambda 계층으로 Lambda를 자동으로 계측할 수 있습니다. 두 가지 해결 방법이 있습니다.

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<string> 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<ListBucketsResponse> 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 및 Lambda 함수 이름으로 service.name 설정된 Resource 로 구성하는 것이 좋습니다.

  2. 를 호출하여에 SDK 클라이언트 계측AddAWSInstrumentation()을 추가하여 OpenTemetry AWS AWS SDK 계측으로 Amazon S3 클라이언트 계측 TracerProvider

  3. 원래 Lambda 함수와 동일한 서명으로 래퍼 함수를 생성합니다. AWSLambdaWrapper.Trace() API를 호출하고 TracerProvider, 원래 Lambda 함수 및 해당 입력을 파라미터로 전달합니다. 래퍼 함수를 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<string> HandleRequest(object input, ILambdaContext context)
    => await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context);

    public async Task<string> 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<ListBucketsResponse> 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 콘솔의 트레이스 맵