Tutorial: Configure OpenTelemetry para sus aplicações usando NGINX

Si está buscando una herramienta para rastrear aplicações web e infraestructura de manera más efectiva, OpenTelemetry podría ser justo lo que necesita. Al instrumentar su servidor NGINX con el módulo comunitario NGINX OpenTelemetry existente, puede recopilar métricas, seguimientos y registros y obtener una mejor visibilidad del estado de su servidor. Esto, a su vez, le permite solucionar problemas y optimizar sus aplicações web para un mejor rendimiento. Sin embargo, este módulo comunitario existente también puede ralentizar los tiempos de respuesta de su servidor debido a la sobrecarga de rendimiento que requiere para el rastreo. Este proceso también puede consumir recursos adicionales, aumentando el uso de CPU y memoria. Además, instalar y configurar el módulo puede ser una molestia.

NGINX ha desarrollado recientemente un módulo nativo OpenTelemetry, ngx_otel_module , que revoluciona el seguimiento del rendimiento del procesamiento de solicitudes. El módulo utiliza llamadas de telemetría para monitorear las solicitudes y respuestas de las aplicação , lo que permite capacidades de seguimiento mejoradas. El módulo se puede instalar y configurar cómodamente dentro de los archivos de configuración de NGINX, lo que lo hace muy fácil de usar. Este nuevo módulo satisface las necesidades de los usuarios de NGINX OSS y NGINX Plus. Admite la propagación de contexto W3C y el protocolo de exportación OTLP/gRPC, lo que lo convierte en una solución integral para optimizar el rendimiento.

El módulo OpenTelemetry nativo de NGINX es un módulo dinámico que no requiere ningún paquete adicional con NGINX Plus. Ofrece una variedad de funciones, incluidos módulos de API y almacenamiento de clave-valor. Estas características funcionan juntas para proporcionar una solución completa para monitorear y optimizar el rendimiento de su instancia NGINX Plus. Al utilizar ngx_otel_module , puede obtener información valiosa sobre el rendimiento de su aplicación web y tomar medidas para mejorarla. Le recomendamos encarecidamente explorar ngx_otel_module para descubrir cómo puede ayudarle a lograr mejores resultados.

Nota:  Puede dirigirse a nuestra página de GitHub para obtener instrucciones detalladas sobre cómo instalar nginx_otel_module y comenzar.

Descripción general del tutorial

En este blog, puede seguir una guía paso a paso sobre cómo configurar OpenTelemetry en NGINX Plus y utilizar la herramienta Jaeger para recopilar y visualizar rastros. OpenTelemetry es una herramienta poderosa que ofrece una vista integral de la ruta de una solicitud, incluida información valiosa como latencia, detalles de la solicitud y datos de respuesta. Esto puede ser increíblemente útil para optimizar el rendimiento e identificar problemas potenciales. Para simplificar las cosas, hemos configurado el módulo OpenTelemetry, la aplicação y Jaeger en una sola instancia, que puedes ver en el diagrama a continuación.

Siga los pasos de estas secciones para completar el tutorial:

• Requisitos previos
• Implementar NGINX Plus e instalar el módulo OpenTelemetry
• Implementar Jaeger y la aplicação echo
• Configurar OpenTelemetry en NGINX para el seguimiento
• Probar la configuración

Requisitos previos

• Un entorno Linux/Unix, o cualquier entorno compatible
• Una suscripción a NGINX Plus
• Familiaridad básica con la línea de comandos de Linux y JavaScript
• Docker
• Node.js 19.x o posterior
• cURL

Implementar NGINX Plus e instalar el módulo OpenTelemetry

Seleccionar un entorno apropiado es crucial para implementar con éxito una instancia NGINX. Este tutorial lo guiará a través de la implementación de NGINX Plus y la instalación de los módulos dinámicos de NGINX.

1. Instale NGINX Plus en un sistema operativo compatible .
2. Instalar ngx_otel_module . Agregue el módulo dinámico al directorio de configuración de NGINX para activar OpenTelemetry:

módulo de carga módulos/ngx_otel_module.so;

3. Recargue NGINX para habilitar el módulo:

nginx -t y nginx -s recargar

Implementar Jaeger y la aplicação echo

Hay varias opciones disponibles para ver los rastros. Este tutorial utiliza Jaeger para recopilar y analizar datos de OpenTelemetry. Jaeger proporciona una interfaz eficiente y fácil de usar para recopilar y visualizar datos de rastreo. Después de recopilar datos, implementará mendhak/http-https-echo , una aplicação Docker simple. Esta aplicação devuelve los atributos de solicitud de JavaScript en formato JSON.

1. Utilice docker-compose para implementar Jaeger y la aplicaçãohttp-echo . Puede crear un archivo docker-compose copiando la configuración a continuación y guardándola en un directorio de su elección.

    

   versión: '3'
   
   Servicios:
   Jaeger:
   Imagen: jaegertracing/all-in-one:1.41
   Container_name: Jaeger
   Puertos:
   - "16686:16686"
   - "4317:4317"
   - "4318:4318"
   Entorno:
         COLLECTOR_OTLP_ENABLED: verdadero
   
   http-echo:
   imagen: mendhak/http-https-echo
   entorno:
   - HTTP_PORT=8888
   - HTTPS_PORT=9999
   puertos:
   - "4500:8888"
   - "8443:9999"
   

