Tutorial: Configura OpenTelemetry para tus aplicaciones con NGINX

NGINX | 18 de enero de 2024

Akash AnanthanarayananResponsable de marketing técnico | F5 NGINX

Si busca una herramienta para rastrear aplicaciones web e infraestructuras de forma más eficaz, OpenTelemetry podría ser justo lo que necesita. Al instrumentar su servidor NGINX con el módulo comunitario de OpenTelemetry para NGINX existente, puede recopilar métricas, trazas y registros, y obtener una mayor visibilidad del estado de su servidor. Esto, a su vez, le permite solucionar problemas y optimizar sus aplicaciones web para mejorar su rendimiento. Sin embargo, este módulo comunitario también puede ralentizar los tiempos de respuesta de su servidor debido a la sobrecarga de rendimiento que requiere el rastreo. Este proceso también puede consumir recursos adicionales, lo que aumenta el uso de la CPU y la memoria. Además, instalar y configurar el módulo puede resultar complicado.

NGINX ha desarrollado recientemente un módulo nativo de OpenTelemetry, ngx_otel_module, que revoluciona el seguimiento del rendimiento del procesamiento de solicitudes. El módulo utiliza llamadas de telemetría para supervisar las solicitudes y respuestas de las aplicaciones, lo que permite mejorar las capacidades de seguimiento. Se puede instalar y configurar fácilmente en los archivos de configuración de NGINX, por lo que resulta muy sencillo de usar. Este nuevo módulo responde a las necesidades de los usuarios tanto de NGINX OSS como de 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 diversas funcionalidades, incluidos los módulos de API y de almacenamiento de pares clave-valor. Estas funcionalidades trabajan conjuntamente para proporcionar una solución completa que permite supervisar y optimizar el rendimiento de su instancia de NGINX Plus. Al utilizar ngx_otel_module, puede obtener información valiosa sobre el rendimiento de su aplicación web y tomar medidas para mejorarlo. Recomendamos encarecidamente explorar ngx_otel_module para descubrir cómo puede ayudarle a obtener mejores resultados.

Nota: Puedes visitar nuestra página de GitHub para consultar instrucciones detalladas sobre cómo instalar nginx_otel_module y empezar a utilizarlo.

Descripción general del tutorial

En este blog encontrarás una guía paso a paso para configurar OpenTelemetry en NGINX Plus y utilizar la herramienta Jaeger para recopilar y visualizar trazas. OpenTelemetry es una potente herramienta que ofrece una visión completa del recorrido de una solicitud, incluida información valiosa como la latencia, los detalles de la solicitud y los datos de la respuesta. Esto puede resultar sumamente útil para optimizar el rendimiento e identificar posibles problemas. Para simplificar el proceso, hemos configurado el módulo de OpenTelemetry, la aplicación y Jaeger en una única instancia, como se muestra en el siguiente diagrama.

Figura 1: Descripción general de la arquitectura de OpenTelemetry de NGINX

Sigue los pasos de estas secciones para completar el tutorial:

Requisitos previos
Implementar NGINX Plus e instalar el módulo OpenTelemetry
Implemente Jaeger y la aplicación echo Application
Configurar OpenTelemetry en NGINX para el rastreo
Probar la configuración

Requisitos previos

Un entorno Linux/Unix o cualquier entorno compatible
Una suscripción a NGINX Plus
Conocimientos básicos de la línea de comandos de Linux y de JavaScript
Docker
Node.js 19.x o posterior
Curl

Implementar NGINX Plus e instalar el módulo OpenTelemetry

Seleccionar un entorno adecuado es fundamental para implementar correctamente una instancia de NGINX. En este tutorial, aprenderá a implementar NGINX Plus e instalar los módulos dinámicos de NGINX.

Instale NGINX Plus en un sistema operativo compatible.
Instale ngx_otel_module. Añada el módulo dinámico al directorio de configuración de NGINX para activar OpenTelemetry:

load_module modules/ngx_otel_module.so;

Recargue NGINX para habilitar el módulo:

nginx -t && nginx -s reload

Desplegar Jaeger y la aplicación `echo` Application

