Pular para conteúdo

influx: cliente Nginx-module-lua para InfluxDB

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Depois, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou Amazon Linux 2

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 lua-resty-influx

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-influx

Para usar esta biblioteca Lua com NGINX, certifique-se de que o nginx-module-lua está instalado.

Este documento descreve lua-resty-influx v0.2.1 lançado em 27 de dezembro de 2017.

Esta biblioteca fornece uma interface OpenResty para escrever pontos de dados em um servidor InfluxDB via interfaces UDP e HTTP. Interfaces baseadas em objetos e de buffer por trabalhador são fornecidas.

Sinopse

Interface de objeto:

http {
    server {
        access_by_lua_block {
            local i = require "resty.influx.object"

            local influx, err = i:new({
                host = "127.0.0.1",
                port = 8086,
                proto = "http",
                db = "db",
                hostname = "localhost",
                auth = "user:password",
            })

            if (not influx) then
                ngx.say(err)
                return
            end

            influx:set_measurement("foo")
            influx:add_tag("foo", "bar")
            influx:add_field("value", 1)
            influx:buffer()

            -- adicionar e bufferizar pontos de dados adicionais

            local ok, err = influx:flush()

            if (not ok) then
                ngx.say(err)
            end
        }
    }
}

Interface de buffering:

http {
    init_worker_by_lua_block {
        local ibuf = require "resty.influx.buffer"

        local ok, err = ibuf.init({
            host = "127.0.0.1",
            port = 8089,
            proto = "udp",
        })

        if (not ok) then
            ngx.log(ngx.ERR, err)
        end
    }

    server {
        access_by_lua_block {
            local ibuf = require "resty.influx.buffer"

            ibuf.buffer({
                measurement = "foo",
                tags = {
                    { foo = "bar" }
                },
                fields = {
                    { value = 1 }
                }
            })
        }

        log_by_lua_block {
            local ibuf = require "resty.influx.buffer"

            ibuf.flush()
        }
    }
}

Uso

Opções

lua-resty-influx fornece uma interface puramente baseada em objetos, bem como uma interface de buffering que armazena pontos de dados por trabalhador e, em seguida, bufferiza de forma assíncrona via ngx.timer.at. A criação da interface de buffering deve ser tratada na fase init_worker_by_lua via a função resty.influx.buffer.init; a criação da interface orientada a objetos deve ser tratada no seu manipulador de fase apropriado via resty.influx.object:new. Em ambos os casos, as seguintes opções estão disponíveis:

host

Padrão: 127.0.0.1

Define o host ao qual ngx.socket.udp e resty.http tentarão se conectar.

port

Padrão: 8086

Define a porta à qual ngx.socket.udp e resty.http tentarão se conectar. O padrão é 8086, pois o protocolo padrão é HTTP.

db

Padrão: 'lua-resty-influx'

Define o db ao qual resty.http tentará se conectar. Esta opção é ignorada quando udp é o protocolo configurado.

hostname

Padrão: host

Define o hostname que resty.http usará para definir o cabeçalho Host para requisições HTTP. Por padrão, isso é igual à opção host configurada. Esta opção é ignorada quando udp é o protocolo configurado.

proto

Padrão: http

Define o protocolo pelo qual resty.influx se conectará ao servidor remoto. Note que o UDP pode apresentar uma melhoria significativa de desempenho, particularmente ao enviar muitos pequenos conjuntos de pontos de dados, à custa de tratamento de erros e autenticação.

precision

Padrão: ms

Define a precisão do timestamp pela qual resty.influx definirá timestamps. Atualmente, ms, s e none são suportados; quando none é configurado, nenhum timestamp será enviado como parte da mensagem do protocolo de linha, e o servidor Influx remoto usará precisão em nanossegundos com base no relógio local do servidor.

ssl

Padrão: false

Configura requisições HTTP para realizar um handshake TLS antes de enviar dados. Esta opção é ignorada quando udp é o protocolo configurado.

auth

Padrão: ''

Define o nome de usuário e a senha apresentados ao HTTP(S) remoto. Este valor deve ser fornecido como uma única string no formato user:password. Esta opção é ignorada quando udp é o protocolo configurado.

Interface Orientada a Objetos

Os seguintes métodos estão disponíveis via a interface de objeto:

influx:set_measurement

Sintaxe: influx:set_measurement(string)

Define a medição para o ponto de dados associado ao objeto atual.

influx:add_tag

Sintaxe: influx:add_tag(key, value)

Adiciona uma tag de ponto de dados como um par chave-valor. Chaves e valores são escapados de acordo com (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/).

influx:add_field

Sintaxe: influx:add_field(key, value)

Adiciona um campo de ponto de dados como um par chave-valor. Campos e valores são escapados de acordo com (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/). Valores inteiros (valores numéricos seguidos de um i) são interpolados corretamente.

influx:stamp

Sintaxe: influx:stamp(time?)

Marca o ponto de dados associado ao objeto atual, com um valor arbitrário opcional (deve ser fornecido como um número); caso contrário, isso marca o objeto com o valor apropriado com base na precisão especificada via as opções dadas a new para a interface de objeto.

influx:clear

Sintaxe: influx:clear()

Limpa a medição, tags e campos no ponto de dados associado ao objeto atual. Note que isso é chamado internamente quando buffer ou write são chamados.

influx:buffer

Sintaxe: local ok, err = influx:buffer()

Bufferiza o conteúdo do ponto de dados associado ao objeto atual para posterior descarte. Retorna true em caso de sucesso; caso contrário, retorna false e uma string descrevendo o erro (como condições inválidas sob as quais bufferizar).

influx:flush

Sintaxe: local ok, err = influx:flush()

Descarrega todos os pontos de dados bufferizados associados ao objeto atual. Retorna true em caso de sucesso; caso contrário, retorna false e uma string descrevendo o erro (como dados restantes esperando para serem bufferizados, ou nenhum ponto de dados bufferizado disponível).

influx:write

Sintaxe: local ok, err = influx:write()

Escreve o ponto de dados associado ao objeto atual, sem limpar o buffer do objeto existente. Isso é essencialmente uma forma abreviada de chamar buffer e flush em um único ponto de dados. Note que pontos de dados previamente bufferizados ainda permanecem no buffer e devem ser enviados via flush se desejado.

Interface de Buffering

As seguintes funções estão disponíveis via a interface de buffering:

influx.buffer

Sintaxe: influx.buffer(data_table)

Bufferiza um novo ponto de dados no buffer do processo por trabalhador. data_table deve ser uma tabela que contém as seguintes chaves:

  • measurement: String que denota a medição do ponto de dados
  • tags: Tabela indexada por inteiros contendo tabelas de pares chave-valor que denotam os elementos de tag. Veja a sinopse para exemplos.
  • fields: Tabela indexada por inteiros contendo tabelas de pares chave-valor que denotam os elementos de campo. Veja a sinopse para exemplos.

Note que atualmente o timestamp é automaticamente definido com precisão de ms.

influx.flush

Sintaxe: influx.flush()

Escreve todos os pontos de dados bufferizados no processo trabalhador atual para o host influx configurado. Retorna true em caso de sucesso; caso contrário, retorna false e uma string descrevendo o erro de ngx.timer.at.

Esta operação retorna imediatamente e é executada de forma assíncrona.

GitHub

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