graphite: Um módulo NGINX para coletar estatísticas no Graphite

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-graphite

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-graphite

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

load_module modules/ngx_http_graphite_module.so;

Este documento descreve o nginx-module-graphite v4.3 lançado em 20 de janeiro de 2023.

---

Um módulo nginx para coletar estatísticas de localização no Graphite.

Recursos

• Agregação de métricas de localização, servidor ou http
• Cálculo de percentis
• Envio de dados para o Graphite via UDP ou TCP de forma não bloqueante
• Envio de métricas personalizadas do Lua

Sinopse

http {
    graphite_config prefix=playground server=127.0.0.1;
    server {
        location /foo/ {
            graphite_data nginx.foo;
        }
    }
}

Descrição

Este módulo utiliza um segmento de memória compartilhada para coletar estatísticas agregadas de todos os workers e enviar os valores calculados do último minuto para o Graphite a cada 60 segundos (padrão) via UDP ou TCP de forma não bloqueante. A agregação de estatísticas é feita em tempo real em um buffer de tamanho fixo alocado na inicialização do servidor e não afeta o desempenho do servidor.

Este módulo está em uso ativo nos Mail.Ru Sites (um dos maiores serviços web na Rússia) há cerca de um ano e é considerado estável e bem testado.

Para coletar métricas dos módulos principais do nginx (ssl, gzip, upstream), um pequeno patch deve ser aplicado na árvore de código-fonte do nginx. Veja as instruções de instalação. Você pode compilar este módulo como um módulo dinâmico, mas então não será capaz de coletar métricas dos módulos principais do nginx (ssl, gzip, upstream) e funções do Lua.

Diretrizes

graphite_config

sintaxe: graphite_config key1=<value1> key2=<value2> ... keyN=<valueN>

contexto: http

Especifique configurações globais para toda a instância do servidor.

Parâmetro	Obrigatório	Padrão	Descrição
prefixo			prefixo de caminho para todos os gráficos
host		gethostname()	nome do host para todos os gráficos
servidor	Sim		endereço IP do servidor carbon-cache
protocolo		udp	protocolo do servidor carbon-cache (udp ou tcp)
porta		2003	porta do servidor carbon-cache
frequência		60	com que frequência enviar valores para o Graphite (segundos)
intervalos		1m	intervalos de agregação, lista de intervalos de tempo, separador de barra vertical (m - minutos)
parâmetros		*	limite a lista de métricas a serem rastreadas, separador de barra vertical
compartilhado		2m	tamanho da memória compartilhada, aumentar em caso de erro memória compartilhada muito pequena
buffer		64k	tamanho do buffer de rede, aumentar em caso de erro tamanho do buffer muito pequeno
pacote		1400	tamanho máximo do pacote UDP
modelo			modelo para o nome do gráfico (o padrão é $prefix.$host.$split.$param_$interval)
error_log			sufixo do caminho para gráficos de logs de erro (*)

(*): funciona apenas quando o nginx_error_log_limiting*.patch é aplicado ao código-fonte do nginx

Exemplo (padrão):

http {
    graphite_config prefix=playground server=127.0.0.1;
}

Exemplo (personalizado):

http {
    graphite_config prefix=playground server=127.0.0.1 intervals=1m|5m|15m params=rps|request_time|upstream_time template=$prefix.$host.$split.$param_$interval;
}

Exemplo (error_log):

http {
    graphite_config prefix=playground server=127.0.0.1 error_log=log;
}

graphite_default_data

sintaxe: graphite_default_data <path prefix> [params=<params>] [if=<condition>]

contexto: http, server

Crie um ponto de medição em todas as localizações aninhadas. Você pode usar as variáveis "$location" ou "$server", que representam o nome da localização atual e o nome do servidor atual, com todos os caracteres não alfanuméricos substituídos por "_." Os "_" iniciais e finais são removidos.

Exemplo:

   graphite_default_data nginx.$location;

   location /foo/ {
   }

   location /bar/ {
   }

Os dados para /foo/ serão enviados para nginx.foo, os dados para /bar/ - para nginx.bar. O parâmetro <params> (1.3.0) especifica a lista de parâmetros a serem coletados para todas as localizações aninhadas. Para adicionar todos os parâmetros padrão, use *. O parâmetro <if> (1.1.0) habilita o registro condicional. Uma solicitação não será registrada se a condição avaliar para "0" ou uma string vazia.

Exemplo (com $server):

    graphite_default_data nginx.$server.$location

    server {
        server_name foo_host;

        location /foo/ {
        }
    }

    server {
        server_name bar_host;

        location /bar/ {
        }
    }

Os dados para /foo/ serão enviados para nginx.foo_host.foo, os dados para /bar/ - para nginx.bar_host.bar.

graphite_data

sintaxe: graphite_data <path prefix> [params=<params>] [if=<condition>]

contexto: http, server, location, if

Crie um ponto de medição em uma localização específica.

Exemplo:

    location /foo/ {
        graphite_data nginx.foo;
    }

O parâmetro <params> (1.3.0) especifica a lista de parâmetros a serem coletados para esta localização. Para adicionar todos os parâmetros padrão, use *. O parâmetro <if> (1.1.0) habilita o registro condicional. Uma solicitação não será registrada se a condição avaliar para "0" ou uma string vazia.

Exemplo:

    map $scheme $is_http { http 1; }
    map $scheme $is_https { https 1; }

    ...

    location /bar/ {
        graphite_data nginx.all.bar;
        graphite_data nginx.http.bar if=$is_http;
        graphite_data nginx.https.bar if=$is_https;
        graphite_data nginx.arg params=rps|request_time;
        graphite_data nginx.ext params=*|rps|request_time;
    }

