Systèmes pris en charge

La vigie applicative est prise en charge et testé sur Amazon EKS, Kubernetes natif, Amazon ECS et Amazon EC2. Les instructions pour activer la vigie applicative sur Amazon EC2 devraient fonctionner sur toute plateforme prenant en charge l’agent CloudWatch et AWS Distro for OpenTelemetry.

Java compatibility

La vigie applicative prend en charge les applications Java, ainsi que les mêmes bibliothèques et cadres Java qu’AWS Distro for OpenTelemetry. Pour plus d’informations, veuillez consulter la rubrique Bibliothèques, frameworks, serveurs d’applications et JVM pris en charge.

Compatibilité .NET

La vigie applicative prend en charge les mêmes bibliothèques et cadres .NET qu’AWS Distro for OpenTelemetry. Pour plus d’informations, consultez la section Instrumentations prises en charge.

La vigie applicative prend en charge les applications .NET qui s’exécutent sur des processeurs x86-64 ou ARM64, ainsi que Linux x64, Linux ARM64 et Microsoft Windows Server 2022 x64.

Compatibilité PHP

La vigie applicative prend en charge les applications PHP avec l’instrumentation OpenTelemetry sans code. Il n’existe pas de kit SDK AWS Distro for Open Telemetry (ADOT) disponible à cette fin. Il est recommandé d’utiliser le kit SDK d’instrumentation OpenTelemetry standard avec la fonctionnalité Recherche de transactions activée. Pour commencer à utiliser l’instrumentation sans code en PHP, veuillez suivre les étapes décrites dans la documentation sur l’instrumentation PHP OpenTelemetry, Instrumentation PHP sans code. L’instrumentation automatique est disponible pour un certain nombre de bibliothèques PHP couramment utilisées. Pour plus d’informations, consultez le registre OpenTelemetry.

Compatibilité Ruby

La vigie applicative prend en charge les applications Ruby avec l’instrumentation OpenTelemetry sans code. Il n’existe pas de kit SDK AWS Distro for Open Telemetry (ADOT) disponible à cette fin. Il est recommandé d’utiliser le kit SDK d’instrumentation OpenTelemetry standard avec la fonctionnalité Recherche de transactions activée. Pour commencer à utiliser l’instrumentation sans code dans Ruby, veuillez suivre les étapes décrites dans la documentation sur l’instrumentation Ruby OpenTelemetry, Instrumentation Ruby sans code. Pour obtenir la liste des bibliothèques d’instrumentation publiées, consultez Registre.

Compatibilité Python

La vigie applicative prend en charge les mêmes bibliothèques et cadres qu’AWS Distro for OpenTelemetry. Pour plus d’informations, consultez Packages pris en charge sur opentelemetry-python-contrib.

Avant d’activer la vigie applicative pour vos applications Python, tenez compte des considérations suivantes.

Compatibilité Node.js

La vigie applicative prend en charge les mêmes bibliothèques et cadres Node.js qu’AWS Distro for OpenTelemetry. Pour plus d’informations, consultez la section Instrumentations prises en charge.

Limitations connues concernant Node.js avec ESM

AWS Distro for OpenTelemetry Node.js prend en charge deux systèmes de modules : ECMAScript Modules (ESM) et CommonJS (CJS). Pour activer la vigie applicative, il est recommandé d’utiliser le format de module CJS, car la prise en charge d’ESM par OpenTelemetry JavaScript est expérimentale et en cours de développement. Pour plus d’informations, consultez la page ECMAScript Modules vs. CommonJS sur GitHub.

Pour déterminer si votre application utilise CJS et non ESM, assurez-vous qu’elle ne remplit pas les conditions requises pour activer ESM. Pour plus d’informations sur ces conditions, consultez Activation dans la documentation Node.js.

AWS Distro for OpenTelemetry Node.js offre une prise en charge limitée d’ESM, basée sur la prise en charge expérimentale d’ESM par OpenTelemetry JavaScript. Cela signifie que :

