Unterstützte Systeme

Application Signals wird in Amazon EKS, nativem Kubernetes, Amazon ECS und Amazon EC2 unterstützt und getestet. Die Anweisungen zur Aktivierung von Application Signals in Amazon EC2 sollten auf jeder Plattform funktionieren, die den CloudWatch-Agenten und die AWS Distro für OpenTelemetry unterstützt.

Java-Kompatibilität

Application Signals unterstützt Java-Anwendungen und dieselben Java-Bibliotheken und -Frameworks wie die AWS Distro für OpenTelemetry. Weitere Informationen finden Sie unter Unterstützte Bibliotheken, Frameworks, Anwendungsserver und JVMs.

.NET-Kompatibilität

Application Signals unterstützt dieselben .NET-Bibliotheken und -Frameworks wie die AWS Distro für OpenTelemetry. Weitere Informationen finden Sie unter Unterstützte Instrumentierungen.

Application Signals unterstützt .NET-Anwendungen, die auf x86-64- oder ARM64-CPUs ausgeführt werden, sowie Linux x64, Linux ARM64 und Microsoft Windows Server 2022 x64.

PHP-Kompatibilität

Application Signals unterstützt PHP-Anwendungen mit OpenTelemetry-Zero-Code-Instrumentierung. Für diesen Zweck ist kein AWS Distro für Open Telemetry (ADOT) SDK verfügbar. Sie sollten das standardmäßige OpenTelemetry-Instrumentierungs-SDK mit aktivierter Transaktionssuche verwenden. Zur Nutzung der Zero-Code-Instrumentierung in PHP folgen Sie diesen Schritten aus der Dokumentation zur OpenTelemetry-PHP-Instrumentierung, Zero-Code-Instrumentierung in PHP. Die automatische Instrumentierung ist für eine Reihe häufig verwendeter PHP-Bibliotheken verfügbar. Weitere Informationen finden Sie unter OpenTelemetry-Registry.

Ruby-Kompatibilität

Application Signals unterstützt Ruby-Anwendungen mit OpenTelemetry-Zero-Code-Instrumentierung. Für diesen Zweck ist kein AWS Distro für Open Telemetry (ADOT) SDK verfügbar. Sie sollten das standardmäßige OpenTelemetry-Instrumentierungs-SDK mit aktivierter Transaktionssuche verwenden. Zur Nutzung der Zero-Code-Instrumentierung in Ruby folgen Sie diesen Schritten aus der Dokumentation zur OpenTelemetry-PHP-Instrumentierung, Zero-Code-Instrumentierung in Ruby. Eine Liste der veröffentlichten Instrumentierungsbibliotheken finden Sie unter Registry.

Python-Kompatibilität

Application Signals unterstützt dieselben Bibliotheken und Frameworks wie die AWS Distro für OpenTelemetry. Weitere Informationen finden Sie in Unterstützte Pakete unter opentelemetry-python-contrib.

Bevor Sie Application Signals für Ihre Python-Anwendungen aktivieren, sollten Sie die folgenden Punkte beachten.

Node.js-Kompatibilität

Application Signals unterstützt dieselben Node.js-Bibliotheken und -Frameworks wie die AWS Distro für OpenTelemetry. Weitere Informationen finden Sie unter Unterstützte Instrumentierungen.

Bekannte Einschränkungen von Node.js mit ESM

Die AWS Distro für OpenTelemetry Node.js unterstützt zwei Modulsysteme: ECMAScript-Module (ESM) und CommonJS (CJS). Um Application Signals zu aktivieren, empfehlen wir, das Modulformat CJS zu verwenden, da die Unterstützung von ESM durch OpenTelemetry JavaScript experimentell und noch in Arbeit ist. Weitere Informationen finden Sie unter ECMAScript Modules vs. CommonJS auf GitHub.

Um festzustellen, ob Ihre Anwendung CJS und nicht ESM verwendet, stellen Sie sicher, dass Ihre Anwendung die Bedingungen für die Aktivierung von ESM nicht erfüllt. Weitere Informationen zu diesen Bedingungen finden Sie in der Node.js-Dokumentation unter Aktivieren.

Die AWS Distro für OpenTelemetry Node.js bietet begrenzte Unterstützung für ESM, basierend auf der experimentellen Unterstützung von OpenTelemetry JavaScript für ESM. Das bedeutet:

Um Application Signals mit dem Node.js-ESM-Modulformat zu aktivieren, bieten wir verschiedene Setups für verschiedene Plattformen:

