Tutorial: configure o OpenTelemetry para suas aplicações usando o NGINX

Akash AnanthanarayananGerente de Marketing Técnico | F5 NGINX

Se você está procurando uma ferramenta para rastrear aplicações web e infraestrutura com mais eficiência, o OpenTelemetry pode ser exatamente o que você precisa. Ao instrumentar seu servidor NGINX com o módulo comunitário OpenTelemetry para NGINX existente, você pode coletar métricas, rastreamentos e logs, além de obter maior visibilidade sobre a integridade do servidor. Isso permite diagnosticar problemas e otimizar suas aplicações web para melhorar o desempenho. No entanto, esse módulo comunitário também pode aumentar o tempo de resposta do servidor devido à sobrecarga de desempenho necessária para o rastreamento. Esse processo também pode consumir recursos adicionais, aumentando o uso de CPU e memória. Além disso, instalar e configurar o módulo pode ser trabalhoso.

A NGINX desenvolveu recentemente um módulo nativo do OpenTelemetry, ngx_otel_module, que revoluciona o rastreamento do desempenho do processamento de requisições. O módulo utiliza chamadas de telemetria para monitorar requisições e respostas de aplicações, oferecendo recursos avançados de rastreamento. Ele pode ser facilmente instalado e configurado nos arquivos de configuração da NGINX, o que o torna muito fácil de usar. Esse novo módulo atende às necessidades dos usuários do NGINX OSS e do NGINX Plus. Ele é compatível com a propagação de contexto W3C e com o protocolo de exportação OTLP/gRPC, sendo uma solução abrangente para otimizar o desempenho.

O módulo OpenTelemetry nativo do NGINX é um módulo dinâmico que não requer nenhum pacote adicional com o NGINX Plus. Ele oferece diversos recursos, incluindo os módulos de API e armazenamento de chave-valor. Esses recursos funcionam em conjunto para fornecer uma solução completa de monitoramento e otimização do desempenho da sua instância do NGINX Plus. Ao usar ngx_otel_module, você pode obter insights valiosos sobre o desempenho da sua aplicação web e tomar medidas para melhorá-lo. Recomendamos fortemente que você conheça o ngx_otel_module para descobrir como ele pode ajudar você a obter melhores resultados.

Observação: Acesse nossa página do GitHub para obter instruções detalhadas sobre como instalar o nginx_otel_module e começar a usá-lo.

Visão geral do tutorial

Neste blog, você pode acompanhar um guia passo a passo sobre como configurar o OpenTelemetry no NGINX Plus e usar a ferramenta Jaeger para coletar e visualizar rastreamentos. OpenTelemetry é uma ferramenta poderosa que oferece uma visão abrangente do caminho percorrido por uma solicitação, incluindo informações valiosas, como latência, detalhes da solicitação e dados da resposta. Isso pode ser extremamente útil para otimizar o desempenho e identificar possíveis problemas. Para simplificar, configuramos o módulo OpenTelemetry, a aplicação e o Jaeger em uma única instância, como você pode ver no diagrama abaixo.

Figura 1: Visão geral da arquitetura do OpenTelemetry no NGINX

Siga as etapas destas seções para concluir o tutorial:

• Pré-requisitos
• Implantar o NGINX Plus e instalar o módulo OpenTelemetry
• Implante o Jaeger e o aplicativo echo Application
• Configure o OpenTelemetry no NGINX para rastreamento
• Teste a configuração

Pré-requisitos

• Um ambiente Linux/Unix ou qualquer ambiente compatível
• Uma assinatura do NGINX Plus
• Conhecimento básico da linha de comando do Linux e de JavaScript
• Docker
• Node.js 19.x ou posterior
• cURL

Implante o NGINX Plus e instale o módulo OpenTelemetry

Selecionar um ambiente adequado é fundamental para implantar com sucesso uma instância do NGINX. Este tutorial orientará você na implantação do NGINX Plus e na instalação dos módulos dinâmicos do NGINX.

1. Instale o NGINX Plus em um sistema operacional compatível.
2. Instale ngx_otel_module. Adicione o módulo dinâmico ao diretório de configuração do NGINX para ativar o OpenTelemetry:

load_module modules/ngx_otel_module.so;

1. Recarregue o NGINX para habilitar o módulo:

nginx -t && nginx -s reload

Implante o Jaeger e o aplicativo echo Application

Há várias opções disponíveis para visualizar rastreamentos. Este tutorial usa o Jaeger para coletar e analisar dados do OpenTelemetry. O Jaeger oferece uma interface eficiente e fácil de usar para coletar e visualizar dados de rastreamento. Após a coleta dos dados, você implantará o mendhak/http-https-echo, uma aplicação Docker simples. Essa aplicação retorna os atributos da solicitação para JavaScript no formato JSON.

1. Use o docker-compose para implantar o Jaeger e o aplicativo http-echo. Você pode criar um arquivo docker-compose copiando a configuração abaixo e salvando-o em um diretório de sua escolha.

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"

1. Para instalar o sistema de rastreamento completo Jaeger e o aplicativo http-echo, execute este comando:

'docker-compose up -d'

1. Execute o comando docker ps -a para verificar se o contêiner 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

Agora você pode acessar o Jaeger simplesmente digitando o endpoint http://localhost:16686 no navegador. Talvez você não consiga visualizar imediatamente os dados de rastreamento do sistema, pois eles estão sendo enviados para o console no momento. Mas não se preocupe! Podemos resolver isso rapidamente exportando os rastreamentos no formato OpenTelemetry Protocol (OTLP). Na próxima seção, você aprenderá a fazer isso ao configurarmos o NGINX para enviar os rastreamentos ao Jaeger.

