BLOG | NGINX

Tutorial: Configure o OpenTelemetry para seus aplicativos usando o NGINX

NGINX-Parte-de-F5-horiz-preto-tipo-RGB
Miniatura de Akash Ananthanarayanan
Akash Ananthanarayanan
Publicado em 18 de janeiro de 2024

Se você está procurando uma ferramenta para rastrear aplicativos e infraestrutura da web de forma mais eficaz, o OpenTelemetry pode ser exatamente o que você precisa. Ao instrumentar seu servidor NGINX com o módulo de comunidade OpenTelemetry NGINX existente, você pode coletar métricas, rastreamentos e logs e obter melhor visibilidade da integridade do seu servidor. Isso, por sua vez, permite que você solucione problemas e otimize seus aplicativos web para melhor desempenho. No entanto, esse módulo comunitário existente também pode diminuir o tempo de resposta do seu 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 um incômodo.

A NGINX desenvolveu recentemente um módulo nativo OpenTelemetry, ngx_otel_module , que revoluciona o rastreamento do desempenho do processamento de solicitações. O módulo utiliza chamadas de telemetria para monitorar solicitações e respostas de aplicativos, permitindo recursos de rastreamento aprimorados. O módulo pode ser convenientemente instalado e configurado dentro dos arquivos de configuração do NGINX, o que o torna altamente fácil de usar. Este novo módulo atende às necessidades dos usuários do NGINX OSS e do NGINX Plus. Ele suporta propagação de contexto W3C e protocolo de exportação OTLP/gRPC, tornando-o 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 uma variedade de recursos, incluindo a API e os módulos de armazenamento de chave-valor. Esses recursos funcionam juntos para fornecer uma solução completa para monitorar e otimizar o desempenho da sua instância do NGINX Plus. Ao usar ngx_otel_module , você pode obter insights valiosos sobre o desempenho do seu aplicativo web e tomar medidas para melhorá-lo. É altamente recomendável explorar o ngx_otel_module para descobrir como ele pode ajudar você a obter melhores resultados.

Observação:  Você pode acessar nossa página do GitHub para obter instruções detalhadas sobre como instalar o nginx_otel_module e começar.

Visão geral do tutorial

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

Diagrama do módulo de telemetria aberta
Figura 1: Visão geral da arquitetura NGINX OpenTelemetry

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

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

Pré-requisitos

  • Um ambiente Linux/Unix ou qualquer ambiente compatível
  • Uma assinatura NGINX Plus
  • Familiaridade básica com a linha de comando do Linux e JavaScript
  • Docker
  • Node.js 19.x ou posterior
  • Enrolar

Implante o NGINX Plus e instale o módulo OpenTelemetry

Selecionar um ambiente apropriado é crucial 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. Instalar ngx_otel_module . Adicione o módulo dinâmico ao diretório de configuração do NGINX para ativar o OpenTelemetry:
  3. load_module módulos/ngx_otel_module.so;

  4. Recarregue o NGINX para habilitar o módulo:
  5. nginx -t && nginx -s recarregar

Implantar Jaeger e o aplicativo echo

Há várias opções disponíveis para visualizar rastros. Este tutorial usa o Jaeger para coletar e analisar dados do OpenTelemetry. A Jaeger fornece uma interface eficiente e fácil de usar para coletar e visualizar dados de rastreamento. Após a coleta de dados, você implantará mendhak/http-https-echo , um aplicativo Docker simples. Este aplicativo retorna os atributos de 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-a em um diretório de sua escolha.

     

    versão: '3'
    
    Serviços:
    jaeger:
    imagem: jaegertracing/all-in-one:1.41
    nome_do_contêiner: jaeger
    portas:
    - "16686:16686"
    - "4317:4317"
    - "4318:4318"
    ambiente:
          COLLECTOR_OTLP_ENABLED: verdadeiro
    
    http-echo:
    imagem: mendhak/http-https-echo
    ambiente:
    - HTTP_PORT=8888
    - HTTPS_PORT=9999
    portas:
    - "4500:8888" 
    - "8443:9999"
    
  2. Para instalar o aplicativo de rastreamento e http-echo tudo-em-um Jaeger. Execute este comando:
  3. 'docker-compose up -d'

  4. Execute o comando docker ps -a para verificar se o contêiner está instalado.
  5. $docker ps -a
    ID DO CONTÊINER IMAGEM COMANDO CRIADO STATUS
    NOMES DAS PORTAS
    
    5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" 30 horas atrás Ativo 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…" 11 dias atrás Ativo há 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
    

    Agora você pode acessar o Jaeger simplesmente digitando o endpoint http://localhost:16686 no seu navegador. Observe que talvez você não consiga ver nenhum dado de rastreamento do sistema imediatamente, pois ele está sendo enviado para o console. Mas não se preocupe! Podemos resolver isso rapidamente exportando os rastros no formato OpenTelemetry Protocol (OTLP). Você aprenderá a fazer isso na próxima seção, quando configurarmos o NGINX para enviar os rastros ao Jaeger.

