{"_id":"57fcc4870312b20e00ac64df","project":"5435687035740020002a1c04","version":{"_id":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","__v":1,"createdAt":"2016-10-11T10:52:54.637Z","releaseDate":"2016-10-11T10:52:54.637Z","categories":["57fcc4860312b20e00ac64c1","57fcc4860312b20e00ac64c2","57fcc4860312b20e00ac64c3","57fcc4860312b20e00ac64c4","57fcc4860312b20e00ac64c5","57fcc4860312b20e00ac64c6","57fcc4860312b20e00ac64c7","57fcc4860312b20e00ac64c8","57fcc4860312b20e00ac64c9","57fcc4860312b20e00ac64ca","57fcc4860312b20e00ac64cb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"[APP-1265], [APP-1035]","version_clean":"5.2.0","version":"5.2"},"__v":0,"user":"5589fde775eaf50d004e4b0c","category":{"_id":"57fcc4860312b20e00ac64c8","__v":0,"version":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-04T23:13:08.376Z","from_sync":false,"order":7,"slug":"lua-scripting","title":"Agent Lua Scripting"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-04T23:52:56.703Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"The Lua global namespace offers a number of functions that are useful for writing Telemetry scripts. We also offer libraries that can be imported to access functions that are more specific to the Telemetry Agent.\n\n# Logging and reporting errors\n\nYou can log a string to the Agent's console output using the `print()` function. Similarly, the `error()` function reports a string to the Agent's error log (and causes the error to bubble to the API, where it will be visible inside your account log). For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local a = 10\\n\\nprint(\\\"The value of a is \\\" .. a)\\n\\nif a > 10 then\\n\\terror(\\\"a is greater than 10!\\\")\\nend\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# The `os.time()` function\n\nLua provides the built-in function `os.time()` which returns the current UNIX timestamp in numeric format. This can be easily sent to the API, or used in a number of calculations.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local a = os.time()\\n\\nlocal value = a / 3600\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# The `math.random()` function\n\nThe `math.random()` function is built into the Lua language. It can be used to generate both interg\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`lower`\",\n    \"0-1\": \"number\",\n    \"0-2\": \"Optional. The lowest random value to be generated. If not included then the result's range will default between 1 and `upper`.\",\n    \"1-0\": \"`upper`\",\n    \"1-1\": \"number\",\n    \"1-2\": \"Optional. The maximum random value to be generated. If no arguments are provided then the result will be a floating point number between 0 and 1.0.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-- Generate a random floating point number between 0 and 1.0 inclusive\\nmath.random()\\n\\n-- Generate a random integer between 1 and 100 inclusive\\nmath.random() + math.random(1, 100)\\n\\n-- Generate a random floating point number between 1.0 and 100.0 inclusive\\nmath.random() + math.random(1, 99)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Accessing arguments\n\nYou can pass arguments to a Lua script in the Agent's configuration file. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[[flow]]\\ntag = \\\"test_flow\\\"\\nscript = \\\"generate_gauge.lua\\\"\\n[flow.args]\\nserver = \\\"server-1\\\"\\nip = \\\"127.0.0.1\\\"\",\n      \"language\": \"toml\"\n    }\n  ]\n}\n[/block]\nThese will then be available inside your script within a table called `args()`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local server = args.server\\nlocal ip = args.ip\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Accessing counters\n\nImporting the `telemetry/storage` library will give you access to the `counter()` global function which returns a reference to a counter. You can then use the `value()` function to retrieve the counter's current value.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\n\\nlocal value = st.counter(\\\"test\\\").value()\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\nIn addition, counters support a [number of properties](doc:accessing-counters-from-lua)  that you can use to manipulate the contents of a counter.\n\n# Accessing series\n\nImporting the `telemetry/storage` library will also give you access to the `series()` global function which returns a reference to a series. You can then [interrogate and manipulate the series](doc:accessing-series-data-from-lua)  using one of several properties.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\nlocal series = st.series(\\\"test\\\")\\n\\nlocal value = series.compute(st.Functions.AVG, \\\"1h\\\")\\nlocal sparkline = series.aggregate(st.Functions.AVG, \\\"1m\\\", 10).values()\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"functions","type":"basic","title":"Functions"}
The Lua global namespace offers a number of functions that are useful for writing Telemetry scripts. We also offer libraries that can be imported to access functions that are more specific to the Telemetry Agent. # Logging and reporting errors You can log a string to the Agent's console output using the `print()` function. Similarly, the `error()` function reports a string to the Agent's error log (and causes the error to bubble to the API, where it will be visible inside your account log). For example: [block:code] { "codes": [ { "code": "local a = 10\n\nprint(\"The value of a is \" .. a)\n\nif a > 10 then\n\terror(\"a is greater than 10!\")\nend", "language": "lua" } ] } [/block] # The `os.time()` function Lua provides the built-in function `os.time()` which returns the current UNIX timestamp in numeric format. This can be easily sent to the API, or used in a number of calculations. [block:code] { "codes": [ { "code": "local a = os.time()\n\nlocal value = a / 3600", "language": "lua" } ] } [/block] # The `math.random()` function The `math.random()` function is built into the Lua language. It can be used to generate both interg [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`lower`", "0-1": "number", "0-2": "Optional. The lowest random value to be generated. If not included then the result's range will default between 1 and `upper`.", "1-0": "`upper`", "1-1": "number", "1-2": "Optional. The maximum random value to be generated. If no arguments are provided then the result will be a floating point number between 0 and 1.0." }, "cols": 3, "rows": 2 } [/block] [block:code] { "codes": [ { "code": "-- Generate a random floating point number between 0 and 1.0 inclusive\nmath.random()\n\n-- Generate a random integer between 1 and 100 inclusive\nmath.random() + math.random(1, 100)\n\n-- Generate a random floating point number between 1.0 and 100.0 inclusive\nmath.random() + math.random(1, 99)", "language": "lua" } ] } [/block] # Accessing arguments You can pass arguments to a Lua script in the Agent's configuration file. For example: [block:code] { "codes": [ { "code": "[[flow]]\ntag = \"test_flow\"\nscript = \"generate_gauge.lua\"\n[flow.args]\nserver = \"server-1\"\nip = \"127.0.0.1\"", "language": "toml" } ] } [/block] These will then be available inside your script within a table called `args()`: [block:code] { "codes": [ { "code": "local server = args.server\nlocal ip = args.ip", "language": "lua" } ] } [/block] # Accessing counters Importing the `telemetry/storage` library will give you access to the `counter()` global function which returns a reference to a counter. You can then use the `value()` function to retrieve the counter's current value. For example: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\n\nlocal value = st.counter(\"test\").value()", "language": "lua" } ] } [/block] In addition, counters support a [number of properties](doc:accessing-counters-from-lua) that you can use to manipulate the contents of a counter. # Accessing series Importing the `telemetry/storage` library will also give you access to the `series()` global function which returns a reference to a series. You can then [interrogate and manipulate the series](doc:accessing-series-data-from-lua) using one of several properties. For example: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\nlocal series = st.series(\"test\")\n\nlocal value = series.compute(st.Functions.AVG, \"1h\")\nlocal sparkline = series.aggregate(st.Functions.AVG, \"1m\", 10).values()", "language": "lua" } ] } [/block]