Instrumenter une application serveur
Configurez votre application (Node.js, Python, Java, .NET, PHP, Go ou Ruby) avec OpenTelemetry pour qu'elle envoie traces, métriques et journaux à l'APM de ARGUNIS.
Sur cette page
Instrumenter, c'est ajouter OpenTelemetry à votre application pour qu'elle mesure chaque requête et l'envoie à ARGUNIS. Dans presque tous les langages, cela se fait sans toucher au code : vous installez le paquet officiel, définissez quelques variables d'environnement et démarrez l'application avec l'instrumenteur.
Tout ce dont vous avez besoin se trouve dans Paramètres → APM → Clé API et SDK, section SDK par langage et autres façons d'envoyer, onglet Langages. Cette page explique les mêmes étapes.
Avant de commencer
L'APM doit être actif et vous devez avoir un jeton serveur. Voir Créer un jeton d'ingestion.
Ayez sous la main l'URL d'ingestion (OTLP/HTTP) qui apparaît dans la carte Jetons d'ingestion de Paramètres → APM → Clé API et SDK.
Si vous créez le jeton sur le même écran, les blocs de code de Comment instrumenter contiennent déjà votre URL d'ingestion et votre jeton. Utilisez Copier à chaque étape.
Les paramètres fournis par Argunis Monitoring
Tous les langages utilisent les mêmes variables standard d'OpenTelemetry. Placez-les dans l'environnement de votre application (fichier de service, conteneur, pool IIS, configuration du cloud) :
OTEL_SERVICE_NAME=mi-servicio
OTEL_EXPORTER_OTLP_ENDPOINT=https://URL_DE_INGESTA
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20jtk_TU_TOKEN_DE_SERVIDOR
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=produccion,service.namespace=mi-sistema,service.version=1.0.0
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlpVariable | Ce que vous indiquez |
|---|---|
| Le nom sous lequel le service apparaît dans APM → Services |
| L'URL d'ingestion de la carte État |
| Toujours |
|
|
| L'environnement ( |
|
|
Indiquer service.version à chaque déploiement sert à deux choses : voir dans quelle version une erreur est apparue et permettre à ARGUNIS de fermer tout seul les incidents d'erreurs quand une nouvelle version ne les a plus. Si service.namespace correspond au nom d'un groupe de l'inventaire, le service se place dans ce groupe.
Node.js
Instrumentation automatique officielle (http, Express, Fastify, NestJS, pg, mysql, MongoDB, Redis, fetch, gRPC, Kafka et plus). CommonJS et ESM, Node 20.6 ou supérieur.
Installez les paquets dans l'application :
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodeDéfinissez les variables d'environnement ci-dessus et ajoutez
OTEL_NODE_RESOURCE_DETECTORS=allpour qu'il détecte tout seul le cloud, le conteneur et le serveur.Démarrez avec l'enregistrement d'OpenTelemetry avant votre code :
node --import @opentelemetry/auto-instrumentations-node/register dist/server.jsAvec PM2 ou Docker, ajoutez l'option à NODE_OPTIONS :
NODE_OPTIONS="--import @opentelemetry/auto-instrumentations-node/register"Python
Django, Flask, FastAPI, Celery, requests, psycopg, SQLAlchemy, Redis et plus, avec la distribution officielle.
Installez la distribution et les instrumentations de ce qu'utilise votre projet :
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a installDéfinissez les variables d'environnement et ajoutez
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=truepour envoyer aussi les journaux delogging.Démarrez en enveloppant votre commande :
opentelemetry-instrument gunicorn app.wsgi:application --workers 4
# o: opentelemetry-instrument python app.pyJava et Kotlin
L'agent officiel instrumente Spring, Jakarta EE, Tomcat, JBoss/WildFly, WebSphere, JDBC (DB2, Oracle, SQL Server, PostgreSQL…), JMS, Kafka et plus. Java 8 ou supérieur.
Téléchargez l'agent (en production, fixez la version) :
curl -L -o /opt/otel/opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jarDéfinissez les variables d'environnement.
Ajoutez l'agent à la JVM (sous WebSphere ou Tomcat, dans les arguments génériques de la JVM) :
java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar app.jarSur AWS, Azure ou Google Cloud, activez le détecteur du cloud correspondant :
-Dotel.resource.providers.aws.enabled=true
-Dotel.resource.providers.azure.enabled=true
-Dotel.resource.providers.gcp.enabled=true.NET
Instrumentation automatique officielle pour .NET 8 ou supérieur et .NET Framework 4.6.2 ou supérieur (ASP.NET Core, ASP.NET sous IIS, HttpClient, SQL Server, EF Core…).
Sous Linux ou dans un conteneur :
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
sh ./otel-dotnet-auto-install.sh
. $HOME/.otel-dotnet-auto/instrument.sh
dotnet MiApp.dllSous Windows avec IIS (PowerShell en tant qu'administrateur) :
$m = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $m -OutFile OpenTelemetry.DotNet.Auto.psm1
Import-Module .\OpenTelemetry.DotNet.Auto.psm1
Install-OpenTelemetryCore
Register-OpenTelemetryForIISDéfinissez ensuite les variables d'environnement (sous IIS, dans le pool d'applications).
PHP
Extension officielle et auto-instrumentation de Laravel, Symfony, Slim, WordPress, PDO, curl et Guzzle. PHP 8.0 ou supérieur.
Installez l'extension et les paquets (exemple avec Laravel) :
pecl install opentelemetry
echo "extension=opentelemetry.so" >> $(php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||")
composer require open-telemetry/sdk open-telemetry/exporter-otlp \
open-telemetry/opentelemetry-auto-laravel open-telemetry/opentelemetry-auto-pdo php-http/guzzle7-adapterDéfinissez les variables d'environnement et ajoutez
OTEL_PHP_AUTOLOAD_ENABLED=true. Avec PHP-FPM, elles vont dans le pool avecenv[...].
Go
SDK officiel avec instrumentation de net/http, gRPC et database/sql. En Go, il faut ajouter quelques lignes au démarrage.
Ajoutez les paquets :
go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk \
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttpAu démarrage de l'application (l'exportateur lit les variables
OTEL_*) :
exp, err := otlptracehttp.New(ctx)
if err != nil { log.Fatal(err) }
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp), sdktrace.WithResource(resource.Default()))
defer tp.Shutdown(ctx)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})
http.ListenAndServe(":8080", otelhttp.NewHandler(mux, "servidor"))Définissez les variables d'environnement.
Ruby
Rails, Sinatra, Sidekiq, ActiveRecord, Net::HTTP, Redis et plus.
Ajoutez les gems :
bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-allCréez
config/initializers/opentelemetry.rb:
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure { |c| c.use_all }Définissez les variables d'environnement.
Tous les SDK envoient en OTLP/HTTP avec protobuf à l'URL d'ingestion. Si un système ne parle que gRPC ou ne sort pas sur Internet, utilisez l'OpenTelemetry Collector comme passerelle. Voir Instrumenter dans les clouds et conteneurs.
Ce qui se passe ensuite
Redémarrez l'application et générez un peu de trafic. En une ou deux minutes, le service apparaît dans APM → Services avec le nom indiqué dans OTEL_SERVICE_NAME. S'il n'apparaît pas, vérifiez dans APM → Configuration et réglages l'indicateur Rejetés aujourd'hui, et dans Paramètres → APM → Clé API et SDK la Dernière utilisation du jeton.