{"_id":"57fcc4870312b20e00ac64e1","project":"5435687035740020002a1c04","__v":0,"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,"user":"5589fde775eaf50d004e4b0c","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"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-06T00:23:25.857Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"A counter is simply a named _integer_ numeric value. The Agent's data manager manages access to counters and allows them to be manipulated either through the Graphite extended interface or through a Lua script.\n\nIn Lua, counters can be accessed using the `counter()` function (exposed by the `telemetry/storage` library), which expects one parameter:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The case-sensitive name of the counter (required).\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\nCounter names must start with a letter, and can contain letters, numbers, underscores, and periods. There is no pre-set limit to the length of a counter's name.\n\nThe return value of a call to `counter()` provides a reference to the counter. Use the `value()` function to retrieve the counter's current value. For example:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\nlocal counter = st.counter(\\\"test\\\")\\n\\nlocal value = counter.value()\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Counters do not need to be explicitly created\",\n  \"body\": \"There is no need to “create” a counter. The Agent automatically create a counter with a value of 0 if it doesn't find one with the name you specified.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Counters are integers!\",\n  \"body\": \"Always remember that counters are _integer_ numbers. If you attempt to assign or increment a counter by a floating-point value, the fractional portion of the latter is discarded.\\n\\nOf course, you can work around this issue by multiplying your floating-point values by a power of ten to isolate a given number of decimal numbers, and then dividing the data you retrieve from a counter as needed. Counters are stored internally as 64-bit signed integers, providing you with plenty of numeric resolution.\"\n}\n[/block]\n## Incrementing a counter\n\nCounter expressions expose an `increment()` function that allows you to add or subtract a number from the counter in a thread-safe manner. It supports one argument:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`delta`\",\n    \"0-1\": \"Number\",\n    \"0-2\": \"The increment value (use negative numbers to _decrement_ a counter instead) (required).\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\nlocal counter = st.counter(\\\"test\\\")\\n\\ncounter.increment(10)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\n## Setting a counter\n\nThe `set()` function of a counter expression can be used to set the counter to a specific value (including, of course, zero). It supports one argument:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`value`\",\n    \"0-1\": \"Number\",\n    \"0-2\": \"The new value (required).\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\nlocal counter = st.counter(\\\"test\\\")\\n\\ncounter.set(0)\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"accessing-counters-from-lua","type":"basic","title":"Counters"}
A counter is simply a named _integer_ numeric value. The Agent's data manager manages access to counters and allows them to be manipulated either through the Graphite extended interface or through a Lua script. In Lua, counters can be accessed using the `counter()` function (exposed by the `telemetry/storage` library), which expects one parameter: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`name`", "0-1": "string", "0-2": "The case-sensitive name of the counter (required)." }, "cols": 3, "rows": 1 } [/block] Counter names must start with a letter, and can contain letters, numbers, underscores, and periods. There is no pre-set limit to the length of a counter's name. The return value of a call to `counter()` provides a reference to the counter. Use the `value()` function to retrieve the counter's current value. For example: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\nlocal counter = st.counter(\"test\")\n\nlocal value = counter.value()", "language": "lua" } ] } [/block] [block:callout] { "type": "info", "title": "Counters do not need to be explicitly created", "body": "There is no need to “create” a counter. The Agent automatically create a counter with a value of 0 if it doesn't find one with the name you specified." } [/block] [block:callout] { "type": "warning", "title": "Counters are integers!", "body": "Always remember that counters are _integer_ numbers. If you attempt to assign or increment a counter by a floating-point value, the fractional portion of the latter is discarded.\n\nOf course, you can work around this issue by multiplying your floating-point values by a power of ten to isolate a given number of decimal numbers, and then dividing the data you retrieve from a counter as needed. Counters are stored internally as 64-bit signed integers, providing you with plenty of numeric resolution." } [/block] ## Incrementing a counter Counter expressions expose an `increment()` function that allows you to add or subtract a number from the counter in a thread-safe manner. It supports one argument: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`delta`", "0-1": "Number", "0-2": "The increment value (use negative numbers to _decrement_ a counter instead) (required)." }, "cols": 3, "rows": 1 } [/block] For example: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\nlocal counter = st.counter(\"test\")\n\ncounter.increment(10)", "language": "lua" } ] } [/block] ## Setting a counter The `set()` function of a counter expression can be used to set the counter to a specific value (including, of course, zero). It supports one argument: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "`value`", "0-1": "Number", "0-2": "The new value (required)." }, "cols": 3, "rows": 1 } [/block] For example: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\nlocal counter = st.counter(\"test\")\n\ncounter.set(0)", "language": "lua" } ] } [/block]