Activation des applications sur Amazon EC2
Activez la vigie applicative CloudWatch sur Amazon EC2 en suivant les étapes de configuration personnalisées décrites dans cette section.
Pour les applications exécutées sur Amazon EC2, installez et configurez vous-même l’agent CloudWatch ainsi qu’AWS Distro for OpenTelemetry. Sur ces architectures activées avec une configuration personnalisée d’Application Signals, Application Signals ne découvre pas automatiquement les noms de vos services ni les hôtes ou clusters sur lesquels ils s’exécutent. Vous devez spécifier ces noms lors de la configuration personnalisée, et les noms que vous spécifiez sont ceux qui sont affichés sur les tableaux de bord d’Application Signals.
Les instructions de cette section concernent les applications Java, Python et .NET. Les étapes ont été testées sur des instances Amazon EC2, mais elles devraient également fonctionner sur d’autres architectures prenant en charge AWS Distro for OpenTelemetry.
Prérequis
Pour obtenir de l’assistance pour Application Signals, vous devez utiliser la version la plus récente de l’agent CloudWatch et de l’agent AWS Distro for OpenTelemetry.
Vous devez avoir installé l’AWS CLI sur l’instance. Nous recommandons l’AWS CLI version 2, mais la version 1 devrait également fonctionner. Pour plus d’informations sur l’installation d’AWS CLI, veuillez consulter la section Installation ou mise à jour de la version la plus récente d’AWS CLI.
Si vous utilisez déjà OpenTelemetry avec une application que vous avez l’intention d’activer pour Application Signals, veuillez consulter la rubrique Systèmes pris en charge avant d’activer Application Signals.
Étape 1 : activer Application Signals dans votre compte
Vous devez d’abord activer la vigie applicative dans votre compte. Si ce n’est pas déjà fait, consultez Activation de la vigie applicative dans votre compte.
Étape 2 : télécharger et démarrer l’agent CloudWatch
Pour installer l’agent CloudWatch dans le cadre de l’activation de la vigie applicative sur une instance Amazon EC2 ou un hôte sur site
Téléchargez la version la plus récente de l’agent CloudWatch sur l’instance. Si l’agent CloudWatch est déjà installé sur l’instance, il se peut que vous deviez le mettre à jour. Seules les versions de l’agent publiées le 30 novembre 2023 ou une version ultérieure prennent en charge CloudWatch Application Signals.
Avant de démarrer l’agent CloudWatch, configurez-le pour activer Application Signals. L’exemple suivant est une configuration d’agent CloudWatch qui active Application Signals pour les métriques et les suivis sur un hôte EC2.
Nous vous recommandons de placer ce fichier à l’emplacement /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json sur les systèmes Linux.
{
"traces": {
"traces_collected": {
"application_signals": {}
}
},
"logs": {
"metrics_collected": {
"application_signals": {}
}
}
}
Attachez la politique IAM CloudWatchAgentServerPolicy au rôle IAM de votre instance Amazon EC2. Pour connaître les autorisations requises pour les hôtes sur site, consultez Autorisations pour les serveurs sur site.
Connectez-vous à la AWS Management Console, puis ouvrez la console IAM à l’adresse https://console.aws.amazon.com/iam/.
Choisissez Rôles et recherchez le rôle utilisé par votre instance Amazon EC2. Choisissez ensuite le nom de ce rôle.
Sous l’onglet Autorisations, choisissez Ajouter des autorisations, Attacher des politiques.
Recherchez CloudWatchAgentServerPolicy. Utilisez le champ de recherche si nécessaire. Cochez la case correspondant à la politique, puis choisissez Ajouter des autorisations.
Démarrez l’agent CloudWatch en saisissant les commandes suivantes. Remplacez agent-config-file-path par le chemin d’accès au fichier de configuration de l’agent CloudWatch, tel que ./amazon-cloudwatch-agent.json. Vous devez inclure le préfixe file: comme indiqué.
export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
-a fetch-config \
-m ec2 -s -c file:agent-config-file-path
Autorisations pour les serveurs sur site
Pour un hôte sur site, vous devez fournir une autorisation AWS à votre appareil.
Pour configurer les autorisations pour un hôte sur site
Créer l’utilisateur IAM destiné à fournir les autorisations à votre hôte sur site :
Ouvrez la console IAM à l’adresse https://console.aws.amazon.com/iam/.
Sélectionnez Utilisateurs, Créer un utilisateur.
Dans Détails de l’utilisateur, pour Nom d’utilisateur, saisissez un nom pour le nouvel utilisateur IAM. Ce sera le nom de connexion AWS utilisé pour authentifier votre hôte. Ensuite, sélectionnez Next
Sur la page Définir les autorisations, pour les Options des autorisations, sélectionnez Attacher directement les politiques.
Dans la liste Politiques des autorisations, sélectionnez la politique CloudWatchAgentServerPolicy à ajouter à votre utilisateur. Ensuite, sélectionnez Suivant.
Sur la page Vérifier et créer, vérifiez le nom d’utilisateur et la présence de CloudWatchAgentServerPolicy dans le Récapitulatif des autorisations.
Sélectionnez Créer un utilisateur
Créez et extrayez votre clé d’accès AWS et votre clé secrète :
Dans le volet de navigation de la console IAM, sélectionnez Utilisateurs, puis le nom d’utilisateur que vous avez créé à l’étape précédente.
Sur la page de l’utilisateur, ouvrez l’onglet Informations d’identification de sécurité. Ensuite, dans la section Clés d’accès, sélectionnez Créer une clé d’accès.
Pour Créer une clé d’accès – Étape 1, sélectionnez Interface de ligne de commande (CLI).
Pour Créer une clé d’accès – Étape 2, ajoutez éventuellement une balise puis cliquez sur Suivant.
Pour Créer une clé d’accès – Étape 3, sélectionnez Télécharger le fichier .csv pour enregistrer un fichier .csv avec la clé d’accès et la clé d’accès secrète de votre utilisateur IAM. Vous aurez besoin de ces informations pour l’étape suivante.
Sélectionnez Exécuté.
Configurez vos informations d’identification AWS sur votre hôte sur site en saisissant la commande suivante. Remplacez ACCESS_KEY_ID et SECRET_ACCESS_ID par votre clé d’accès et votre clé d’accès secrète nouvellement générées à partir du fichier .csv que vous avez téléchargé à l’étape précédente.
$ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
Étape 3 : instrumenter votre application et la démarrer
L’étape suivante consiste à instrumenter votre application pour la vigie applicative CloudWatch.
- Java
-
Pour instrumenter vos applications Java dans le cadre de l’activation de la vigie applicative sur une instance Amazon EC2 ou un hôte sur site
Téléchargez la version la plus récente de l’agent d’auto-instrumentation Java de AWS Distro for OpenTelemetry. Vous pouvez télécharger la version la plus récente en utilisant ce lien. Vous pouvez consulter les informations relatives à toutes les versions publiées sur aws-otel-java-instrumentation Releases.
Pour optimiser vos avantages d’Application Signals, utilisez des variables d’environnement pour fournir des informations supplémentaires avant de démarrer votre application. Ces informations seront affichées dans les tableaux de bord d’Application Signals.
Pour la variable OTEL_RESOURCE_ATTRIBUTES, spécifiez les informations suivantes sous forme de paires clé-valeur :
(Facultatif) service.name définit le nom du service. Ce nom s’affichera dans les tableaux de bord de la vigie applicative comme nom du service de votre application. Si vous ne fournissez pas de valeur pour cette clé, la valeur par défaut UnknownService est utilisée.
(Facultatif) deployment.environment définit l’environnement d’exécution de l’application. Cet environnement sera affiché comme l’environnement hébergé de votre application dans les tableaux de bord Application Signals. Si vous ne le spécifiez pas, l’une des valeurs par défaut suivantes est utilisée :
S’il s’agit d’une instance qui fait partie d’un groupe Auto Scaling, la valeur est ec2:name-of-Auto-Scaling-group
S’il s’agit d’une instance Amazon EC2 qui ne fait pas partie d’un groupe Auto Scaling, la valeur est ec2:default
S’il s’agit d’un hôte sur site, la valeur est generic:default
Cette variable d’environnement est utilisée uniquement par la vigie applicative et est convertie en annotations de suivi X-Ray et en dimensions de métriques CloudWatch.
Pour la variable OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les suivis doivent être exportés. Le port OTLP exposé par l’agent CloudWatch est 4316. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
Pour la variable OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les métriques doivent être exportées. Le port OTLP exposé par l’agent CloudWatch est 4316. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
Pour la variable JAVA_TOOL_OPTIONS, spécifiez le chemin où l’agent d’auto-instrumentation Java AWS Distro for OpenTelemetry est stocké.
export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"
Par exemple :
export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar
Pour la variable OTEL_METRICS_EXPORTER, nous vous recommandons de définir la valeur sur none. Cela désactive les autres exportateurs de métriques afin que seul l’exportateur d’Application Signals soit utilisé.
Définissez OTEL_AWS_APPLICATION_SIGNALS_ENABLED sur true. Cela génère des métriques d’Application Signals à partir des suivis.
Démarrez votre application avec les variables d’environnement mentionnées à l’étape précédente. Voici un exemple de script de démarrage.
La configuration suivante prend uniquement en charge les versions 1.32.2 ou ultérieures de l’agent d’instrumentation automatique AWS Distro for OpenTelemetry pour Java.
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
(Facultatif) Pour activer la corrélation des journaux, ajoutez dans OTEL_RESOURCE_ATTRIBUTES une variable d’environnement supplémentaire aws.log.group.names pour les groupes de journaux de votre application. Cela permet de corréler les suivis et les métriques de votre application avec les entrées de journaux correspondantes. Pour cette variable, remplacez $YOUR_APPLICATION_LOG_GROUP par le nom du groupe de journaux de votre application. Si vous avez plusieurs groupes de journaux, vous pouvez les séparer à l’aide d’un esperluette (&), comme dans l’exemple suivant : aws.log.group.names=log-group-1&log-group-2. Pour activer la corrélation entre les métriques et les journaux, la définition de cette variable suffit. Pour de plus amples informations, consultez Activation de la corrélation entre métriques et journaux. Pour activer la corrélation entre les suivis et les journaux, vous devez également modifier la configuration de journalisation de votre application. Pour de plus amples informations, consultez Activation de la corrélation entre suivis et journaux.
L’exemple suivant montre un script de démarrage qui permet d’activer la corrélation des journaux.
JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORT=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
- Python
-
Pour instrumenter vos applications Python dans le cadre de l’activation de la vigie applicative sur une instance Amazon EC2
Téléchargez la dernière version de l’agent d’instrumentation automatique AWS Distro for OpenTelemetry pour Python. Pour l'installer, exécutez la commande d' ci-dessous.
pip install aws-opentelemetry-distro
Vous pouvez consulter les informations sur toutes les versions publiées dans la section Instrumentation AWS Distro for OpenTelemetry pour Python.
Pour optimiser vos avantages d’Application Signals, utilisez des variables d’environnement pour fournir des informations supplémentaires avant de démarrer votre application. Ces informations seront affichées dans les tableaux de bord d’Application Signals.
Pour la variable OTEL_RESOURCE_ATTRIBUTES, spécifiez les informations suivantes sous forme de paires clé-valeur :
service.name défini le nom du service. Il sera affiché comme nom de service pour votre application dans les tableaux de bord d’Application Signals. Si vous ne fournissez pas de valeur pour cette clé, la valeur par défaut UnknownService est utilisée.
deployment.environment définit l’environnement dans lequel l’application s’exécute. Cet environnement sera affiché comme l’environnement hébergé de votre application dans les tableaux de bord Application Signals. Si vous ne le spécifiez pas, l’une des valeurs par défaut suivantes est utilisée :
S’il s’agit d’une instance qui fait partie d’un groupe Auto Scaling, la valeur est ec2:name-of-Auto-Scaling-group.
S’il s’agit d’une instance Amazon EC2 qui ne fait pas partie d’un groupe Auto Scaling, la valeur est ec2:default
S’il s’agit d’un hôte sur site, la valeur est generic:default
Cette clé d’attribut n’est utilisée que par Application Signals et est convertie en annotations de suivi X-Ray et en dimensions de métrique CloudWatch.
Pour la variable OTEL_EXPORTER_OTLP_PROTOCOL, spécifiez http/protobuf afin d’exporter les données de télémétrie via HTTP vers les points de terminaison de l’agent CloudWatch décrits ci-dessous.
Pour la variable OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les suivis doivent être exportés. L’agent CloudWatch expose le port 4316 comme port OTLP via HTTP. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
Pour la variable OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les métriques doivent être exportées. L’agent CloudWatch expose le port 4316 comme port OTLP via HTTP. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
Pour la variable OTEL_METRICS_EXPORTER, nous vous recommandons de définir la valeur sur none. Cela désactive les autres exportateurs de métriques afin que seul l’exportateur d’Application Signals soit utilisé.
Définissez la variable OTEL_AWS_APPLICATION_SIGNALS_ENABLED sur true afin que votre conteneur commence à envoyer des suivis X-Ray et des métriques CloudWatch à la vigie applicative.
Démarrez votre application avec les variables d’environnement décrites à l’étape précédente. Voici un exemple de script de démarrage.
Remplacez $SVC_NAME par le nom de votre application. Ce nom apparaîtra comme nom de l’application dans les tableaux de bord de la vigie applicative.
Remplacez $PYTHON_APP par l’emplacement et le nom de votre application.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
Avant d’activer la vigie applicative pour vos applications Python, tenez compte des considérations suivantes.
Dans certaines applications conteneurisées, l’absence de la variable d’environnement PYTHONPATH peut empêcher l’application de démarrer. Pour résoudre ce problème, veillez à définir la variable d’environnement PYTHONPATH sur le répertoire de travail de votre application. Ce problème est lié à un bogue connu de l’instrumentation automatique OpenTelemetry. Pour plus d’informations sur ce problème, consultez la section Le paramètre d’instrumentation automatique Python pour PYTHONPATH n’est pas conforme.
Pour les applications Django, des configurations supplémentaires sont nécessaires, comme indiqué dans la documentation OpenTelemetry pour Python.
Utilisez le paramètre --noreload pour empêcher le rechargement automatique.
Définissez la variable d’environnement DJANGO_SETTINGS_MODULE sur l’emplacement du fichier settings.py de votre application Django. Cela permet à OpenTelemetry d’accéder correctement à vos paramètres Django et de s’y intégrer.
-
(Facultatif) Pour activer la corrélation des journaux, ajoutez dans OTEL_RESOURCE_ATTRIBUTES une variable d’environnement supplémentaire aws.log.group.names pour les groupes de journaux de votre application. Cela permet de corréler les suivis et les métriques de votre application avec les entrées de journaux correspondantes. Pour cette variable, remplacez $YOUR_APPLICATION_LOG_GROUP par le nom du groupe de journaux de votre application. Si vous avez plusieurs groupes de journaux, vous pouvez les séparer à l’aide d’un esperluette (&), comme dans l’exemple suivant : aws.log.group.names=log-group-1&log-group-2. Pour activer la corrélation entre les métriques et les journaux, la définition de cette variable suffit. Pour de plus amples informations, consultez Activation de la corrélation entre métriques et journaux. Pour activer la corrélation entre les suivis et les journaux, vous devez également modifier la configuration de journalisation de votre application. Pour de plus amples informations, consultez Activation de la corrélation entre suivis et journaux.
L’exemple suivant montre un script de démarrage qui permet d’activer la corrélation des journaux.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_PYTHON_DISTRO=aws_distro \
OTEL_PYTHON_CONFIGURATOR=aws_configurator \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
java -jar $MY_PYTHON_APP.jar
- .NET
-
Pour instrumenter vos applications .NET dans le cadre de l’activation de la vigie applicative sur une instance Amazon EC2 ou un hôte sur site
Téléchargez la dernière version du package d’instrumentation automatique AWS Distro for OpenTelemetry pour .NET. Vous pouvez télécharger la dernière version depuis la section Versions aws-otel-dotnet-instrumentation.
Pour activer la vigie applicative, définissez les variables d’environnement ci-dessous afin de fournir des informations supplémentaires avant de démarrer votre application. Ces variables sont nécessaires pour configurer le hook de démarrage pour l’instrumentation .NET avant le lancement de votre application .NET. Remplacez dotnet-service-name dans la variable d’environnement OTEL_RESOURCE_ATTRIBUTES par le nom du service de votre choix.
Voici un exemple pour Linux.
export INSTALL_DIR=OpenTelemetryDistribution
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}
export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4316
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://127.0.0.1:4316/v1/metrics
export OTEL_METRICS_EXPORTER=none
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
export OTEL_TRACES_SAMPLER=xray
export OTEL_TRACES_SAMPLER_ARG=http://127.0.0.1:2000
Voici un exemple de configuration pour Windows Server.
$env:INSTALL_DIR = "OpenTelemetryDistribution"
$env:CORECLR_ENABLE_PROFILING = 1
$env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
$env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll"
$env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps"
$env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store"
$env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
$env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR
$env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=dotnet-service-name"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4316"
$env:OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT = "http://127.0.0.1:4316/v1/metrics"
$env:OTEL_METRICS_EXPORTER = "none"
$env:OTEL_AWS_APPLICATION_SIGNALS_ENABLED = "true"
$env:OTEL_TRACES_SAMPLER = "xray"
$env:OTEL_TRACES_SAMPLER_ARG = "http://127.0.0.1:2000"
Démarrez votre application avec les variables d’environnement mentionnées à l’étape précédente.
(Facultatif) Vous pouvez également utiliser les scripts d’installation fournis pour faciliter la configuration du package d’instrumentation automatique AWS Distro for OpenTelemetry pour .NET.
Pour Linux, téléchargez et installez le script d’installation Bash depuis la page des versions GitHub :
# Download and Install
curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
chmod +x ./aws-otel-dotnet-install.sh
./aws-otel-dotnet-install.sh
# Instrument
. $HOME/.otel-dotnet-auto/instrument.sh
export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
Pour Windows Server, téléchargez et installez le script d’installation PowerShell depuis la page des versions GitHub :
# Download and Install
$module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path
Import-Module $download_path
Install-OpenTelemetryCore
# Instrument
Import-Module $download_path
Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
Register-OpenTelemetryForIIS
Le package NuGet du package d’instrumentation automatique AWS Distro for OpenTelemetry pour .NET. est également disponible dans le référentiel officiel NuGet. Assurez-vous de consulter le fichier README pour des instructions.
- Node.js
-
Pour instrumenter vos applications Node.js dans le cadre de l’activation de la vigie applicative sur une instance Amazon EC2
Téléchargez la dernière version de l’agent d’instrumentation automatique JavaScript de AWS Distro for OpenTelemetry pour Node.js. Pour l'installer, exécutez la commande d' ci-dessous.
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
Vous pouvez consulter les informations sur toutes les versions publiées dans la section Instrumentation AWS Distro for OpenTelemetry pour JavaScript.
Pour optimiser vos avantages d’Application Signals, utilisez des variables d’environnement pour fournir des informations supplémentaires avant de démarrer votre application. Ces informations seront affichées dans les tableaux de bord d’Application Signals.
Pour la variable OTEL_RESOURCE_ATTRIBUTES, spécifiez les informations suivantes sous forme de paires clé-valeur :
service.name défini le nom du service. Il sera affiché comme nom de service pour votre application dans les tableaux de bord d’Application Signals. Si vous ne fournissez pas de valeur pour cette clé, la valeur par défaut UnknownService est utilisée.
deployment.environment définit l’environnement dans lequel l’application s’exécute. Cet environnement sera affiché comme l’environnement hébergé de votre application dans les tableaux de bord Application Signals. Si vous ne le spécifiez pas, l’une des valeurs par défaut suivantes est utilisée :
S’il s’agit d’une instance qui fait partie d’un groupe Auto Scaling, la valeur est ec2:name-of-Auto-Scaling-group.
S’il s’agit d’une instance Amazon EC2 qui ne fait pas partie d’un groupe Auto Scaling, la valeur est ec2:default
S’il s’agit d’un hôte sur site, la valeur est generic:default
Cette clé d’attribut n’est utilisée que par Application Signals et est convertie en annotations de suivi X-Ray et en dimensions de métrique CloudWatch.
Pour la variable OTEL_EXPORTER_OTLP_PROTOCOL, spécifiez http/protobuf afin d’exporter les données de télémétrie via HTTP vers les points de terminaison de l’agent CloudWatch décrits ci-dessous.
Pour la variable OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les suivis doivent être exportés. L’agent CloudWatch expose le port 4316 comme port OTLP via HTTP. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
Pour la variable OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT, spécifiez l’URL du point de terminaison de base vers lequel les métriques doivent être exportées. L’agent CloudWatch expose le port 4316 comme port OTLP via HTTP. Sur Amazon EC2, étant donné que les applications communiquent avec l’agent CloudWatch local, vous devez définir cette valeur sur OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
Pour la variable OTEL_METRICS_EXPORTER, nous vous recommandons de définir la valeur sur none. Cela désactive les autres exportateurs de métriques afin que seul l’exportateur d’Application Signals soit utilisé.
Définissez la variable OTEL_AWS_APPLICATION_SIGNALS_ENABLED sur true afin que votre conteneur commence à envoyer des suivis X-Ray et des métriques CloudWatch à la vigie applicative.
Démarrez votre application avec les variables d’environnement décrites à l’étape précédente. Voici un exemple de script de démarrage.
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_TRACES_SAMPLER=xray \
OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
-
(Facultatif) Pour activer la corrélation des journaux, ajoutez dans OTEL_RESOURCE_ATTRIBUTES une variable d’environnement supplémentaire aws.log.group.names pour les groupes de journaux de votre application. Cela permet de corréler les suivis et les métriques de votre application avec les entrées de journaux correspondantes. Pour cette variable, remplacez $YOUR_APPLICATION_LOG_GROUP par le nom du groupe de journaux de votre application. Si vous avez plusieurs groupes de journaux, vous pouvez les séparer à l’aide d’un esperluette (&), comme dans l’exemple suivant : aws.log.group.names=log-group-1&log-group-2. Pour activer la corrélation entre les métriques et les journaux, la définition de cette variable suffit. Pour de plus amples informations, consultez Activation de la corrélation entre métriques et journaux. Pour activer la corrélation entre les suivis et les journaux, vous devez également modifier la configuration de journalisation de votre application. Pour de plus amples informations, consultez Activation de la corrélation entre suivis et journaux.
L’exemple suivant montre un script de démarrage qui permet d’activer la corrélation des journaux.
export OTEL_METRICS_EXPORTER=none \
export OTEL_LOGS_EXPORTER=none \
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
export OTEL_TRACES_SAMPLER=xray \
export OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:2000 \
export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME" \
node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
Configuration d’une application Node.js utilisant le format de module ESM
Un support limité est disponible pour les applications Node.js utilisant le format de module ESM. Pour en savoir plus, consultez Limitations connues concernant Node.js avec ESM.
Pour activer la vigie applicative pour une application Node.js utilisant le format ESM, vous devez adapter les étapes de la procédure précédente.
Tout d’abord, installez @opentelemetry/instrumentation pour votre application Node.js :
npm install @opentelemetry/instrumentation@0.54.0
Ensuite, aux étapes 3 et 4 de la procédure précédente, modifiez les options du nœud :
--require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register'
par :
--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs
(Facultatif) Étape 4 : surveiller l’état de votre application
Une fois vos applications activées sur Amazon EC2, vous pouvez surveiller leur état directement dans la vigie applicative. Pour de plus amples informations, consultez Surveillez l’état de fonctionnement de vos applications avec Application Signals.