Configurar 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. Esta configuração poderosa permite monitoramento e análise precisos do tráfego, permitindo que você otimize o desempenho do seu aplicativo. Ao final desta seção, você terá uma sólida compreensão da utilização do módulo NGINX OpenTelemetry para monitorar o desempenho do seu aplicativo.

Configurar e configurar a coleta de telemetria é muito fácil com os arquivos de configuração do NGINX. Com o ngx_otel_module , os usuários podem acessar uma ferramenta de rastreamento robusta e com reconhecimento de protocolo que pode ajudar a identificar e resolver rapidamente problemas em aplicativos. Este módulo é uma adição valiosa ao seu conjunto de ferramentas de desenvolvimento e gerenciamento de aplicativos e ajudará você a melhorar o desempenho dos seus aplicativos. Para saber mais sobre como configurar outras configurações de exemplo do OpenTelemetry, consulte a documentação ngx_otel_module .

Diretivas e variáveis do OpenTelemetry

O NGINX tem novas diretivas que podem ajudar você a obter uma implantação OpenTelemetry ainda mais otimizada, adaptada às suas necessidades específicas. Essas diretivas foram projetadas para melhorar o desempenho do seu aplicativo e torná-lo mais eficiente do que nunca.

Diretivas do módulo:

  1. otel_exporter – Define os parâmetros para dados OpenTelemetry, incluindo endpoint , interval , batch size e batch count . Esses parâmetros são cruciais para o sucesso da exportação de dados e devem ser definidos com precisão.
  2. otel_service_name – Define o atributo de nome de serviço para seu recurso OpenTelemetry para melhorar a organização e o rastreamento.
  3. otel_trace – Para habilitar ou desabilitar o rastreamento do OpenTelemetry, agora você pode fazer isso especificando uma variável. Isso oferece flexibilidade no gerenciamento de suas configurações de rastreamento.
  4. otel_span_name – O nome do intervalo OpenTelemetry é definido como o nome do local para uma solicitação por padrão. Vale ressaltar que o nome é personalizável e pode incluir variáveis conforme necessário.

Exemplos de configuração

Aqui estão exemplos de maneiras de configurar o OpenTelemetry no NGINX usando o armazenamento de chave-valor do NGINX Plus. O módulo de armazenamento de chave-valor NGINX Plus oferece um caso de uso valioso que permite a configuração dinâmica do intervalo OpenTelemetry e outros atributos OpenTelemetry, simplificando assim o processo de rastreamento e depuração.

Este é um exemplo de ativação dinâmica do rastreamento OpenTelemetry usando um armazenamento de chave-valor:

http {
keyval "otel.trace" $trace_switch zona=nome;

servidor {
localização / {
otel_trace $trace_switch;
otel_trace_context inject;
proxy_pass http://backend;
}

localização /api {
api write=on;
} 
}
}

A seguir, aqui está um exemplo de desabilitação dinâmica do rastreamento OpenTelemetry usando um armazenamento de chave-valor:

localização /api {
api write=off;
} 

Aqui está um exemplo de configuração de atributo span do NGINX OpenTelemetry:

usuário nginx;
processos_de_trabalhador auto;
módulo_de_carregamento módulos/ngx_otel_module.so;
log_de_erros /var/log/nginx debug;
pid /var/run/nginx.pid;

eventos {
conexões_de_trabalhador 1024;
}

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

formato_de_log principal '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
incluir mime.types;
tipo_padrão aplicação/json;
upstream echo {
servidor localhost:4500;
zona echo 64k;
}
otel_service_name nginx;
otel_exporter {
endpoint localhost:4317;
}

