サポートされているシステム

Application Signals は、Amazon EKS、ネイティブ Kubernetes、Amazon ECS、および Amazon EC2 でサポートされ、テストされています。Amazon EC2 で Application Signals を有効にする手順は、CloudWatch エージェントと AWS Distro for OpenTelemetry をサポートするすべてのプラットフォームに適用されます。

Java の互換性

Application Signals は Java アプリケーションをサポートしていますが、AWS Distro for OpenTelemetry と同じ Java ライブラリとフレームワークもサポートしています。詳細については、「Supported libraries, frameworks, application servers, and JVMs」を参照してください。

.NET の互換性

Application Signals は、AWS Distro for OpenTelemetry と同じ .NET ライブラリとフレームワークをサポートしています。詳細については、「Supported instrumentations」を参照してください。

Application Signals は、x86-64 CPU または ARM64 CPU で実行されている .NET アプリケーションに加え、Linux x64、Linux ARM64、および Microsoft Windows Server 2022 x64 をサポートしています。

PHP の互換性

Application Signals は、OpenTelemetry ゼロコード計測による PHP アプリケーションをサポートしています。この目的で使用できる AWS Distro for Open Telemetry (ADOT) SDK はありません。トランザクション検索を有効にした標準の OpenTelemetry Instrumentation SDK を使用する必要があります。PHP でゼロコード計測の使用を開始するには、OpenTelemetry PHP 計測ドキュメントの「PHP zero-code instrumentation」の手順に従ってください。自動計測は、一般的に使用される多くの PHP ライブラリで使用できます。詳細については、「OpenTelemetry registry」を参照してください。

Ruby の互換性

Application Signals は、OpenTelemetry ゼロコード計測を使用した Ruby アプリケーションをサポートしています。この目的で使用できる AWS Distro for Open Telemetry (ADOT) SDK はありません。トランザクション検索を有効にした標準の OpenTelemetry Instrumentation SDK を使用する必要があります。Ruby でゼロコード計測の使用を開始するには、OpenTelemetry Ruby Instrumentation ドキュメントの「計装」の手順に従ってください。リリースされた計測ライブラリのリストについては、「Registry」を参照してください。

Python の互換性

Application Signals は、AWS Distro for OpenTelemetry と同じライブラリとフレームワークをサポートしています。詳細については、opentelemetry-python-contrib の「サポート対象パッケージ」を参照してください。

Python アプリケーションの Application Signals を有効にする前に、以下の考慮事項に注意してください。

Node.js の互換性

Application Signals は、AWS Distro for OpenTelemetry と同じ Node.js ライブラリとフレームワークをサポートしています。詳細については、「Supported instrumentations」を参照してください。

EMS を使用する ENode.js における既知の制限事項

AWS Distro for Opentelemetry Node.js は、ECMAScript Modules (ESM) と CommonJS (CJS) の 2 つのモジュールシステムをサポートしています。OpenTelemetry JavaScript による ESM のサポートは実験的であり、現在開発中であるため、Application Signals を有効にするには、CJS モジュール形式を使用することをお勧めします。詳細については、GitHub の「ECMAScript Modules vs. CommonJS」を参照してください。

お使いのアプリケーションで ESM ではなく CJS を使用しているかどうかは、アプリケーションが ESM を有効にするための条件を満たしていないことを確認することで判断できます。これらのコマンドの詳細については、Node.js ドキュメントの「Enabling」を参照してください。

AWS Distro for Opentelemetry Node.js は、OpenTelemetry JavaScript の ESM の実験サポートに基づいて、ESM の限定的なサポートを提供します。これは以下を意味します。

Node.js ESM モジュール形式で Application Signals を有効にするにあたって、プラットフォームごとに異なるセットアップが提供されています。

GoLang の互換性

Application Signals は、OpenTelemetry ゼロコード計測を備えた GoLang アプリケーションをサポートしています。この目的で使用できる AWS Distro for Open Telemetry (ADOT) SDK はありません。トランザクション検索を有効にした標準の OpenTelemetry Instrumentation SDK を使用する必要があります。GoLang でゼロコード計測の使用を開始するには、OpenTelemetry GoLang 計測ドキュメントの「Getting Started with OpenTelemetry Go Automatic Instrumentation」の手順に従ってください。