graphite_param

sintaxe: graphite_param name=<path> interval=<time value> aggregate=<func>

contexto: location

Parâmetro	Obrigatório	Descrição
name	Sim	prefixo de caminho para todos os gráficos
interval	Sim*	intervalo de agregação, formato do valor do intervalo de tempo (m - minutos)
aggregate	Sim*	função de agregação sobre os valores
percentile	Sim*	nível de percentil

funções de agregação

func	Descrição
sum	soma dos valores por intervalo
persec	soma dos valores por segundo (sum dividido pelos segundos no interval)
avg	valor médio no intervalo
gauge	valor de medição

Exemplo: veja abaixo.

Nginx API para Lua

sintaxe: ngx.graphite.param(<name>)

Obtenha um link para um nome de parâmetro graphite, para usá-lo no lugar do nome para as funções abaixo. O link é válido até o recarregamento do nginx. Após obter o link de um parâmetro, você ainda pode passar o nome do parâmetro para as funções abaixo. Você pode obter o link de um parâmetro várias vezes, sempre receberá o mesmo objeto pelo mesmo nome (um lightuserdata). A função retorna false se o parâmetro especificado pelo nome não existir. A função retorna nil em caso de erros ao obter o link. As funções acessam informações dos parâmetros por link mais rapidamente do que por nome.

Disponível após aplicar o patch ao lua-nginx-module. O recurso está presente no patch para o módulo lua v0.10.12. Veja as instruções de instalação.

sintaxe: ngx.graphite(<name_or_link>,<value>[,<config>])

Escreva o valor da estatística na função agregadora. Números de ponto flutuante são aceitos em value.

Disponível após aplicar o patch ao lua-nginx-module. Veja as instruções de instalação.

ngx.graphite(name, value, config)

Exemplo:

location /foo/ {
    graphite_param name=lua.foo_sum aggregate=sum interval=1m;
    graphite_param name=lua.foo_rps aggregate=persec interval=1m;
    graphite_param name=lua.foo_avg aggregate=avg interval=1m;
    graphite_param name=lua.foo_gauge aggregate=gauge;

    content_by_lua '
        ngx.graphite("lua.foo_sum", 0.01)
        ngx.graphite("lua.foo_rps", 1)
        ngx.graphite("lua.foo_avg", ngx.var.request_uri:len())
        local foo_gauge_link = ngx.graphite.param("lua.foo_gauge")
        ngx.graphite(foo_gauge_link, 10)
        ngx.graphite(foo_gauge_link, -2)
        ngx.graphite("lua.auto_rps", 1, "aggregate=persec interval=1m percentile=50|90|99")
        ngx.say("hello")
    ';
}

Você deve especificar o comando graphite_param ou passar o argumento config. Se você escolher a segunda opção, os dados para este gráfico não serão enviados até a primeira chamada para ngx.graphite.

Aviso: Se você não declarar o gráfico usando o comando graphite_param, a memória para o gráfico será alocada dinamicamente na memória compartilhada do módulo. Se a memória compartilhada do módulo se esgotar enquanto o nginx estiver em execução, novos gráficos não serão criados e uma mensagem de erro será registrada.

sintaxe: ngx.graphite.get(<name_or_link>)

Obtenha o valor do parâmetro gauge com o name_or_link especificado.

sintaxe: ngx.graphite.set(<name>,<value>)

Defina value para o parâmetro gauge com o name_or_link especificado.

Parâmetros

Parâmetro	Unidades	Função	Descrição
request_time	ms	avg	tempo total gasto no atendimento da solicitação
bytes_sent	bytes	avg	comprimento da resposta http
body_bytes_sent	bytes	avg	comprimento do corpo da resposta http
request_length	bytes	avg	comprimento da solicitação http
ssl_handshake_time	ms	avg	tempo gasto na handshake ssl
ssl_cache_usage	%	last	quanto do cache SSL foi usado
content_time	ms	avg	tempo gasto gerando conteúdo dentro do nginx
gzip_time	ms	avg	tempo gasto comprimindo conteúdo on-the-fly
upstream_time	ms	avg	tempo gasto conversando com upstream
upstream_connect_time	ms	avg	tempo gasto na conexão upstream (nginx >= 1.9.1)
upstream_header_time	ms	avg	tempo gasto no cabeçalho upstream (nginx >= 1.9.1)
rps	rps	sum	número total de solicitações por segundo
keepalive_rps	rps	sum	número de solicitações enviadas através de uma conexão keepalive previamente aberta
response_2xx_rps	rps	sum	número total de respostas com código 2xx
response_3xx_rps	rps	sum	número total de respostas com código 3xx
response_4xx_rps	rps	sum	número total de respostas com código 4xx
response_5xx_rps	rps	sum	número total de respostas com código 5xx
response_[0-9]{3}_rps	rps	sum	número total de respostas com o código dado
upstream_cache_(miss	bypass	expired	stale
lua_time	ms	avg	tempo gasto no código lua

Percentis

Para calcular o valor do percentil para qualquer parâmetro, defina o nível do percentil via /. Exemplo: request_time/50|request_time/90|request_time/99.

patch para adicionar API para enviar métricas do código lua (opcional)

patch -p1 < /path/to/graphite-nginx-module/lua_module_v0_9_11.patch cd ..

wget 'http://nginx.org/download/nginx-1.9.2.tar.gz' tar -xzf nginx-1.9.2.tar.gz cd nginx-1.9.2/

GitHub

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