Pular para conteúdo

otel: Módulo dinâmico NGINX OpenTelemetry

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-otel

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-otel

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_otel_module.so;

Este documento descreve o nginx-module-otel v0.1.2 lançado em 15 de março de 2025.

O que é OpenTelemetry

OpenTelemetry (OTel) é uma estrutura de observabilidade para monitorar, rastrear, solucionar problemas e otimizar aplicações. O OTel permite a coleta de dados de telemetria de uma pilha de aplicações implantadas.

O que é o Módulo Nativo OTel do NGINX

O módulo dinâmico ngx_otel_module permite que o NGINX Open Source ou NGINX Plus envie dados de telemetria para um coletor OTel. Ele fornece suporte para a propagação do contexto de rastreamento W3C, exportações de rastreamento OpenTelemetry Protocol (OTLP)/gRPC e oferece vários benefícios em relação aos módulos OTel existentes, incluindo:

Melhor Desempenho

Implementações OTel de terceiros reduzem o desempenho do processamento de solicitações em até 50% quando o rastreamento está habilitado. O módulo Nativo do NGINX limita esse impacto a aproximadamente 10-15%.

Provisionamento Fácil

A configuração pode ser feita diretamente nos arquivos de configuração do NGINX.

Controle Dinâmico Baseado em Variáveis

A capacidade de controlar parâmetros de rastreamento dinamicamente usando cookies, tokens e variáveis. Consulte nosso exemplo de Rastreamento Baseado em Proporção para mais detalhes.

Além disso, o NGINX Plus, disponível como parte de uma assinatura comercial, permite o controle dinâmico dos parâmetros de amostragem através da API do NGINX Plus e dos módulos de armazenamento chave-valor.

Habilitando o Módulo OTel

Seguir os passos de instalação acima instalará o módulo em /etc/nginx/modules por padrão. Carregue o módulo adicionando a seguinte linha ao topo do arquivo de configuração principal do NGINX, localizado em /etc/nginx/nginx.conf.

load_module modules/ngx_otel_module.so;

Configurando o Módulo

Para uma lista completa de diretivas, variáveis incorporadas, atributos de span padrão e configurações de exemplo, consulte a documentação do ngx_otel_module.

Exemplos

Use estes exemplos para configurar alguns casos de uso comuns para rastreamento OTel.

Rastreamento Simples

Este exemplo envia dados de telemetria para todas as solicitações http.

http {
    otel_exporter {
        endpoint localhost:4317;
    }

    otel_trace on;

    server {
        location / {
            proxy_pass http://backend;
        }
    }
}

Rastreamento Baseado em Pai

Neste exemplo, herdamos contextos de rastreamento de solicitações recebidas e registramos spans apenas se um span pai for amostrado. Também propagamos contextos de rastreamento e decisões de amostragem para servidores upstream.

http {
    server {
        location / {
            otel_trace $otel_parent_sampled;
            otel_trace_context propagate;

            proxy_pass http://backend;
        }
    }
}

Rastreamento Baseado em Proporção

Neste exemplo baseado em proporção, o rastreamento é configurado para uma porcentagem do tráfego (neste caso 10%):

http {
    # rastrear 10% das solicitações
    split_clients $otel_trace_id $ratio_sampler {
        10%     on;
        *       off;
    }

    # ou podemos rastrear 10% das sessões de usuário
    split_clients $cookie_sessionid $session_sampler {
        10%     on;
        *       off;
    }

    server {
        location / {
            otel_trace $ratio_sampler;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

Coletando e Visualizando Rastros

Existem vários métodos e pacotes de software disponíveis para visualizar rastros. Para um início rápido, o Jaeger fornece um contêiner tudo-em-um para coletar, processar e visualizar dados de rastreamento OTel. Siga estas etapas para baixar, instalar, iniciar e usar os serviços OTel do Jaeger.

Registro de Alterações

Veja nossa página de lançamentos para acompanhar as atualizações.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub do nginx-module-otel.