servidor {
listen 4000;
otel_trace on;
otel_span_name otel;
localização /cidade {
proxy_set_header "Conexão" "" ;
proxy_set_header Host $host;
otel_span_attr demo $trace_attr;
otel_trace_context inject;
proxy_pass http://echo;
}
localização /api {
api write=on;
}
localização = /dashboard.html {
root /usr/share/nginx/html;
}

}

}

Para salvar a configuração e reiniciar o NGINX, insira este código:

nginx -s recarregar

Por fim, veja como adicionar o atributo span na API do NGINX Plus:


curl -X POST -d '{"otel.span.attr": "<nome do atributo span>"}' http://localhost:4000/api/6/http/keyvals/<nome da zona>



Teste a configuração

Agora, você pode testar sua configuração seguindo os passos abaixo.

  1. Para gerar os dados de rastreamento, comece abrindo a janela do terminal. Em seguida, digite este comando para criar os dados:

     

    $ curl -i localhost:4000/cidade

    A saída ficará assim:

                          HTTP/1.1 200 OK
    Servidor: nginx/1.25.3
    Data: Qua, 29 de nov de 2023 20:25:04 GMT
    Tipo de conteúdo: application/json; charset=utf-8
    Comprimento do conteúdo: 483
    Conexão: keep-alive
    X-Powered-By: Expresso
    ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"
    
    {
    "caminho": "/cidade",
    "cabeçalhos": {
    "host": "localhost",
    "conexão": "fechar",
    "agente-usuário": "curl/7.81.0",
    "aceitar": "*/*",
    "traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
    },
    "método": "OBTER",
    "corpo": "",
    "fresco": falso,
    "nome do host": "localhost",
    "ip": "::ffff:172.18.0.1",
    "ips": [],
    "protocolo": "http",
    "consulta": {},
    "subdomínios": [],
    "xhr": falso,
    "os": {
    "nome do host": "e55d9c00a158"
    },
    "conexão": {}
    
  2. Agora você quer garantir que o exportador OTLP esteja funcionando corretamente e que você possa obter acesso ao rastreamento. Comece abrindo um navegador e acessando a interface do usuário do Jaeger em http://localhost:16686 . Quando a página carregar, clique no botão Pesquisar , localizado na barra de título. A partir daí, selecione o serviço que começa com NGINX no menu suspenso no campo Serviço . Em seguida, selecione a operação chamada Otel no menu suspenso chamado Operação . Para facilitar a identificação de quaisquer problemas, clique no botão Encontrar rastros para visualizar o rastro.
  3. Painel de instrumentos Jaeger
    Figura 2: Painel de instrumentos Jaeger
  4. Para acessar uma análise mais detalhada e abrangente de um traço específico, clique em um dos traços individuais disponíveis. Isso lhe dará informações valiosas sobre o traço que você selecionou. No rastreamento abaixo, você pode revisar tanto o atributo span da diretiva OpenTelemetry quanto o atributo não diretivo do rastreamento, permitindo que você entenda melhor os dados em questão.
    • demo – OTel – Nome do atributo span do OpenTelemetry
    • Campo http.status_code – 200 – Indica criação bem-sucedida
    • otel.library.name – nginx – nome do serviço OpenTelemetry
  5. Figura 3: Análise detalhada do rastreamento OpenTelemetry

    Em Tags você pode ver os seguintes atributos:

Conclusão

O NGINX agora tem suporte integrado para OpenTelemetry, um desenvolvimento significativo para rastrear solicitações e respostas em ambientes de aplicativos complexos. Esse recurso simplifica o processo e garante uma integração perfeita, tornando muito mais fácil para os desenvolvedores monitorar e otimizar seus aplicativos.

Embora o módulo OpenTracing introduzido no NGINX Plus R18 esteja obsoleto e será removido a partir do NGINX Plus R34, ele ainda estará disponível em todas as versões do NGINX Plus até então. No entanto, é recomendável usar o módulo OpenTelemetry, que foi introduzido no NGINX Plus R29 .

Se você é novo no NGINX Plus, pode começar seu teste gratuito de 30 dias hoje mesmo ou entrar em contato conosco para discutir seus casos de uso .


"Esta postagem do blog pode fazer referência a produtos que não estão mais disponíveis e/ou não têm mais suporte. Para obter as informações mais atualizadas sobre os produtos e soluções F5 NGINX disponíveis, explore nossa família de produtos NGINX . O NGINX agora faz parte do F5. Todos os links anteriores do NGINX.com redirecionarão para conteúdo semelhante do NGINX no F5.com."