otel: Módulo dinámico de NGINX OpenTelemetry
Instalación
Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:
- RedHat Enterprise Linux 7, 8, 9 y 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 y 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
Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:
load_module modules/ngx_otel_module.so;
Este documento describe nginx-module-otel v0.1.2 lanzado el 15 de marzo de 2025.
¿Qué es OpenTelemetry?
OpenTelemetry (OTel) es un marco de observabilidad para monitorear, rastrear, solucionar problemas y optimizar aplicaciones. OTel permite la recolección de datos de telemetría de un stack de aplicaciones desplegado.
¿Qué es el Módulo Nativo OTel de NGINX?
El módulo dinámico ngx_otel_module permite que NGINX Open Source o NGINX Plus envíen datos de telemetría a un colector OTel. Proporciona soporte para la propagación del contexto de traza W3C, exportaciones de traza OpenTelemetry Protocol (OTLP)/gRPC y ofrece varios beneficios sobre los módulos OTel existentes, incluyendo:
Mejor Rendimiento
Las implementaciones de OTel de terceros reducen el rendimiento del procesamiento de solicitudes hasta en un 50% cuando se habilita el rastreo. El módulo nativo de NGINX limita este impacto a aproximadamente un 10-15%.
Aprovisionamiento Fácil
La configuración se puede realizar directamente en los archivos de configuración de NGINX.
Control Dinámico Basado en Variables
La capacidad de controlar dinámicamente los parámetros de traza utilizando cookies, tokens y variables. Consulta nuestro ejemplo de Rastreo basado en proporciones para más detalles.
Además, NGINX Plus, disponible como parte de una suscripción comercial, permite el control dinámico de los parámetros de muestreo a través de la API de NGINX Plus y los módulos de almacenamiento clave-valor.
Habilitando el Módulo OTel
Siguiendo los pasos de instalación anteriores, el módulo se instalará en /etc/nginx/modules por defecto. Carga el módulo añadiendo la siguiente línea en la parte superior del archivo de configuración principal de NGINX, ubicado en /etc/nginx/nginx.conf.
load_module modules/ngx_otel_module.so;
Configurando el Módulo
Para una lista completa de directivas, variables integradas, atributos de span predeterminados y configuraciones de ejemplo, consulta la documentación del ngx_otel_module.
Ejemplos
Utiliza estos ejemplos para configurar algunos casos de uso comunes para el rastreo OTel.
Rastreo Simple
Este ejemplo envía datos de telemetría para todas las solicitudes http.
http {
otel_exporter {
endpoint localhost:4317;
}
otel_trace on;
server {
location / {
proxy_pass http://backend;
}
}
}
Rastreo Basado en Padres
En este ejemplo, heredamos contextos de traza de las solicitudes entrantes y registramos spans solo si un span padre es muestreado. También propagamos contextos de traza y decisiones de muestreo a servidores ascendentes.
http {
server {
location / {
otel_trace $otel_parent_sampled;
otel_trace_context propagate;
proxy_pass http://backend;
}
}
}
Rastreo Basado en Proporciones
En este ejemplo basado en proporciones, el rastreo se configura para un porcentaje de tráfico (en este caso 10%):
http {
# rastrear el 10% de las solicitudes
split_clients $otel_trace_id $ratio_sampler {
10% on;
* off;
}
# o podemos rastrear el 10% de las sesiones de usuario
split_clients $cookie_sessionid $session_sampler {
10% on;
* off;
}
server {
location / {
otel_trace $ratio_sampler;
otel_trace_context inject;
proxy_pass http://backend;
}
}
}
Recolectando y Visualizando Trazas
Existen varios métodos y paquetes de software disponibles para visualizar trazas. Para un inicio rápido, Jaeger proporciona un contenedor todo-en-uno para recolectar, procesar y visualizar datos de trazas OTel. Sigue estos pasos para descargar, instalar, lanzar y utilizar los servicios OTel de Jaeger.
Registro de Cambios
Consulta nuestra página de lanzamientos para mantenerte al tanto de las actualizaciones.
GitHub
Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-otel.