PREVIEW
OpenTelemetryfor.NETを搭載したAWSLambdaはまだ開発中です。
Javaについても同様のドキュメントがありますが、OpenTelemetry で AWS Lambda に Python、Go、JavaScript、Ruby、または PHP を使用している場合は、Java または .NET ドキュメントをセットアップの一般的なガイドとして使用できます。詳細については、 OpenTelemetry の AWS ディストリビューション を参照してください。
このガイドでは、 OpenTelemetry Lambda を使って、AWS のマネージド OpenTelemetry Lambda Layers を使って、.NET Lambda 関数をトレースする方法を説明します。OpenTelemetryは、多くの一般的なライブラリの自動インスツルメンテーションを含む、関数のインスツルメンテーションを簡単に行うことができます。
前提条件
このガイドでは、以下のものを想定しています。
- New Relic のアカウントです。まだお持ちでない方は、 無料で作成できます。.
- AWSのアカウントです。お持ちでない方は、 無料で作成できます。.
- .NET Lambda 関数。まだお持ちでない場合は、 今すぐ作成してください。
重要
AWS OTel .NET SDK for Lambda ではDisableAwsXRayContextExtraction
がtrue
に設定されているため、X-Ray を有効にする必要はなくなりました。 詳細については、 AWS OTel .NET SDK for Lambda Readme を参照してください。
レイヤーをインストールする
AWSは、 OpenTelemetry Lambda Collector を含むマネージドレイヤーを公開しています。
インストールするには
- 作成した関数を Lambda Console で開きます。
- [デザイナ]セクションの[レイヤー]で、[レイヤーの追加]を選択します。
- [ARNの指定]で、以下のリストから関数のアーキテクチャーのレイヤーARNの1つを貼り付けます。
{region}
をus-east-1
などのAWSリージョンに置き換えます。 - Choose Add.
AMD64 / X86_64:
arn:aws:lambda:{region}:901920570463:layer:aws-otel-collector-amd64-ver-0-90-1:1
ARM64:
arn:aws:lambda:\<region>:901920570463:layer:aws-otel-collector-arm64-ver-0-90-1:1
SAM および CloudFormation テンプレートの場合、関数のプロパティに以下を追加します。
yourFunctionHere:Type: AWS::Serverless::FunctionProperties:...Layers:# Use this if using x86_64 architecture- !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:901920570463:layer:aws-otel-collector-amd64-ver-0-90-1:1# Use this if using arm64 architecture- !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:901920570463:layer:aws-otel-collector-arm64-ver-0-90-1:1重要
AWSが公開している最新のARNを参照して、上記のレイヤーARNが最新であることを確認してください。
New Relic 環境変数を追加する
このレイヤーが収集した OpenTelemetry データを New Relic に送信するためには、レイヤーに同梱されている OpenTelemetry Lambda Collector を設定して、受信したテレメトリを New Relic OpenTelemetry Endpoint にエクスポートする必要があります。その前に、まずこのコレクターが依存するいくつかの環境変数を設定する必要があります。
New Relic の生成とコピー
New Relic アカウントから。
Lambda Console で作成した関数を開きます。
Configuration を選択し、次に Environment variables を選択します。
Environment variables の下で、 Edit を選択します。
環境変数の追加 を選択します。
キーの場合は
NEW_RELIC_LICENSE_KEY
に設定し、値を手順1で生成したライセンスキーの値に設定します。次に、[保存]を選択します。環境変数の追加 を再度選択します。
Keyの場合は
NEW_RELIC_OPENTELEMETRY_ENDPOINT
に設定し、 Valueを以下のオプションのいずれかに設定します(New Relicリージョンによって異なります)。次に、[保存]を選択します。環境変数の追加 を再度選択します。
キーの場合は
OTEL_SERVICE_NAME
に設定し、値を関数の名前に設定します。次に、[保存]を選択します。
otlp.nr-data.net:4317
:NewRelicアカウントが米国地域にある場合otlp.eu01.nr-data.net:4317
:NewRelicアカウントがEU地域にある場合SAM および CloudFormation テンプレートの場合、関数のプロパティに以下を追加します。
your-license-key-here
を自分のotlp.nr-data.net:4317
は、お使いのリージョンの New Relic OpenTelemetry エンドポイントを使用します。yourFunctionHere:Type: AWS::Serverless::FunctionProperties:...Environment:Variables:...NEW_RELIC_LICENSE_KEY: your-license-key-hereNEW_RELIC_OPENTELEMETRY_ENDPOINT: otlp.nr-data.net:4317OTEL_SERVICE_NAME: your-function-name-here重要
your-license-key-here
New Relic に置き換えますotlp.nr-data.net:4317
は、New Relic リージョンに適したエンドポイントを使用します (上記のリストを参照)。
コレクターを構成する
次に、OpenTelemetry Lambda Collectorのデフォルト構成を、テレメトリをNewRelicOpenTelemetryエンドポイントにエクスポートする構成でオーバーライドします。これを行うには、関数にcollector.yaml
構成ファイルを含める必要があります。
関数のルートディレクトリに、次の内容のcollector.yaml
ファイルを作成します。
receivers: otlp: protocols: grpc: http:
exporters: otlp: endpoint: ${NEW_RELIC_OPENTELEMETRY_ENDPOINT} headers: api-key: ${NEW_RELIC_LICENSE_KEY}
service: pipelines: traces: receivers: [otlp] exporters: [otlp] metrics: receivers: [otlp] exporters: [otlp] logs: receivers: [otlp] exporters: [otlp]
このcollector.yaml
ファイルを関数のzipパッケージのルートディレクトリにバンドルします。
*.csproj
設定の例は次のようになります。
<ItemGroup> <Content Include="collector.yaml"> <CopyToOutputDirectory>Always</CopyToOutputDirectory> </Content> </ItemGroup>
そして、機能を再展開する。
- 作成した関数を Lambda Console で開きます。
- Configuration を選択し、次に Environment variables を選択します。
- Environment variables の下で、 Edit を選択します。
- 環境変数の追加 を選択します。
- キーセット
OPENTELEMETRY_COLLECTOR_CONFIG_FILE
の場合、値を/var/task/collector.yaml
に設定します。 - そして、 Save を選択します。
SAMやCloudFormationのテンプレートの場合は、関数のプロパティにこれを追加します。
yourFunctionHere: Type: AWS::Serverless::Function Properties: ... Environment: Variables: ... OPENTELEMETRY_COLLECTOR_CONFIG_FILE: /var/task/collector.yaml
重要
これは、関数のルートディレクトリにcollector.yaml
をバンドルしていることを前提としています。別の場所にバンドルした場合は、 /var/task/collector.yaml
をcollector.yaml
へのパスに置き換えてください。
インストゥルメントがあなたの機能を評価した
まず、 AWS Lambda 用の OpenTelemetry SDKとOTLP エクスポータ パッケージを追加します。 OpenTelemetry.Insトゥルメンテーション.AWS や OpenTelemetry.Insトゥルメンテーション.Http などの OpenTelemetryインストゥルメンテーションパッケージをさらに追加して、関数の動作をさらに可視化することができます。
$dotnet add package OpenTelemetry.Instrumentation.AWSLambda$dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol$dotnet add package OpenTelemetry.Instrumentation.AWS$dotnet add package OpenTelemetry.Instrumentation.Http
関数の静的コンストラクターに、 TracerProvider
からのAddAWSLambdaConfigurations()
とAddOtlpExporter()
への呼び出しを追加します。
重要
TracerProvider
は Lambda コールド スタートごとに 1 回だけ初期化される必要があるため、関数のコンストラクターは静的である必要があります。
TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder() // add other instrumentations here .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true) .AddOtlpExporter() .Build();
重要
X-Ray を有効にしない場合は、必ずDisableAwsXRayContextExtraction
プロパティをtrue
に設定してください。 そうしないと、トレースはインストゥルメントされません。
元のLambdaハンドラー関数と同じシグネチャでラッパー関数を作成します。 AWSLambdaWrapper.Trace()
APIを呼び出し、元のLambda関数であるTracerProvider
とその入力をパラメーターとして渡します。
// new Lambda function handler passed inpublic string TracingFunctionHandler(JObject input, ILambdaContext context) => AWSLambdaWrapper.Trace(tracerProvider, OriginalFunctionHandler, input, context);
public string OriginalFunctionHandler(JObject input, ILambdaContext context) { return input?.ToString();}
元のハンドラーが非同期関数である場合は、 Trace()
の代わりにTraceAsync()
API を使用します。
public Task<APIGatewayProxyResponse> TracingFunctionHandler(APIGatewayProxyRequest request, ILambdaContext context) => AWSLambdaWrapper.TraceAsync(tracerProvider, OriginalFunctionHandler, request, context);
public async Task<APIGatewayProxyResponse> OriginalFunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context){ //your function here.}
例えば、基本的なAPI GatewayのLambda関数は次のようなものです。
using System;using Amazon.Lambda.APIGatewayEvents;using Amazon.Lambda.Core;using OpenTelemetry;using OpenTelemetry.Instrumentation.AWSLambda;using OpenTelemetry.Trace;
namespace Example{ public class Function { public static TracerProvider tracerProvider;
static Function() { tracerProvider = Sdk.CreateTracerProviderBuilder() .AddAWSLambdaConfigurations(options => options.DisableAwsXRayContextExtraction = true) .AddOtlpExporter() .Build();
// use AwsSdkSample::AwsSdkSample.Function::TracingFunctionHandler as input Lambda handler instead public APIGatewayProxyResponse TracingFunctionHandler(APIGatewayProxyRequest request, ILambdaContext context) { return AWSLambdaWrapper.Trace(tracerProvider, FunctionHandler, request, context); }
/// <summary> /// A simple function that takes a APIGatewayProxyRequest and returns a APIGatewayProxyResponse /// </summary> /// <param name="input"></param> /// <param name="context"></param> /// <returns></returns> public APIGatewayProxyResponse FunctionHandler(APIGatewayProxyRequest request, ILambdaContext context) { return new APIGatewayProxyResponse() { StatusCode = 200, Body = Environment.GetEnvironmentVariable("_X_AMZN_TRACE_ID") }; } } }}
次に、ラッパー関数をLambda関数のハンドラーとして設定します。上記のクラスの場合、ハンドラーはfunction::Example.Function::TracingFunctionHandler
になります。
AWS SDKのトレースを含めた動作例については、 このサンプルアプリ を参照してください。
上記は単なる基本的な例です。より高度なインストゥルメンテーションについては、OpenTelemetry .NET SDK ドキュメントを参照してください。
分散型トレーシング
場合によっては、この構成でNewRelic内に断片化された分散トレースが表示されることがあります。これは、トレースが開始されるか、ADOTコンテキスト外のサービス(マネージドAWSサービスなど)が関与する場合に発生します。そのサービスのスパンはOpenTelemetryではなくX線によって作成され、ADOTはそれらをNewRelicに転送しません。トレースは断片化されているように見えますが、Lambda関数内のパフォーマンスや、スパンがNewRelicに転送された他のサービスに関する完全な洞察を提供します。
詳細情報
詳細については、 New Relic OpenTelemetry クイックスタート をご覧ください。