lua-resty-influx - OpenResty client writer for InfluxDB.
This library is in active development and is considered ready for production use.
This library provides an OpenResty interface to write data points to an InfluxDB server via UDP and HTTP interfaces. Object-based and buffering per-worker interfaces are provided.
Object interface:
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()
-- add and buffer additional data points
local ok, err = influx:flush()
if (not ok) then
ngx.say(err)
end
}
}
}Buffering interface:
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()
}
}
}lua-resty-influx provides a pure object-based interface, as well as a buffering interface that stores data points per-worker, and then buffers asynchronously via ngx.timer.at. Creation of the buffering interface should be handled in the init_worker_by_lua phase via the resty.influx.buffer.init function; creation of the object-oriented interface should be handled in your appropriate phase handler via resty.influx.object:new. In both cases, the following options are available:
Default: 127.0.0.1
Sets the host to which ngx.socket.udp and resty.http will attempt to connect.
Default: 8086
Sets the port to which ngx.socket.udp and resty.http will attempt to connect. Defaults to 8086 as the default protocol is HTTP.
Default: 'lua-resty-influx'
Sets the db to which resty.http will attempt to connect. This option is ignored when udp is the configured protocol.
Default: host
Sets the hostname to which resty.http will define the Host header for HTTP requests. By default, this is equal to the configured host option. This option is ignored when udp is the configured protocol.
Default: http
Sets the protocol by which resty.influx will connect to the remote server. Note that UDP can present a significant performance improvement, particularly when sending many small sets of data points, at the cost of error handling and authentication.
Default: ms
Sets the timestamp precision by which resty.influx will define timestamps. Currently, ms, s, and none are supported; when none is configured, no stamp will be sent as part of the line protocol message, and the remote Influx server will use nanosecond precision based on the server-local clock.
Default: false
Configures HTTP requests to perform a TLS handshake before sending data. This option is ignored when udp is the configured protocol.
Default: ''
Sets the username and password presented to remote HTTP(S). This value must be given as a single string in the format user:password. This option is ignored when udp is the configured protocol.
The following methods are available via the object interface:
Syntax: influx:set_measurement(string)
Sets the measurement for the data point associated with the current object.
Syntax influx:add_tag(key, value)
Adds a data point tag as a key-value pair. Keys and values are escaped according to (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/).
Syntax: influx:add_field(key, value)
Add a data point field as a key-value pair. Fields and values are escaped according to (https://docs.influxdata.com/influxdb/v1.0/write_protocols/line_protocol_reference/). Integer values (number values appended with an i) are properly interpolated.
Syntax: influx:stamp(time?)
Stamps the data point associated with the current object, with an optional arbitrary value (must be provided as a number); otherwise, this stamps the object with the appropriate value based on the precision specified via the options given to new for the object interface.
Syntax influx:clear()
Clears the measurement, tags, and fields on the data point associated with the current object. Note that this is called internally when buffer or write are called.
Syntax: local ok, err = influx:buffer()
Buffer the contents of the data point associated with the current object for later flushing. Returns true on success; otherwise, returns false and a string describing the error (such as invalid conditions under which to buffer).
Syntax: local ok, err = influx:flush()
Flushes all buffered data points associated with the current object. Returns true on success; otherwise, returns false and a string describing the error (such as leftover data waiting to be buffered, or no available buffered data points).
Syntax local ok, err = inflush:write()
Writes the data point associated with the current object, without clearing the existing object buffer. This is essentially shorthand for calling buffer and flush on a single data point. Note that previously buffered data points still remain in the buffer, and must be sent out via flush if desired.
The following functions are available via the buffering interface:
Syntax: influx.buffer(data_table)
Buffers a new data point in the per-worker process buffer. data_table must be a table that contains the following keys:
measurement: String denoting the measurement of the data pointtags: Integer-indexed table containing tables of key-value pairs denoting the tag elements. See the synopsis for examples.fields: Integer-indexed table containing tables of key-value pairs denoting the field elements. See the synopsis for examples.
Note that currently the timestamp is automatically set with ms precision.
Syntax influx.flush()
Write all data points buffered in the current worker process to the configured influx host. Returns true on success; otherwise, returns false and a string describing the error from ngx.timer.at.
This operation returns immediately and runs asynchronously
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/
Please report bugs by creating a ticket with the GitHub issue tracker.