2. Para instalar la aplicação de seguimiento y eco http todo en uno de Jaeger. Ejecute este comando:

'docker-compose up -d'

3. Ejecute el comando docker ps -a para verificar si el contenedor está instalado.

$docker ps -a
ID DE CONTENEDOR IMAGEN COMANDO CREADO ESTADO
NOMBRE DE PUERTOS

5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" Hace 30 horas 5775/udp, 5778/tcp, 14250/tcp, 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp, 6831-6832/udp, 14268/tcp Jaeger

e55d9c00a158 mendhak/http-https-echo "docker-entrypoint.s…" hace 11 días. Activo durante 30 horas: 8080/tcp, 8443/tcp, 0.0.0.0:8080->8888/tcp, :::8080->8888/tcp, 0.0.0.0:8443->9999/tcp, :::8443->9999/tcp ubuntu-http-echo-1

Ahora puede acceder a Jaeger simplemente escribiendo el punto final http://localhost:16686 en su navegador. Tenga en cuenta que es posible que no pueda ver ningún dato de seguimiento del sistema de inmediato, ya que actualmente se están enviando a la consola. Pero no te preocupes! Podemos resolver esto rápidamente exportando los rastros en el formato del Protocolo OpenTelemetry (OTLP). Aprenderá a hacer esto en la siguiente sección cuando configuremos NGINX para enviar los seguimientos a Jaeger.

Configurar OpenTelemetry en NGINX para el seguimiento

Esta sección le mostrará paso a paso cómo configurar la directiva OpenTelemetry en NGINX Plus usando un almacén de clave-valor. Esta potente configuración permite un monitoreo y análisis preciso del tráfico, lo que le permite optimizar el rendimiento de su aplicación. Al final de esta sección, tendrá una comprensión sólida del uso del módulo NGINX OpenTelemetry para rastrear el rendimiento de su aplicación.

Configurar la recopilación de telemetría es muy sencillo con los archivos de configuración de NGINX. Con ngx_otel_module , los usuarios pueden acceder a una herramienta de seguimiento robusta y consciente del protocolo que puede ayudar a identificar y resolver rápidamente problemas en las aplicações. Este módulo es una valiosa adición a su conjunto de herramientas de desarrollo y gestión de aplicação y lo ayudará a mejorar el rendimiento de sus aplicações. Para obtener más información sobre cómo configurar otras configuraciones de muestra de OpenTelemetry, consulte la documentación de ngx_otel_module .

Directivas y variables de OpenTelemetry

NGINX tiene nuevas directivas que pueden ayudarlo a lograr una implementación de OpenTelemetry aún más optimizada, adaptada a sus necesidades específicas. Estas directivas fueron diseñadas para mejorar el rendimiento de su aplicación y hacerla más eficiente que nunca.

Directivas del módulo:

1. otel_exporter : establece los parámetros para los datos de OpenTelemetry, incluidos el punto final , el intervalo , el tamaño del lote y el recuento de lotes . Estos parámetros son cruciales para la exportación exitosa de datos y deben definirse con precisión.
2. otel_service_name : establece el atributo de nombre de servicio para su recurso OpenTelemetry para mejorar la organización y el seguimiento.
3. otel_trace – Para habilitar o deshabilitar el seguimiento de OpenTelemetry, ahora puede hacerlo especificando una variable. Esto ofrece flexibilidad en la gestión de su configuración de seguimiento.
4. otel_span_name : el nombre del intervalo de OpenTelemetry se establece como el nombre de ubicación para una solicitud de manera predeterminada. Vale la pena señalar que el nombre es personalizable y puede incluir variables según sea necesario.

Ejemplos de configuración

A continuación se muestran ejemplos de formas en las que puede configurar OpenTelemetry en NGINX utilizando el almacén de clave-valor NGINX Plus. El módulo de almacenamiento de clave-valor NGINX Plus ofrece un caso de uso valioso que permite la configuración dinámica del intervalo de OpenTelemetry y otros atributos de OpenTelemetry, agilizando así el proceso de seguimiento y depuración.

Este es un ejemplo de cómo habilitar dinámicamente el seguimiento de OpenTelemetry mediante un almacén de clave-valor:

http {
keyval "otel.trace" $trace_switch zone=nombre;

servidor {
ubicación / {
otel_trace $trace_switch;
otel_trace_context inject;
proxy_pass http://backend;
}

ubicación /api {
api write=on;
} 
}
}

A continuación, se muestra un ejemplo de desactivación dinámica del seguimiento de OpenTelemetry mediante un almacén de clave-valor:

ubicación /api {
api write=off;
} 

