otel: NGINX OpenTelemetry module dynamique
Installation
Vous pouvez installer ce module sur n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :
- RedHat Enterprise Linux 7, 8, 9 et 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 et Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-otel
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-otel
Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :
load_module modules/ngx_otel_module.so;
Ce document décrit nginx-module-otel v0.1.2 publié le 15 mars 2025.
Qu'est-ce qu'OpenTelemetry
OpenTelemetry (OTel) est un cadre d'observabilité pour surveiller, tracer, dépanner et optimiser les applications. OTel permet la collecte de données de télémétrie à partir d'une pile d'application déployée.
Qu'est-ce que le module OTel natif de NGINX
Le module dynamique ngx_otel_module permet à NGINX Open Source ou NGINX Plus d'envoyer des données de télémétrie à un collecteur OTel. Il fournit un support pour la propagation du contexte de trace W3C, les exports de traces via le protocole OpenTelemetry (OTLP)/gRPC et offre plusieurs avantages par rapport aux modules OTel existants, notamment :
Meilleure performance
Les implémentations OTel tierces réduisent la performance du traitement des requêtes jusqu'à 50 % lorsque le traçage est activé. Le module natif NGINX limite cet impact à environ 10-15 %.
Provisionnement facile
La configuration peut être effectuée directement dans les fichiers de configuration de NGINX.
Contrôle dynamique basé sur des variables
La capacité de contrôler dynamiquement les paramètres de trace à l'aide de cookies, de jetons et de variables. Veuillez consulter notre exemple de Traçage basé sur le ratio pour plus de détails.
De plus, NGINX Plus, disponible dans le cadre d'un abonnement commercial, permet un contrôle dynamique des paramètres d'échantillonnage via l'API NGINX Plus et les modules de stockage clé-valeur.
Activation du module OTel
Suivre les étapes d'installation ci-dessus installera le module par défaut dans /etc/nginx/modules. Chargez le module en ajoutant la ligne suivante en haut du fichier de configuration principal de NGINX, situé à /etc/nginx/nginx.conf.
load_module modules/ngx_otel_module.so;
Configuration du module
Pour une liste complète des directives, des variables intégrées, des attributs de span par défaut et des configurations d'exemple, veuillez vous référer à la documentation du ngx_otel_module.
Exemples
Utilisez ces exemples pour configurer certains cas d'utilisation courants pour le traçage OTel.
Traçage simple
Cet exemple envoie des données de télémétrie pour toutes les requêtes http.
http {
otel_exporter {
endpoint localhost:4317;
}
otel_trace on;
server {
location / {
proxy_pass http://backend;
}
}
}
Traçage basé sur le parent
Dans cet exemple, nous héritons des contextes de trace des requêtes entrantes et enregistrons des spans uniquement si un span parent est échantillonné. Nous propagons également les contextes de trace et les décisions d'échantillonnage aux serveurs en amont.
http {
server {
location / {
otel_trace $otel_parent_sampled;
otel_trace_context propagate;
proxy_pass http://backend;
}
}
}
Traçage basé sur le ratio
Dans cet exemple basé sur le ratio, le traçage est configuré pour un pourcentage de trafic (dans ce cas 10 %) :
http {
# tracer 10% des requêtes
split_clients $otel_trace_id $ratio_sampler {
10% on;
* off;
}
# ou nous pouvons tracer 10% des sessions utilisateur
split_clients $cookie_sessionid $session_sampler {
10% on;
* off;
}
server {
location / {
otel_trace $ratio_sampler;
otel_trace_context inject;
proxy_pass http://backend;
}
}
}
Collecte et affichage des traces
Il existe plusieurs méthodes et packages logiciels disponibles pour visualiser les traces. Pour un démarrage rapide, Jaeger fournit un conteneur tout-en-un pour collecter, traiter et visualiser les données de trace OTel. Suivez ces étapes pour télécharger, installer, lancer et utiliser les services OTel de Jaeger.
Journal des modifications
Consultez notre page de publication pour suivre les mises à jour.
GitHub
Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-otel.