{"id":13777028,"url":"https://github.com/lblasc/lua-telegraf","last_synced_at":"2025-05-11T10:31:32.363Z","repository":{"id":139101098,"uuid":"161317569","full_name":"lblasc/lua-telegraf","owner":"lblasc","description":"Lua/LuaJIT/OpenResty client for telegraf/influxdb","archived":false,"fork":false,"pushed_at":"2020-12-19T08:09:05.000Z","size":13,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-20T21:39:33.893Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lblasc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-11T10:33:48.000Z","updated_at":"2022-03-04T15:47:59.000Z","dependencies_parsed_at":"2024-01-13T10:12:53.216Z","dependency_job_id":"c391b090-11f1-4e4d-9970-a8618ff2c351","html_url":"https://github.com/lblasc/lua-telegraf","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lblasc%2Flua-telegraf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lblasc%2Flua-telegraf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lblasc%2Flua-telegraf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lblasc%2Flua-telegraf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lblasc","download_url":"https://codeload.github.com/lblasc/lua-telegraf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253551797,"owners_count":21926362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T18:00:36.564Z","updated_at":"2025-05-11T10:31:30.710Z","avatar_url":"https://github.com/lblasc.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"# Name\n\nlua-telegraf - Lua/LuaJIT/OpenResty client writer for [Telegraf](https://github.com/influxdata/telegraf)/[InfluxDB](https://github.com/influxdata/influxdb)\nor any listener compatible with [InfluxDB Line Protocol](https://docs.influxdata.com/influxdb/latest/write_protocols/line_protocol_reference/).\n\n# Table of Contents\n\n* [Name](#name)\n* [Status](#status)\n* [Description](#description)\n* [Installation](#installation)\n* [Synopsis](#synopsis)\n    * [OpenResty](#openresty)\n    * [Lua](#lua)\n* [Methods](#methods)\n    * [new](#new)\n    * [set](#set)\n    * [flush](#flush)\n* [TODO](#todo)\n* [Author](#author)\n* [Copyright and License](#copyright-and-license)\n\n# Status\n\nThis library is considered production ready.\n\n# Description\n\nThis library implements writer interface for InfluxDB line protocol.\nFocus is on simplicity and efficiency. Depending on runtime it will\nfind most suitable backend/library for constructing and writing metrics.\n\nWhen run in context of OpenResty it will use cosocket API, which\nensures 100% nonblocking behavior, and nginx time primitives for\nfetching cached time (no syscall involved). Support for Lua,\nLuaJIT and nanosecond precision is covered by\n[ljsyscall](https://github.com/justincormack/ljsyscall) library.\n\n# Installation\n\nClone into your Lua module path or use opm:\n\n```bash\n  $ opm get lblasc/lua-telegraf\n```\n\n# Synopsis\n\n## OpenResty\n\n#### Simple (no batching)\n```lua\n# you do not need the following line if you installed\n# module with `opm`\nlua_package_path \"/path/to/lua-telegraf/?.lua;;\";\n\nhttp {\n  server {\n    access_by_lua_block {\n      local telegraf = require \"telegraf\"\n\n      local t = telegraf.new({\n        host = \"127.0.0.1\",\n        port = 8094,\n        global_tags = {\n          gtag  = 1,\n        },\n      })\n\n      local ok, err = t:set('test', {field = 123}, {tag = 'tagged'})\n      if not ok then\n        ngx.say(err)\n      end\n    }\n  }\n}\n```\n\n#### Batching\n\nCreate simple module (E.g. stats.lua) witch will use lua module caching\nto preserve `lua-telegraf` instance and make it available in all phases.\n\n```lua\nlocal telegraf = require 'telegraf'\nlocal t\n\nlocal _M = {}\n\nfunction _M.init(conf)\n  t = telegraf.new(conf)\n  return t\nend\n\nfunction _M.get()\n  assert(t)\n  return t\nend\n\nreturn _M\n```\n\n```lua\nlua_package_path \"/path/to/stats/module/?.lua;;\";\n\nhttp {\n  init_worker_by_lua_block {\n    local function flush_stats(premature)\n      if premature then\n        return\n      end\n\n      local t = require('stats').get()\n      t:flush()\n    end\n\n    local flush_every = 1 -- adjust flush interval (in seconds)\n    require(\"stats\").init({\n      host = \"127.0.0.1\",\n      port = 8094,\n      batch_size = 20,\n      global_tags = {\n        gtag  = 1,\n      },\n    })\n\n    local ok, err = ngx.timer.every(flush_every, flush_stats)\n    if not ok then\n      ngx.log(ngx.ERR, err)\n      return\n    end\n  }\n\n  server {\n    access_by_lua_block {\n      local t = require(\"stats\").get()\n\n      t:set('test', {field = 123}, {tag = 'tagged'})\n    }\n\n    log_by_lua_block {\n      local t = require(\"stats\").get()\n\n      t:set('nginx_stats', {\n        request_time = ngx.now() - ngx.req.start_time()\n      }, {tag = 'mytag'})\n    }\n  }\n}\n```\n\n## Lua\n```lua\nlocal telegraf = require \"telegraf\"\n\nlocal t = telegraf.new({\n  host = \"127.0.0.1\",\n  port = 8094,\n  global_tags = {\n    gtag  = 1,\n  },\n})\n\nlocal ok, err = t:set('test', {field = 123}, {tag = 'tagged'})\nif not ok then\n  error(err)\nend\n```\n\n# Methods\n\n## new\n`syntax: t, err = telegraf.new(options?)`\n\nCreates telegraf instance with optional options table.\n\n### options\n\n#### host\n\n*Default*: `127.0.0.1`\n\nSets the host address.\n\n#### port\n\n*Default*: `8094`\n\nSets the host port.\n\n#### proto\n\n*Default*: `udp`\n\nSets the protocol, for now only supported is udp.\n\n#### precision\n\n*Default*: `nil`\n\nSets the timestamp precision. Currently, `s`, `ms`, `u`, and `ns`\nare supported, when precision is `nil` (default) no timestamp\nwill be sent as part of the line protocol message, and the\nremote server will set timestamp based on the server-local clock.\n\n#### global_tags\n\n*Default*: `{}`\n\nTags that will be added to every metric. Field needs to be defined\nin set of tag/value pairs.\n\n#### batch_size\n\n*Default*: `nil`\n\nPreallocates batch buffer by specified size and enables batching.\nBatch buffer is `table` which will exceed buffer size if not\nflushed in time, flushing is manual operation. By default (`nil`)\nbatching is disabled and all metrics will be sent immediately.\n\n## set\n`syntax: ok, err = t:set(measurement, fields, tags?, timestamp?)`\n\nGenerates new data point, depending on options, data point is pushed\nto a buffer or sent immediately.\n\n* `measurement`: `string` denoting the measurement of the data point\n* `fields`: `table` of key-value pairs denoting the field elements\n* `tags` (optional): `table` of key-value pairs denoting the tag elements\n* `timestamp` (optional): `number` which overrides generated or\nsets timestamp with time provided in `UNIX time` format\n\n## flush\n`syntax: t:flush()`\n\nFlushes batch buffer. If buffer is empty or not enabled method\njust returns.\n\n[Back to TOC](#table-of-contents)\n\n# TODO\n\n- http support\n\n[Back to TOC](#table-of-contents)\n\nAuthor\n======\n\nLuka Blašković \u003clblasc@znode.net\u003e\n\n[Back to TOC](#table-of-contents)\n\nCopyright and License\n=====================\n\nSee [LICENSE](./LICENSE)\n\n[Back to TOC](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flblasc%2Flua-telegraf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flblasc%2Flua-telegraf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flblasc%2Flua-telegraf/lists"}