A continuación se muestra un ejemplo de configuración del atributo span de NGINX OpenTelemetry:

usuario nginx;
procesos_de_trabajo automáticos;
módulo de carga módulos/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid /var/run/nginx.pid;


eventos {
conexiones_de_trabajador 1024;
}

http {
keyval "otel.span.attr" $trace_attr zona=demo;
keyval_zone zona=demo:64k estado=/var/lib/nginx/state/demo.keyval;

formato de registro principal '$dirección_remota - $usuario_remoto [$hora_local] "$solicitud" '
'$estado $body_bytes_sent "$http_referer"'
'"$http_user_agent" "$http_x_reenviado_para"';
incluir mime.types;
tipo_predeterminado aplicação/json;
eco ascendente {
servidor localhost:4500;
eco de zona 64k;
}
nombre_servicio_hotel nginx;
exportador_de_hoteles {
punto final localhost:4317;
}

servidor {
escuchar 4000;
otel_trace activado;
otel_span_name hotel;
ubicación/ciudad {
proxy_set_header "Conexión" "" ;
encabezado_conjunto_proxy Host $host;
otel_span_attr demostración $trace_attr;
otel_trace_context inyectar;
proxy_pass <a href="http://echo;">http://echo;</a>
}
ubicación /api {
api write=on;
}
ubicación = /dashboard.html {
raíz /usr/share/nginx/html;
}

}

}

Para guardar la configuración y reiniciar NGINX, ingrese este código:

nginx -s recargar

Por último, aquí se explica cómo agregar el atributo span en la API de NGINX Plus:

curl -X POST -d '{"otel.span.attr": "<nombre del atributo span>"}' http://localhost:4000/api/6/http/keyvals/<nombre de la zona>

Probar la configuración

Ahora, puedes probar tu configuración siguiendo los pasos a continuación.

1. Para generar los datos de seguimiento, comience abriendo la ventana de su terminal. A continuación, escriba este comando para crear los datos:

    

   $ curl -i localhost:4000/ciudad

   La salida se verá así:

                         HTTP/1.1 200 OK
   Servidor: nginx/1.25.3
   Fecha: Mié, 29 nov 2023 20:25:04 GMT
   Tipo de contenido: aplicação/json; conjunto de caracteres=utf-8
   Longitud del contenido: 483
   Conexión: Keep-Alive
   X-Powered-By: Expresar
   ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"
   
   {
   "path": "/ciudad",
   "headers": {
   "host": "localhost",
   "connection": "close",
   "user-agent": "curl/7.81.0",
   "accept": "*/*",
   "traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
   },
   "método": "GET",
   "body": "",
   "fresh": falso,
   "hostname": "localhost",
   "ip": "::ffff:172.18.0.1",
   "ips": [],
   "protocol": "http",
   "query": {},
   "subdomains": [],
   "xhr": falso,
   "os": {
   "hostname": "e55d9c00a158"
   },
   "connection": {}
   

2. Ahora desea asegurarse de que el exportador OTLP esté funcionando correctamente y de que pueda obtener acceso al seguimiento. Comience abriendo un navegador y accediendo a la interfaz de usuario de Jaeger en http://localhost:16686 . Una vez que se cargue la página, haga clic en el botón Buscar , ubicado en la barra de título. Desde allí, seleccione el servicio que comienza con NGINX en el menú desplegable en el campo Servicio . A continuación, seleccione la operación denominada Otel del menú desplegable llamado Operación . Para facilitar la identificación de cualquier problema, haga clic en el botón Buscar rastros para visualizar el rastro.



3. Para acceder a un análisis más detallado y completo de un rastro específico, haga clic en uno de los rastros individuales disponibles. Esto le proporcionará información valiosa sobre el rastro que ha seleccionado. En el seguimiento a continuación, puede revisar tanto el atributo span de la directiva OpenTelemetry como la no directiva del seguimiento, lo que le permitirá comprender mejor los datos disponibles.
   • demo – OTel – Nombre del atributo span de OpenTelemetry
   • Campo http.status_code – 200 – Indica creación exitosa
   • otel.library.name – nginx – Nombre del servicio OpenTelemetry

En Etiquetas puedes ver los siguientes atributos:

CONCLUSIÓN

NGINX ahora tiene soporte integrado para OpenTelemetry, un desarrollo significativo para rastrear solicitudes y respuestas en entornos de aplicação complejos. Esta característica agiliza el proceso y garantiza una integración perfecta, lo que hace que sea mucho más fácil para los desarrolladores supervisar y optimizar sus aplicações.

Aunque el módulo OpenTracing que se introdujo en NGINX Plus R18 ahora está obsoleto y se eliminará a partir de NGINX Plus R34, seguirá estando disponible en todas las versiones de NGINX Plus hasta entonces. Sin embargo, se recomienda utilizar el módulo OpenTelemetry, que se introdujo en NGINX Plus R29 .

Si es nuevo en NGINX Plus, puede comenzar su prueba gratuita de 30 días hoy o contactarnos para analizar sus casos de uso .