L’instrumentation sans code attache un agent à votre application au démarrage. L’agent patche les bibliothèques courantes, comme les serveurs et clients HTTP, les pilotes de bases de données et les files de messages, et produit des traces, des métriques et des logs sans modifier le code source. La configuration repose sur les variables d’environnement standard OTEL_* plus quelques variables propres à chaque langage ; toute la mise en place tient donc dans une ligne de Dockerfile et quelques variables. Ce guide couvre Java, Python et Node.js.

Prérequis : un endroit où envoyer les données

Ayez un Collector en écoute, par exemple celui du guide Docker Compose, sur otel-collector:4318 (HTTP) ou :4317 (gRPC). Chaque exemple ci-dessous le cible avec OTEL_EXPORTER_OTLP_ENDPOINT.

Java

Téléchargez une fois le JAR de l’agent, puis attachez-le avec -javaagent :

curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=checkout \
     -jar myapp.jar

Les conteneurs préfèrent généralement les variables d’environnement, avec JAVA_TOOL_OPTIONS portant l’option pour ne pas modifier l’entrypoint :

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY myapp.jar .
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/<version>/opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/opentelemetry-javaagent.jar"
CMD ["java", "-jar", "myapp.jar"]

Épinglez la version de l’agent dans l’URL de téléchargement plutôt que d’utiliser latest, afin que les builds soient reproductibles. Configurez-le ensuite à l’exécution :

OTEL_SERVICE_NAME=checkout \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging \
java -jar myapp.jar

L’agent peut être configuré de trois façons : propriétés système (-Dotel.service.name=...), variables d’environnement, ou un fichier de propriétés Java référencé avec OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/file.properties (ou -Dotel.javaagent.configuration-file). Gardez le fichier de propriétés dans Git lorsque vous avez de nombreux paramètres. Pour déboguer l’agent lui-même, définissez OTEL_JAVAAGENT_DEBUG=true, et attendez-vous à une sortie très verbeuse. L’agent prend aussi en charge un fichier de configuration YAML déclaratif ; consultez la documentation de l’agent Java.

Python

Installez la distribution, l’exporter OTLP et les bibliothèques d’instrumentation qui correspondent à vos paquets installés :

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap -a install analyse votre environnement et installe l’instrumentation correspondant à ce qu’il trouve, par exemple l’instrumentation Flask lorsque Flask est installé. Exécutez opentelemetry-bootstrap sans argument pour voir ses recommandations sans rien installer. Démarrez l’application via opentelemetry-instrument :

OTEL_SERVICE_NAME=checkout \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
opentelemetry-instrument python myapp.py

Notez les antislashs de fin de ligne : chaque variable doit se trouver sur la même ligne de commande logique que opentelemetry-instrument, sinon elle n’atteindra pas le processus. Pour des serveurs comme Gunicorn ou Uvicorn, enveloppez la commande du serveur : opentelemetry-instrument gunicorn app:app. Certaines configurations avec le gestionnaire de paquets uv nécessitent un contournement pour l’étape de bootstrap, que décrit la page de dépannage Python. L’export des logs est optionnel en Python ; consultez donc la section sur la journalisation de la documentation Python si les logs n’apparaissent pas.

Un modèle de Dockerfile :

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt \
 && pip install opentelemetry-distro opentelemetry-exporter-otlp \
 && opentelemetry-bootstrap -a install
COPY . .
CMD ["opentelemetry-instrument", "python", "myapp.py"]

Node.js

Installez l’API et le bundle d’auto-instrumentation :

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

Chargez-le avant votre application avec --require, ou via NODE_OPTIONS :

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_NODE_RESOURCE_DETECTORS=env,host,os
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js

OTEL_NODE_RESOURCE_DETECTORS limite les détecteurs de resource qui s’exécutent (tous sont activés par défaut). OTEL_NODE_ENABLED_INSTRUMENTATIONS limite les instrumentations chargées ; consultez la page de configuration du module. OTEL_LOG_LEVEL accepte none, error, warn, info, debug, verbose et all, avec info par défaut. Gardez info en production, car la sortie debug nuit aux performances. Les applications en modules ES peuvent nécessiter une option de loader supplémentaire ; suivez la documentation Node.js pour votre système de modules.

.NET, Go et les autres

.NET dispose d’un agent sans code configuré de la même manière (variables d’environnement plus un script de démarrage). Go utilise un agent basé sur eBPF qui s’exécute comme un sidecar privilégié et a besoin du chemin de l’exécutable cible ; il est donc surtout utilisé via l’Operator. Consultez la section sans code de la documentation pour chacun.

Ce que vous obtenez, et ce que vous n’obtenez pas

Vous obtenez des spans pour le HTTP entrant et sortant, les appels de bases de données et les bibliothèques de messagerie courantes, ainsi que des métriques d’exécution dans certains langages. Vous n’obtenez pas de spans métier, comme « calculer la remise », car l’agent ne peut pas les connaître. Ajoutez quelques spans ou attributs manuels avec l’API OpenTelemetry là où le détail supplémentaire en vaut la peine, et gardez l’agent pour tout le reste.

Vérifier que ça fonctionne

1. Démarrez l’application avec l’exporter debug du Collector activé.
2. Envoyez une requête : curl http://localhost:8080/.
3. Cherchez dans le log du Collector des spans avec votre service.name :

docker compose logs otel-collector | grep -i 'service.name'

Si rien n’arrive, vérifiez dans cet ordre : l’endpoint et le port correspondent au protocole, le pipeline du Collector pour le signal liste le receiver otlp, l’application peut résoudre le nom d’hôte du Collector, et OTEL_SDK_DISABLED n’est pas défini. Le guide de dépannage détaille chacun de ces points.

Notes de production

• Épinglez les versions de l’agent et de la distribution, et mettez-les à jour de manière délibérée.
• Définissez service.name, service.version et deployment.environment.name sur chaque service, car les tableaux de bord en dépendent.
• Commencez avec un ratio d’échantillonnage plutôt que de tout conserver (voir le guide sur l’échantillonnage).
• Sur Kubernetes, utilisez l’Operator pour injecter l’agent par annotation au lieu de modifier chaque Dockerfile.