Configure o OpenTelemetry no NGINX para rastreamento

Esta seção mostrará, passo a passo, como configurar a diretiva OpenTelemetry no NGINX Plus usando um armazenamento de chave-valor. Essa poderosa configuração permite monitorar e analisar o tráfego com precisão, ajudando você a otimizar o desempenho da sua aplicação. Ao final desta seção, você terá uma compreensão sólida de como usar o módulo OpenTelemetry do NGINX para acompanhar o desempenho da sua aplicação.

Configurar a coleta de telemetria é muito fácil com os arquivos de configuração do NGINX. Com o módulo ngx_otel_module, os usuários têm acesso a uma ferramenta de rastreamento robusta e compatível com protocolos, que ajuda a identificar e resolver rapidamente problemas em aplicações. Esse módulo é uma adição valiosa ao seu conjunto de ferramentas de desenvolvimento e gerenciamento de aplicações e ajudará a melhorar o desempenho delas. Para saber mais sobre outras configurações de exemplo do OpenTelemetry, consulte a documentação do ngx_otel_module documentation.

Diretivas e variáveis do OpenTelemetry

O NGINX conta com novas diretivas que podem ajudar você a obter uma implantação do OpenTelemetry ainda mais otimizada e adaptada às suas necessidades específicas. Essas diretivas foram desenvolvidas para melhorar o desempenho da sua aplicação e torná-la mais eficiente do que nunca.

Diretivas do módulo:

1. otel_exporter – Define os parâmetros dos dados do OpenTelemetry, incluindo endpoint, interval, batch size, e batch count. Esses parâmetros são essenciais para a exportação bem-sucedida dos dados e devem ser definidos com precisão.
2. otel_service_name – Define o atributo de nome do serviço para o recurso do OpenTelemetry, melhorando a organização e o rastreamento.
3. otel_trace – Para habilitar ou desabilitar o rastreamento do OpenTelemetry, agora você pode especificar uma variável. Isso oferece flexibilidade no gerenciamento das configurações de rastreamento.
4. otel_span_name – Por padrão, o nome do span do OpenTelemetry é definido como o nome do local de uma solicitação. Vale ressaltar que esse nome pode ser personalizado e incluir variáveis conforme necessário.

Exemplos de configuração

Veja alguns exemplos de como configurar o OpenTelemetry no NGINX usando o armazenamento de chave-valor do NGINX Plus. O módulo de armazenamento de chave-valor do NGINX Plus oferece um caso de uso valioso que permite configurar dinamicamente spans e outros atributos do OpenTelemetry, simplificando assim o processo de rastreamento e depuração.

Este é um exemplo de como habilitar dinamicamente o rastreamento do OpenTelemetry usando um armazenamento de chave-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 seguir, veja um exemplo de como desabilitar dinamicamente o rastreamento do OpenTelemetry usando um armazenamento de chave-valor:

location /api {
              api write=off;
          } 

Veja um exemplo de configuração de atributos de span do OpenTelemetry no 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 salvar a configuração e reiniciar o NGINX, insira este código:

nginx -s reload

Por fim, veja como adicionar um atributo de span à API do NGINX Plus:

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

Teste a configuração

Agora, você pode testar sua configuração seguindo as etapas abaixo.

1. Para gerar os dados de rastreamento, comece abrindo uma janela do terminal. Em seguida, digite este comando para criar os dados: $ curl -i localhost:4000/city A saída será semelhante a esta:

                      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": {}

1. Agora, você deve verificar se o exportador OTLP está funcionando corretamente e se é possível acessar o rastreamento. Comece abrindo um navegador e acessando a interface do Jaeger em http://localhost:16686. Após o carregamento da página, clique no botão Pesquisar, localizado na barra de título. Em seguida, selecione o serviço cujo nome começa com NGINX no menu suspenso do campo Serviço. Depois, selecione a operação chamada Otel no menu suspenso Operação. Para facilitar a identificação de possíveis problemas, clique no botão Localizar rastreamentos para visualizar o rastreamento.

Figura 2: Painel do Jaeger

1. Para acessar uma análise mais detalhada e abrangente de um trace específico, clique em um dos traces individuais disponíveis. Isso fornecerá informações valiosas sobre o trace selecionado. No trace abaixo, você pode analisar tanto o atributo de span da diretiva OpenTelemetry quanto o atributo que não pertence à diretiva, o que permite compreender melhor os dados apresentados.
   • demo – OTel – nome do atributo de span do OpenTelemetry
   • campo http.status_code – 200 – Indica que a criação foi bem-sucedida
   • otel.library.name – nginx – Nome do serviço OpenTelemetry

Figura 3: análise detalhada do rastreamento do OpenTelemetry

Em Tags você pode ver os seguintes atributos:

Conclusão

O NGINX agora oferece suporte nativo ao OpenTelemetry, um avanço significativo para o rastreamento de solicitações e respostas em ambientes de aplicações complexos. Esse recurso simplifica o processo e garante uma integração perfeita, facilitando muito o monitoramento e a otimização das aplicações pelos desenvolvedores.

Embora o módulo OpenTracing, introduzido no NGINX Plus R18, esteja obsoleto e seja removido a partir do NGINX Plus R34, ele continuará disponível em todas as versões do NGINX Plus até lá. No entanto, recomenda-se usar o módulo OpenTelemetry, que foi introduzido no NGINX Plus R29.

Se você ainda não conhece o NGINX Plus, pode iniciar hoje mesmo sua avaliação gratuita de 30 dias ou entrar em contato conosco para conversar sobre seus casos de uso.

Sobre o autor

Akash AnanthanarayananGerente de Marketing Técnico | F5 NGINX

Mais publicações de Akash Ananthanarayanan