GoLang-Kompatibilität

Application Signals unterstützt GoLang-Anwendungen mit OpenTelemetry-Zero-Code-Instrumentierung. Für diesen Zweck ist kein AWS Distro für Open Telemetry (ADOT) SDK verfügbar. Sie sollten das standardmäßige OpenTelemetry-Instrumentierungs-SDK mit aktivierter Transaktionssuche verwenden. Zur Nutzung der Zero-Code-Instrumentierung in GoLang folgen Sie diesen Schritten aus der Dokumentation zur OpenTelemetry-GoLang-Instrumentierung Erste Schritte mit der automatischen OpenTelemetry-Go-Instrumentierung.

Überlegungen zur Implementierung – GoLang-Instrumentierung

Informationen zu wichtigen Implementierungsdetails für die Verwendung der GoLang-Instrumentierung In dieser Anleitung wird erklärt, wie Sie die explizite Kontextverbreitung in GoLang-Anwendungen implementieren und Application Signals einrichten. Die korrekte Implementierung der GoLang-Instrumentierung hilft Ihnen, die Leistung Ihrer Anwendung effektiv zu verfolgen und zu analysieren.

Instrumentieren des AWS-SDK

Die Golang-Bibliothek für die automatische Instrumentierung unterstützt standardmäßig keine AWS-SDK-Instrumentierung. Sie müssen die otelaws-Bibliotheksinstrumentierung zusammen mit dem Agenten für die automatische Instrumentierung verwenden:

Das folgende Beispiel generiert Spans für AWS-Anrufe und integriert die automatische Instrumentierung.

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
}

Informationen zum Konfigurieren der ausführbaren Datei für die automatische Instrumentierung finden Sie unter Konfigurationsmethoden.

Instrumentieren von HTTP-Aufrufen

HTTP-Aufrufe können Traces aufteilen, wenn zwischen Anfragen kein Kontext übergeben wird – HTTP-Clients müssen NewRequestWithContext() statt NewRequest() verwenden, um sicherzustellen, dass der nachgelagerte Service denselben Kontext verwendet. Wenn beide Services Instrumentierungsagenten haben, stellen die Spans eine Verbindung mit derselben Trace-ID her, um durchgängige Sichtbarkeit zu gewährleisten.

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()
}

Instrumentieren von SQL-Aufrufen

SQL-Spans können von ihrem übergeordneten Span getrennt werden, wodurch Client-Aufrufe als Server-Spans abgeleitet werden. Dies tritt auf, wenn SQL-Aufrufe von ihren vorgelagerten Handlern keinen Kontext erhalten. Standard-SQL-Aufrufe wie Query und Exec verwenden standardmäßig context.Background() und nicht den Kontext des vorgelagerten Aufrufers. Ersetzen Sie Standard-SQL-Aufrufe durch ihre kontextbezogenen Entsprechungen:

Diese Methoden übergeben den vorgelagerten Anforderungskontext an die DB-Aufrufe und sorgen so für eine korrekte Trace-Kontinuität.

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
}

Ressourcendetektoren

Die automatische Go-Instrumentierung unterstützt derzeit keine Konfiguration von Ressourcendetektoren zur Laufzeit. Die OpenTelemetry-Community arbeitet an einer Funktion zur Konfiguration von Ressourcendetektoren mithilfe von Umgebungsvariablen. Diese Funktion sollte in einem künftigen Update verfügbar sein. In der Zwischenzeit können Sie den CloudWatch-Agent mit automatischer Instrumentierung verwenden, um automatisch Host-Ressourcenattribute zu generieren.

Laufzeitversion – Unterstützungsmatrix

Bekannte Probleme

Die Erfassung von Laufzeit-Metriken in der Java-SDK-Version 1.32.5 funktioniert bekannterweise nicht mit Anwendungen, die JBoss Wildfly verwenden. Dieses Problem erstreckt sich auf das Add-On von Amazon CloudWatch Observability EKS und betrifft die Versionen 2.3.0-eksbuild.1 bis 2.6.0-eksbuild.1. Das Problem wurde in der Java-SDK-Version v1.32.6 und der Version v3.0.0-eksbuild.1 des Add-Ons von Amazon CloudWatch Observability EKS behoben.

Wenn Sie betroffen sind, aktualisieren Sie entweder die Java-SDK-Version oder deaktivieren Sie die Erfassung von Laufzeitmetriken, indem Sie Ihrer Anwendung die Umgebungsvariable OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false hinzufügen.