Tutorial: Configure o OpenTelemetry para seus aplicativos usando o NGINX
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.
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.
- Instale o NGINX Plus em um sistema operacional compatível .
- Instalar
ngx_otel_module. Adicione o módulo dinâmico ao diretório de configuração do NGINX para ativar o OpenTelemetry: - Recarregue o NGINX para habilitar o módulo:
load_module módulos/ngx_otel_module.so;
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.
- Use
o docker-composepara implantar o Jaeger e o aplicativohttp-echo. Você pode criar um arquivodocker-composecopiando a configuração abaixo e salvando-a 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" - Para instalar o aplicativo de rastreamento e
http-echotudo-em-um Jaeger. Execute este comando: - Execute o comando docker
ps -apara verificar se o contêiner está instalado.
'docker-compose up -d'
$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 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:
otel_exporter– Define os parâmetros para dados OpenTelemetry, incluindoendpoint,interval,batch sizeebatch count. Esses parâmetros são cruciais para o sucesso da exportação de dados e devem ser definidos com precisão.otel_service_name– Define o atributo de nome de serviço para seu recurso OpenTelemetry para melhorar a organização e o rastreamento.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.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 zone=name;
server {
location / {
otel_trace $trace_switch;
otel_trace_context inject;
proxy_pass http://backend;
}
location /api {
api write=on;
}
}
}
A seguir, aqui está um exemplo de desabilitação dinâmica do rastreamento OpenTelemetry usando um armazenamento de chave-valor:
location /api {
api write=off;
}
Aqui está um exemplo de configuração de atributo span do NGINX OpenTelemetry:
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 recarregar
Por fim, veja como adicionar o atributo span na 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 os passos abaixo.
- 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/cidadeA saída ficará assim:
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": {} - 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. - 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 OpenTelemetryCampo http.status_code – 200– Indica criação bem-sucedidaotel.library.name – nginx– nome do serviço 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."