実装に関する考慮事項 GoLang 計測

GoLang 計測を使用するための実装に関する重要な詳細について説明します。このガイダンスでは、GoLang アプリケーションで明示的なコンテキスト伝達を実装し、Application Signals を設定する方法について説明します。GoLang 計測を適切に実装することで、アプリケーションのパフォーマンスを効果的に追跡および分析できます。

AWS SDK の計測

Golang 自動計測ライブラリは、AWS SDK 計測を標準ではサポートしていません。自動計測エージェントと共に otelaws ライブラリ計測を使用する必要があります。

以下の例では、AWS 呼び出しのスパンを生成し、自動計測と統合します。

func handleRequest(ctx context.Context) error {
    cfg, err := config.LoadDefaultConfig(ctx)
    if err != nil {
        return err
    }
    
    // Add OpenTelemetry instrumentation middleware to the AWS config
    otelaws.AppendMiddlewares(&cfg.APIOptions)
    
    // Create S3 client with the instrumented config
    s3Client := s3.NewFromConfig(cfg)
    
    // Now any operations with this client will be traced
    // with the context from the upstream call
    _, err = s3Client.ListBuckets(ctx, &s3.ListBucketsInput{})
    return err
}

自動計測実行可能ファイルの設定については、「Configuration methods」を参照してください。

HTTP 呼び出しの計測

HTTP 呼び出しは、リクエスト間でコンテキストが渡されない場合にトレースを分割できます。HTTP クライアントは NewRequest() の代わりに NewRequestWithContext() を使用して、ダウンストリームサービスでも同じコンテキストが使用されるようにする必要があります。両方のサービスに計測エージェントがある場合、スパンは同じトレース ID で接続し、エンドツーエンドの可視性を提供します。

func makeDownstreamCall(ctx context.Context, url string) ([]byte, error) {
    client := &http.Client{}
    
    // Create request with context from the upstream call
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }
    
    // Execute the request
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
}

SQL 呼び出しの計測

SQL スパンが親スパンから切断され、クライアント呼び出しがサーバースパンとして推測される可能性があります。これは、SQL 呼び出しがアップストリームハンドラーからコンテキストを受信しない場合に発生します。Query や Exec などの標準 SQL 呼び出しは、アップストリーム呼び出し元のコンテキストではなく、デフォルトで context.Background() を使用します。標準 SQL 呼び出しをコンテキスト対応の同等のものに置き換えます。

これらの方法は、アップストリームリクエストコンテキストを DB 呼び出しに渡し、適切なトレース継続性を維持します。

func queryDatabase(ctx context.Context, db *sql.DB, userID string) (*sql.Rows, error) {
    // This breaks the trace context
    // row := db.Query("SELECT name FROM users WHERE id = $1", userID)
    
    // This passes the context from the upstream call for trace continuity
    rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE id = $1", userID)
    
    return rows, error
}

リソースディテクター

Go 自動計測は現在、ランタイム時のリソースディテクターの設定をサポートしていません。OpenTelemetry コミュニティは、環境変数を使用してリソースディテクターを設定する機能に取り組んでいます。この機能は今後の更新で提供される予定です。その間、自動計測で CloudWatch エージェントを使用して、ホストリソース属性を自動的に生成できます。

ランタイムバージョンのサポートマトリックス

既知の問題

Java SDK リリース v1.32.5 のランタイムメトリクスコレクションは、JBoss Wildfly を使用するアプリケーションで動作しないことが知られています。この問題は Amazon CloudWatch Observability EKS アドオンに及び、2.3.0-eksbuild.1 から 2.6.0-eksbuild.1 までのバージョンに影響します。この問題は、Java SDK リリース v1.32.6 と Amazon CloudWatch Observability EKS アドオンバージョン v3.0.0-eksbuild.1 で修正されています。

影響を受けた場合、Java SDK のバージョンをアップグレードするか、アプリケーションに OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false 環境変数を追加してランタイムメトリクス収集を無効にします。