Hay varias opciones disponibles para visualizar las trazas. En este tutorial se 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 trazas. Tras recopilar los datos, desplegará mendhak/http-https-echo, una sencilla aplicación de Docker. Esta aplicación devuelve los atributos de la solicitud para JavaScript en formato JSON.

Utiliza docker-compose para desplegar Jaeger y la aplicación http-echo. Puedes crear un archivo de docker-compose copiando la configuración que aparece a continuación y guardándolo en el directorio que prefieras.

version: '3'

Services:
  jaeger:
    image: jaegertracing/all-in-one:1.41
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      COLLECTOR_OTLP_ENABLED: true

  http-echo:
    image: mendhak/http-https-echo
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "4500:8888" 
        - "8443:9999"

Para instalar el sistema de rastreo todo en uno Jaeger y la aplicación http-echo, ejecuta este comando:

'docker-compose up -d'

Ejecute el comando de Docker «ps -a» para comprobar si el contenedor está instalado.

$docker ps -a
CONTAINER ID   IMAGE                           COMMAND                  CREATED        STATUS
PORTS                                                                                                                                                                   NAMES

5cb7763439f8   jaegertracing/all-in-one:1.41   "/go/bin/all-in-one-…"   30 hours ago   Up 30 hours   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…"   11 days ago    Up 30 hours   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 puedes acceder a Jaeger simplemente introduciendo en tu navegador el endpoint http://localhost:16686. Ten en cuenta que es posible que no veas de inmediato ningún dato de trazas del sistema, ya que actualmente se envía a la consola. Pero no te preocupes. Podemos solucionarlo rápidamente exportando las trazas en formato OpenTelemetry Protocol (OTLP). En la siguiente sección aprenderás a hacerlo cuando configuremos NGINX para enviar las trazas a Jaeger.

Configurar OpenTelemetry en NGINX para el rastreo

En esta sección se explica paso a paso cómo configurar la directiva OpenTelemetry en NGINX Plus mediante un almacén de clave-valor. Esta potente configuración permite supervisar y analizar el tráfico con precisión, lo que le ayudará a optimizar el rendimiento de su aplicación. Al finalizar esta sección, comprenderá claramente cómo utilizar el módulo OpenTelemetry de NGINX para realizar un seguimiento del 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 sólida herramienta de rastreo compatible con protocolos que ayuda a identificar y resolver rápidamente problemas en las aplicaciones. Este módulo es una valiosa incorporación a su conjunto de herramientas de desarrollo y gestión de aplicaciones y le ayudará a mejorar el rendimiento de sus aplicaciones. Para obtener más información sobre cómo configurar otros ejemplos de configuración de OpenTelemetry, consulte la documentación de ngx_otel_module.

Directivas y variables de OpenTelemetry

NGINX incorpora nuevas directivas que pueden ayudarle a conseguir una implementación de OpenTelemetry aún más optimizada y adaptada a sus necesidades específicas. Estas directivas se han diseñado para mejorar el rendimiento de su aplicación y hacerla más eficiente que nunca.

Directivas del módulo:

otel_exporter – Establece los parámetros de los datos de OpenTelemetry, incluidos endpoint, interval, batch size y batch count. Estos parámetros son fundamentales para exportar correctamente los datos y deben definirse con precisión.
otel_service_name – Establece el atributo de nombre del servicio para el recurso de OpenTelemetry a fin de mejorar la organización y el seguimiento.
otel_trace – Para activar o desactivar el seguimiento de OpenTelemetry, ahora puede especificar una variable. Esto ofrece flexibilidad a la hora de gestionar la configuración del seguimiento.
otel_span_name – De forma predeterminada, el nombre del intervalo de OpenTelemetry se establece como el nombre de la ubicación de una solicitud. Cabe señalar que el nombre se puede personalizar y puede incluir variables según sea necesario.

Ejemplos de configuración

A continuación se muestran ejemplos de cómo puede configurar OpenTelemetry en NGINX mediante el almacén de pares clave-valor de NGINX Plus. El módulo de almacén de pares clave-valor de NGINX Plus ofrece un caso de uso muy útil que permite configurar dinámicamente los intervalos y otros atributos de OpenTelemetry, lo que agiliza el proceso de rastreo 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=name;

      server {
          location / {
              otel_trace $trace_switch;
              otel_trace_context inject;
              proxy_pass http://backend;
          }

          location /api {
              api write=on;
          } 
      }
  }

