{"_id":"57fcc4870312b20e00ac64de","parentDoc":null,"__v":0,"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"},"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"},"project":"5435687035740020002a1c04","user":"5589fde775eaf50d004e4b0c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-05T20:22:19.333Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Lua is a general-purpose scripting language that has been integrated into the Telemetry Agent to allow users to easily perform Agent-specific tasks such as:\n\n- Extracting data from a time series stored in the Agent's data management system\n- Manipulating a counter (also in the data management system)\n- Checking for specific conditions that may trigger one or more changes in a flow (e.g.: set a color to red if a certain value exceeds a predefined threshold)\n- Sending notifications to the API\n\nThis capability is available while also offering the freedom of a general-purpose language. All of Lua's functionality is available when writing scripts for the Agent. You can review the [Lua reference manual](http://www.lua.org/manual/5.3/) for a full overview of this functionality.\n\nThe following section will introduce some of the basics of the Lua language.\n\n# Data Types \n\nLua has eight basic [data types](http://www.lua.org/pil/2.html). These are:\n\n- [Numbers](http://www.lua.org/pil/2.3.html), expressed solely as double-precision floating point​ values. The distinction between integer and floating-point numbers are determined automatically as needed.\n- [Strings](http://www.lua.org/pil/2.4.html), expressed as UTF-8 sequences delimited by either single or double quotation marks. A backslash can be used to escape a quotation mark inside a string.\n- [Boolean](http://www.lua.org/pil/2.2.html) values can be assigned the value `true` and `false`. Traditional logical operations, such as `or`, `and`, and `not` are supported. Numbers evaluate to `true` even if they are zero. Strings always evaluate to `true` even when empty.\n- [Tables](http://www.lua.org/pil/2.5.html) are associative arrays enclosed in braces `{}`. Values can be associated with either a numerical index or keys which are case-sensitive string identifiers. Traditional arrays can be specified by wrapping the table in the `array()` function.\n- Additional types include [Nil](http://www.lua.org/pil/2.1.html), [Functions](http://www.lua.org/pil/2.6.html), [Userdata, and Threads](http://www.lua.org/pil/2.7.html)\n\nHere are some examples:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-- Numbers\\n123\\n28.392\\n-192.1\\n\\n12 + 20\\n(10 + 20) * 10\\n\\n-- Strings\\n\\\"A string with double quotation marks\\\"\\n'A string with single quotation marks'\\n\\\"A string with \\\\\\\"escaped quotation marks\\\\\\\"\\\"\\n\\n-- Boolean\\ntrue\\nfalse\\ntrue and false\\nnot true\\n\\n-- Table\\nlocal t = { test = 1, [\\\"Test\\\"] = 2, [\\\"Another Test\\\"] = 3}\\nt[\\\"one last test\\\"] = 4\\n\\nlocal a = array( {0, 1, 2, 3} )\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Comments\n\nLua recognizes single-line comments beginning with two hyphens (--) or multi-line comments beginning with two hyphens and a two open brackets (--[[) followed by two hyphens and two closing brackets (--]]). For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-- This is a single-line comment\\n\\n--[[\\n\\tThis is a multi-line comment\\n--]]\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Variables\n\nAs in any other language, variables are containers of data. Lua is loosely typed; therefore, variables take on the type of the value that is assigned to them at any given time.\n\nVariables by default are assigned to the global namespace. Local variables must be preceded by the `local` keyword when being declared. Data can be assigned to a variable with the `=` operator.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-- A global variable\\na = 10\\n-- A local variable\\nlocal b = 20\\n\\n-- Variables can be used in expressions\\na + b\\na == b\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n# Populating Telemetry flows\n\nTelemetry flows are populated using the `output` global table variable. To send data to a flow, all that you need to do is append a flow's property to the `output` table.\n\nFor example, if you have a `number` flow:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local a = 10\\n\\noutput.number = {\\n  value = a\\n}\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\nHere is a more complex example, this time for a pie chart flow:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"output.slices = array({\\n  {\\n    value = 12,\\n    label = \\\"test1\\\"\\n  },\\n  {\\n    value = 52,\\n    label = \\\"test2\\\"\\n  },\\n  {\\n    value = 22,\\n    label = \\\"test3\\\"\\n  },\\n  {\\n    value = 16,\\n    label = \\\"test4\\\"\\n  },\\n  {\\n    value = 14,\\n    label = \\\"test5\\\"\\n  }\\n})\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Outputting data to a flow is optional\",\n  \"body\": \"Even though writing data to a flow is probably one of the most common operations that our embedded Lua scripts perform, you are not _required_ to do so in every script you write. The result of commands that do not result in an assignment to a property, such as variable assignments and free-form expressions like function calls, is simply discarded.\\n\\nIf the script associated with a job does not output any data to a flow, the Agent simply does not send data to the API.\"\n}\n[/block]\n# Conditional statements\n\nAn [if-then-else](http://www.lua.org/pil/4.3.1.html) statement allows you to perform separate sets of commands depending on a Boolean expression. Their format is as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local a = 10\\n\\nif a < 10 then\\n\\tlocal value = a\\nelseif a == 5\\n  local value = a\\nelse\\n\\tlocal value = 10\\nend\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\nNote that `else` and `elseif` blocks are optional. Multiple `elseif` or nested `if` statements are supported.\n\n# Loops \n\nLua supports several types of loop structures including [while](http://www.lua.org/pil/4.3.2.html), [repeat](http://www.lua.org/pil/4.3.3.html), [numeric for](http://www.lua.org/pil/4.3.4.html), and [generic for](http://www.lua.org/pil/4.3.5.html):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-- While\\nlocal i = 0\\nwhile i < 100 do\\n  print(i)\\n\\ti = i + 1\\nend\\n\\n-- Repeat\\n-- Similar to a do-while in other languages\\nlocal i = 0\\nrepeat\\n  print(i)\\n\\ti = i + 1\\nuntil i == 100\\n\\n-- Numeric for\\n-- Similar to a counted for(i = 0; 1 < 100; i++) in other languages\\nfor i = 0, 100, 1 do\\n\\tprint(i)\\nend\\n\\n-- Generic for\\n-- Similar to a for each in other languages\\nlocal table = { one = 1, two = 2, three = 3 }\\nfor k, v in pairs(table) do\\n  print(k, v)\\nend\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"lua-introduction","type":"basic","title":"Introduction"}
Lua is a general-purpose scripting language that has been integrated into the Telemetry Agent to allow users to easily perform Agent-specific tasks such as: - Extracting data from a time series stored in the Agent's data management system - Manipulating a counter (also in the data management system) - Checking for specific conditions that may trigger one or more changes in a flow (e.g.: set a color to red if a certain value exceeds a predefined threshold) - Sending notifications to the API This capability is available while also offering the freedom of a general-purpose language. All of Lua's functionality is available when writing scripts for the Agent. You can review the [Lua reference manual](http://www.lua.org/manual/5.3/) for a full overview of this functionality. The following section will introduce some of the basics of the Lua language. # Data Types Lua has eight basic [data types](http://www.lua.org/pil/2.html). These are: - [Numbers](http://www.lua.org/pil/2.3.html), expressed solely as double-precision floating point​ values. The distinction between integer and floating-point numbers are determined automatically as needed. - [Strings](http://www.lua.org/pil/2.4.html), expressed as UTF-8 sequences delimited by either single or double quotation marks. A backslash can be used to escape a quotation mark inside a string. - [Boolean](http://www.lua.org/pil/2.2.html) values can be assigned the value `true` and `false`. Traditional logical operations, such as `or`, `and`, and `not` are supported. Numbers evaluate to `true` even if they are zero. Strings always evaluate to `true` even when empty. - [Tables](http://www.lua.org/pil/2.5.html) are associative arrays enclosed in braces `{}`. Values can be associated with either a numerical index or keys which are case-sensitive string identifiers. Traditional arrays can be specified by wrapping the table in the `array()` function. - Additional types include [Nil](http://www.lua.org/pil/2.1.html), [Functions](http://www.lua.org/pil/2.6.html), [Userdata, and Threads](http://www.lua.org/pil/2.7.html) Here are some examples: [block:code] { "codes": [ { "code": "-- Numbers\n123\n28.392\n-192.1\n\n12 + 20\n(10 + 20) * 10\n\n-- Strings\n\"A string with double quotation marks\"\n'A string with single quotation marks'\n\"A string with \\\"escaped quotation marks\\\"\"\n\n-- Boolean\ntrue\nfalse\ntrue and false\nnot true\n\n-- Table\nlocal t = { test = 1, [\"Test\"] = 2, [\"Another Test\"] = 3}\nt[\"one last test\"] = 4\n\nlocal a = array( {0, 1, 2, 3} )", "language": "lua" } ] } [/block] # Comments Lua recognizes single-line comments beginning with two hyphens (--) or multi-line comments beginning with two hyphens and a two open brackets (--[[) followed by two hyphens and two closing brackets (--]]). For example: [block:code] { "codes": [ { "code": "-- This is a single-line comment\n\n--[[\n\tThis is a multi-line comment\n--]]", "language": "lua" } ] } [/block] # Variables As in any other language, variables are containers of data. Lua is loosely typed; therefore, variables take on the type of the value that is assigned to them at any given time. Variables by default are assigned to the global namespace. Local variables must be preceded by the `local` keyword when being declared. Data can be assigned to a variable with the `=` operator. For example: [block:code] { "codes": [ { "code": "-- A global variable\na = 10\n-- A local variable\nlocal b = 20\n\n-- Variables can be used in expressions\na + b\na == b", "language": "lua" } ] } [/block] # Populating Telemetry flows Telemetry flows are populated using the `output` global table variable. To send data to a flow, all that you need to do is append a flow's property to the `output` table. For example, if you have a `number` flow: [block:code] { "codes": [ { "code": "local a = 10\n\noutput.number = {\n value = a\n}", "language": "lua" } ] } [/block] Here is a more complex example, this time for a pie chart flow: [block:code] { "codes": [ { "code": "output.slices = array({\n {\n value = 12,\n label = \"test1\"\n },\n {\n value = 52,\n label = \"test2\"\n },\n {\n value = 22,\n label = \"test3\"\n },\n {\n value = 16,\n label = \"test4\"\n },\n {\n value = 14,\n label = \"test5\"\n }\n})", "language": "lua" } ] } [/block] [block:callout] { "type": "info", "title": "Outputting data to a flow is optional", "body": "Even though writing data to a flow is probably one of the most common operations that our embedded Lua scripts perform, you are not _required_ to do so in every script you write. The result of commands that do not result in an assignment to a property, such as variable assignments and free-form expressions like function calls, is simply discarded.\n\nIf the script associated with a job does not output any data to a flow, the Agent simply does not send data to the API." } [/block] # Conditional statements An [if-then-else](http://www.lua.org/pil/4.3.1.html) statement allows you to perform separate sets of commands depending on a Boolean expression. Their format is as follows: [block:code] { "codes": [ { "code": "local a = 10\n\nif a < 10 then\n\tlocal value = a\nelseif a == 5\n local value = a\nelse\n\tlocal value = 10\nend", "language": "lua" } ] } [/block] Note that `else` and `elseif` blocks are optional. Multiple `elseif` or nested `if` statements are supported. # Loops Lua supports several types of loop structures including [while](http://www.lua.org/pil/4.3.2.html), [repeat](http://www.lua.org/pil/4.3.3.html), [numeric for](http://www.lua.org/pil/4.3.4.html), and [generic for](http://www.lua.org/pil/4.3.5.html): [block:code] { "codes": [ { "code": "-- While\nlocal i = 0\nwhile i < 100 do\n print(i)\n\ti = i + 1\nend\n\n-- Repeat\n-- Similar to a do-while in other languages\nlocal i = 0\nrepeat\n print(i)\n\ti = i + 1\nuntil i == 100\n\n-- Numeric for\n-- Similar to a counted for(i = 0; 1 < 100; i++) in other languages\nfor i = 0, 100, 1 do\n\tprint(i)\nend\n\n-- Generic for\n-- Similar to a for each in other languages\nlocal table = { one = 1, two = 2, three = 3 }\nfor k, v in pairs(table) do\n print(k, v)\nend", "language": "lua" } ] } [/block]