Aller au contenu

influx: client Nginx-module-lua pour InfluxDB

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-influx v0.2.1 publié le 27 décembre 2017.

Cette bibliothèque fournit une interface OpenResty pour écrire des points de données sur un serveur InfluxDB via des interfaces UDP et HTTP. Des interfaces basées sur des objets et de mise en mémoire tampon par travailleur sont fournies.

Synopsis

Interface objet :

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()

            -- ajouter et mettre en mémoire tampon des points de données supplémentaires

            local ok, err = influx:flush()

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

Interface de mise en mémoire tampon :

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()
        }
    }
}

Utilisation

Options

lua-resty-influx fournit une interface purement basée sur des objets, ainsi qu'une interface de mise en mémoire tampon qui stocke les points de données par travailleur, puis met en mémoire tampon de manière asynchrone via ngx.timer.at. La création de l'interface de mise en mémoire tampon doit être gérée dans la phase init_worker_by_lua via la fonction resty.influx.buffer.init ; la création de l'interface orientée objet doit être gérée dans votre gestionnaire de phase approprié via resty.influx.object:new. Dans les deux cas, les options suivantes sont disponibles :

host

Par défaut : 127.0.0.1

Définit l'hôte auquel ngx.socket.udp et resty.http tenteront de se connecter.

port

Par défaut : 8086

Définit le port auquel ngx.socket.udp et resty.http tenteront de se connecter. Par défaut, c'est 8086 car le protocole par défaut est HTTP.

db

Par défaut : 'lua-resty-influx'

Définit la base de données à laquelle resty.http tentera de se connecter. Cette option est ignorée lorsque udp est le protocole configuré.

hostname

Par défaut : host

Définit le nom d'hôte que resty.http utilisera pour définir l'en-tête Host pour les requêtes HTTP. Par défaut, cela est égal à l'option host configurée. Cette option est ignorée lorsque udp est le protocole configuré.

proto

Par défaut : http

Définit le protocole par lequel resty.influx se connectera au serveur distant. Notez que UDP peut offrir une amélioration significative des performances, en particulier lors de l'envoi de nombreux petits ensembles de points de données, au prix de la gestion des erreurs et de l'authentification.

precision

Par défaut : ms

Définit la précision des horodatages par laquelle resty.influx définira les horodatages. Actuellement, ms, s et none sont pris en charge ; lorsque none est configuré, aucun horodatage ne sera envoyé dans le message du protocole de ligne, et le serveur Influx distant utilisera une précision en nanosecondes basée sur l'horloge locale du serveur.

ssl

Par défaut : false

Configure les requêtes HTTP pour effectuer une poignée de main TLS avant d'envoyer des données. Cette option est ignorée lorsque udp est le protocole configuré.

auth

Par défaut : ''

Définit le nom d'utilisateur et le mot de passe présentés à HTTP(S) distant. Cette valeur doit être donnée sous forme d'une seule chaîne au format user:password. Cette option est ignorée lorsque udp est le protocole configuré.

Interface Orientée Objet

Les méthodes suivantes sont disponibles via l'interface objet :

influx:set_measurement

Syntaxe : influx:set_measurement(string)

Définit la mesure pour le point de données associé à l'objet actuel.

influx:add_tag

Syntaxe influx:add_tag(key, value)

Ajoute une balise de point de données sous forme de paire clé-valeur. Les clés et les valeurs sont échappées selon (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/).

influx:add_field

Syntaxe : influx:add_field(key, value)

Ajoute un champ de point de données sous forme de paire clé-valeur. Les champs et les valeurs sont échappés selon (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/). Les valeurs entières (valeurs numériques suivies d'un i) sont correctement interpolées.

influx:stamp

Syntaxe : influx:stamp(time?)

Horodate le point de données associé à l'objet actuel, avec une valeur arbitraire optionnelle (doit être fournie sous forme de nombre) ; sinon, cela horodate l'objet avec la valeur appropriée basée sur la précision spécifiée via les options données à new pour l'interface objet.

influx:clear

Syntaxe influx:clear()

Efface la mesure, les balises et les champs sur le point de données associé à l'objet actuel. Notez que cela est appelé en interne lorsque buffer ou write sont appelés.

influx:buffer

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

Met en mémoire tampon le contenu du point de données associé à l'objet actuel pour un vidage ultérieur. Renvoie true en cas de succès ; sinon, renvoie false et une chaîne décrivant l'erreur (comme des conditions invalides dans lesquelles mettre en mémoire tampon).

influx:flush

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

Vide tous les points de données mis en mémoire tampon associés à l'objet actuel. Renvoie true en cas de succès ; sinon, renvoie false et une chaîne décrivant l'erreur (comme des données restantes en attente d'être mises en mémoire tampon, ou aucun point de données mis en mémoire tampon disponible).

influx:write

Syntaxe local ok, err = inflush:write()

Écrit le point de données associé à l'objet actuel, sans effacer le tampon d'objet existant. C'est essentiellement une abréviation pour appeler buffer et flush sur un seul point de données. Notez que les points de données précédemment mis en mémoire tampon restent dans le tampon et doivent être envoyés via flush si désiré.

Interface de Mise en Mémoire Tampon

Les fonctions suivantes sont disponibles via l'interface de mise en mémoire tampon :

influx.buffer

Syntaxe : influx.buffer(data_table)

Met en mémoire tampon un nouveau point de données dans le tampon de processus par travailleur. data_table doit être une table contenant les clés suivantes :

  • measurement : Chaîne désignant la mesure du point de données
  • tags : Table indexée par des entiers contenant des tables de paires clé-valeur désignant les éléments de balise. Voir le synopsis pour des exemples.
  • fields : Table indexée par des entiers contenant des tables de paires clé-valeur désignant les éléments de champ. Voir le synopsis pour des exemples.

Notez qu'actuellement, l'horodatage est automatiquement défini avec une précision de ms.

influx.flush

Syntaxe influx.flush()

Écrit tous les points de données mis en mémoire tampon dans le processus de travail actuel vers l'hôte influx configuré. Renvoie true en cas de succès ; sinon, renvoie false et une chaîne décrivant l'erreur de ngx.timer.at.

Cette opération retourne immédiatement et s'exécute de manière asynchrone.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-influx.