A continuación, se muestra un ejemplo de cómo deshabilitar dinámicamente el seguimiento de OpenTelemetry mediante un almacén de clave-valor:

location /api {
              api write=off;
          }

Este es un ejemplo de configuración de atributos de span de OpenTelemetry para NGINX:

user  nginx;
worker_processes  auto;
load_module modules/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid   /var/run/nginx.pid;


events {
    worker_connections  1024;
}

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

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    include       mime.types;
    default_type  application/json;
    upstream echo {
        server localhost:4500;
        zone echo 64k;
    }
    otel_service_name nginx;
    otel_exporter {
           endpoint localhost:4317;
        }

    server {
       listen       4000;
       otel_trace on;
       otel_span_name otel;
       location /city {
            proxy_set_header   "Connection" "" ;
            proxy_set_header Host $host;
            otel_span_attr demo $trace_attr;
            otel_trace_context inject;
            proxy_pass http://echo;
       }
       location /api {
           api write=on;
       }
       location = /dashboard.html {
        root /usr/share/nginx/html;
    }
       
  }

}

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

nginx -s reload

Por último, así se añade un atributo de span en la API de NGINX Plus:


curl -X POST -d '{"otel.span.attr": "<span attribute name>"}' http://localhost:4000/api/6/http/keyvals/<zone name>

Probar la configuración

Ahora puede probar su configuración siguiendo los pasos que se indican a continuación.

Para generar los datos de traza, empieza abriendo una ventana del terminal. A continuación, introduce este comando para crear los datos: $ curl -i localhost:4000/city El resultado tendrá este aspecto:

                      HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Wed, 29 Nov 2023 20:25:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 483
Connection: keep-alive
X-Powered-By: Express
ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"

{
"path": "/city",
"headers": {
"host": "localhost",
"connection": "close",
"user-agent": "curl/7.81.0",
"accept": "*/*",
"traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
},
"method": "GET",
"body": "",
"fresh": false,
"hostname": "localhost",
"ip": "::ffff:172.18.0.1",
"ips": [],
"protocol": "http",
"query": {},
"subdomains": [],
"xhr": false,
"os": {
"hostname": "e55d9c00a158"
},
"connection": {}

Ahora debes asegurarte de que el exportador OTLP funciona correctamente y de que puedes acceder a la traza. Para empezar, abre un navegador y accede a la interfaz de usuario de Jaeger en http://localhost:16686. Cuando se cargue la página, haz clic en el botón Buscar, situado en la barra de título. A continuación, selecciona el servicio cuyo nombre empieza por NGINX en el menú desplegable del campo Servicio. Después, selecciona la operación denominada Otel en el menú desplegable Operación. Para facilitar la identificación de posibles problemas, haz clic en el botón Buscar trazas para visualizar la traza.

Figura 2: Panel de Jaeger

Para acceder a un análisis más detallado y completo de una traza específica, haga clic en una de las trazas disponibles. Esto le proporcionará información valiosa sobre la traza seleccionada. En la siguiente traza, puede consultar tanto el atributo de intervalo de la directiva OpenTelemetry como el elemento de la traza que no corresponde a la directiva, lo que le permitirá comprender mejor los datos disponibles.
- demo – OTel – nombre del atributo de span de OpenTelemetry
- Campo http.status_code – 200 – Indica que la creación se ha realizado correctamente
- otel.library.name – nginx – Nombre del servicio de OpenTelemetry

Figura 3: Análisis detallado de la traza de OpenTelemetry

En Etiquetas puedes ver los siguientes atributos:

Conclusión

NGINX ahora ofrece compatibilidad integrada con OpenTelemetry, un avance importante para el seguimiento de solicitudes y respuestas en entornos de aplicaciones complejos. Esta funcionalidad simplifica el proceso y garantiza una integración fluida, lo que facilita considerablemente a los desarrolladores la supervisión y optimización de sus aplicaciones.

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

Si es la primera vez que utiliza NGINX Plus, puede iniciar hoy mismo su prueba gratuita de 30 días o ponerse en contacto con nosotros para hablar sobre sus casos de uso.