Pour activer la vigie applicative avec le format de module ESM Node.js, nous proposons différentes configurations pour différentes plateformes :

Compatibilité GoLang

La vigie applicative prend en charge les applications GoLang avec l’instrumentation OpenTelemetry sans code. Il n’existe pas de kit SDK AWS Distro for Open Telemetry (ADOT) disponible à cette fin. Il est recommandé d’utiliser le kit SDK d’instrumentation OpenTelemetry standard avec la fonctionnalité Recherche de transactions activée. Pour commencer à utiliser l’instrumentation sans code dans GoLang, veuillez suivre les étapes décrites dans la documentation sur l’instrumentation GoLang OpenTelemetry, Mise en route avec l’instrumentation automatique Go OpenTelemetry.

Considérations relatives aux implémentations Instrumentation GoLang

Découvrez les détails d’implémentation importants pour l’utilisation de l’instrumentation GoLang. Ce guide explique comment implémenter la propagation explicite du contexte dans les applications GoLang et configurer la vigie applicative. Une implémentation correcte de l’instrumentation GoLang vous aide à suivre et à analyser efficacement les performances de votre application.

Instrumentation du kit SDK AWS

La bibliothèque d’instrumentation automatique Golang ne prend pas en charge l’instrumentation du kit SDK AWS telle quelle. Vous devez utiliser l’instrumentation de la bibliothèque otelaws avec l’agent d’instrumentation automatique :

L’exemple suivant génère des portées pour les appels AWS et s’intègre à l’instrumentation automatique.

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
}

Pour plus d’informations sur la configuration de l’exécutable d’instrumentation automatique, consultez Méthodes de configuration.

Instrumentation des appels HTTP

Les appels HTTP peuvent diviser les traces lorsque le contexte n’est pas transmis entre les demandes. Les clients HTTP doivent utiliser NewRequestWithContext() au lieu de NewRequest() pour s’assurer que le service en aval utilise le même contexte. Lorsque les deux services disposent d’agents d’instrumentation, les portées se connectent avec le même ID de trace pour offrir une visibilité de bout en bout.

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

Instrumentation des appels SQL

Les portées SQL peuvent être déconnectées de leur portée parent, ce qui entraîne l’interprétation des appels clients comme des portées serveur. Cela se produit lorsque les appels SQL ne reçoivent pas le contexte de leurs gestionnaires en amont. Les appels SQL standard tels que Query et Exec utilisent context.Background() par défaut, et non le contexte de l’appelant en amont. Remplacez les appels SQL standard par leurs équivalents sensibles au contexte :

Ces méthodes transmettent le contexte de la demande en amont aux appels de base de données, ce qui permet de maintenir une continuité de trace appropriée.

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
}

Détecteurs de ressources

L’instrumentation automatique Go ne prend actuellement pas en charge la configuration des détecteurs de ressources lors de l’exécution. La communauté OpenTelemetry travaille sur une fonctionnalité permettant de configurer les détecteurs de ressources à l’aide de variables d’environnement. Cette fonctionnalité sera disponible dans une prochaine mise à jour. En attendant, vous pouvez utiliser l’agent CloudWatch avec l’instrumentation automatique pour générer automatiquement des attributs de ressources hôte.

Matrice de prise en charge des versions d’exécution

Problèmes connus

La collecte de métriques d’exécution dans la version 1.32.5 du kit SDK Java est connue pour ne pas fonctionner avec les applications utilisant JBoss Wildfly. Ce problème s’étend au module complémentaire EKS d’observabilité Amazon CloudWatch, affectant les versions 2.3.0-eksbuild.1 à 2.6.0-eksbuild.1. Le problème est résolu dans la version v1.32.6 du kit SDK Java et dans la version v3.0.0-eksbuild.1 du module complémentaire EKS d’observabilité Amazon CloudWatch.

Si vous êtes concerné, mettez à niveau la version du kit SDK Java ou désactivez la collecte des métriques d’exécution en ajoutant la variable d’environnement OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false à votre application.