{"_id":"57fcc4870312b20e00ac64f8","category":{"_id":"57fcc4860312b20e00ac64c9","__v":0,"version":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-05-01T21:33:28.863Z","from_sync":false,"order":8,"slug":"integration-examples","title":"Integration Examples"},"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":1,"parentDoc":null,"user":"5435682035740020002a1c01","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-27T20:38:17.982Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Source Code Available\",\n  \"body\": \"The source code for this example is available on the [Telemetry Agents Examples ](https://github.com/telemetryapp/agent_examples/tree/master/graphite) Github repository.\"\n}\n[/block]\nThis brief guide serves to help you get familiar with streaming data to Telemetry using the Telemetry Agent and its support for the Graphite protocol.  Within this demo, we'll send some sample data and view it on a dashboard along with receiving notifications. \n\nWe'll send CPU data from your system to Telemetry and render it as a gauge.  We'll also send a notification when the CPU exceeds 50%.   \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b6zNVGTCRR2Uo6288PdT_methods.png\",\n        \"methods.png\",\n        \"1122\",\n        \"538\",\n        \"#2ba1f8\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n# Requirements \n\nYou'll need an OSX or Linux computer system to run through this guide.  Windows is supported with Telemetry but some of the details here would be slightly different and thus it's out of scope.\n\n# Installation \n\nYou'll need to install two pieces of software,  our Telemetry Agent, and Sysstatsd.  We created Syststatsd as a sample project that generates simple Graphite data for your system you install it on.  You can find details on how to install these two packages in their respective Github pages:\n\n- [Telemetry Agent](https://github.com/telemetryapp/gotelemetry_agent/releases)\n- [Sysstatsd](https://github.com/telemetryapp/sysstatsd/releases)\n\n# Configure Board\n\nVisit the [Telemetry Manager application](https://manager.telemetryapp.com), login and either create a new board or use an existing one.   Add a gauge to the board and take note of the *flow_tag*.  You'll use this tag to send data to.  \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/96e01e3-Screen_Shot_2017-07-26_at_10.42.52_AM.png\",\n        \"Screen Shot 2017-07-26 at 10.42.52 AM.png\",\n        263,\n        170,\n        \"#232a34\"\n      ]\n    }\n  ]\n}\n[/block]\n# Configure Agent\n\nNext, we'll need to configure the agent to pick up Graphite data and send it to Telemetry. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#\\n# Server Configuration Parameters\\n#\\n\\n[server]\\n# API token found in the Agents tab in manager.telemetryapp.com\\napi_token = \\\"abc123abc123abc123abc123abc123abc123\\\"\\n# Submit new metrics in a batch at most every 1 second\\nsubmission_interval = \\\"1s\\\"\\n\\n#\\n# Local data storage for aggregation and graphite data\\n#\\n\\n[data]\\n# Location to store\\n# path = \\\"c:\\\\\\\\telemetry_agent.db\\\"\\n# WINDOWS USERS - Uncomment the line above and comment or remove the line below\\npath = \\\"/tmp/telemetry_agent.db\\\"\\n# Expire data after 7 days\\nttl = \\\"7d\\\"\\n\\n#\\n# Graphite Configuration Parameters\\n#\\n\\n[graphite]\\n# Listen on UDP port 2003 on all interfaces for Graphite data\\nlisten_udp = \\\":2003\\\"\\n\\n#\\n# Flow Configurations \\n#\\n\\n#\\n# A specific flow\\n#\\n[[flow]]\\n# The flow tag\\ntag = \\\"graphite_gauge_1\\\"\\n# run the script every 2 seconds\\ninterval = \\\"2s\\\"\\n# The Lua script to run to generate updates\\nscript = \\\"graphite.lua\\\"\",\n      \"language\": \"toml\"\n    }\n  ]\n}\n[/block]\n# Start Sysstatsd\n\nStart up Systatsd, tell it to report CPU statistics to your localhost on port 2003 (replace this if you've selected a different host and port for the Agent to run on). \n\n    sysstatsd -c -s localhost:2003\n    \nSysstatsd will send four graphite data points as HOSTNAME.cpu.user, HOSTNAME.cpu.sys, HOSTNAME.cpu.wait, HOSTNAME.cpu.idle every one second.\n\n\n# Handle Metrics\n\nNext you want to take data from the graphite CPU user graphite series and send metrics to the gauge you've created.\n\nMaking sure to replace **HOSTNAME** with your hostname, create a graphite.lua file with the contents:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local st = require(\\\"telemetry/storage\\\")\\n\\n-- Get the last value of the graphite CPU User stats\\n-- Replace HOSTNAME with your local systems hostname\\n-- Assign this value to the cpu local variable\\nlocal cpu = st.series(\\\"HOSTNAME.cpu.user\\\").last()\\n\\n-- Set the number flow 'value' property to the CPU user\\n-- Set the 'type' to 'percent'\\noutput.number = {value = cpu, type = \\\"percent\\\"}\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\nWith the agent binary and the config file in the same directory start the agent by typing in your console:\n\n    telemetry_agent -c config.toml\n    \nIf you're having trouble running the agent you can get more information through increasing the logging verbosity (try -v debug as a command line option).\n\n# Handle Notifications\n\nFinally, we'll send notifications if the CPU is greater than 50%. Modify the graphite.lua file with the following to send notifications:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"local n = require(\\\"telemetry/notifications\\\")\\n\\n-- Send a notification if the CPU is too high\\nif cpu > 50 then\\n  n.post(\\\"\\\", \\\"graphite_gauge_1\\\", \\\"High CPU\\\", \\\"CPU usage has exceeded 50%\\\")\\nend\",\n      \"language\": \"lua\"\n    }\n  ]\n}\n[/block]\nIf you save the changes to the graphite.lua file the agent should pick them up immediately and begin sending them when your CPU exceeds 50%.\n\n# Viewing your Board and Notifications\n\nGo to [https://viewer.telemetryapp.com](https://viewer.telemetryapp.com) to create a new viewer and input its pairing code in the manager at [https://manager.telemetryapp.com/viewers](https://manager.telemetryapp.com/viewers) \n\nIf you do something that consumes a lot of CPU (such as reloading a heavy web page like www.theverge.com a couple times in your browser) you should see a notification being sent to your viewer.\n\n\n# More Graphite Sources\n\nObviously, this is a trivial example.  Graphite is a well supported protocol with many projects integrating and generating graphite data.  You should be able to send all this graphite data to a Telemetry agent.    Good places to start are with the [Collectd Project](https://collectd.org), [Statsd](https://github.com/etsy/statsd) and Graphite's list of [tools that work with Graphite](https://graphite.readthedocs.org/en/latest/tools.html)","excerpt":"","slug":"graphite-example","type":"basic","title":"Graphite"}
[block:callout] { "type": "info", "title": "Source Code Available", "body": "The source code for this example is available on the [Telemetry Agents Examples ](https://github.com/telemetryapp/agent_examples/tree/master/graphite) Github repository." } [/block] This brief guide serves to help you get familiar with streaming data to Telemetry using the Telemetry Agent and its support for the Graphite protocol. Within this demo, we'll send some sample data and view it on a dashboard along with receiving notifications. We'll send CPU data from your system to Telemetry and render it as a gauge. We'll also send a notification when the CPU exceeds 50%. [block:image] { "images": [ { "image": [ "https://files.readme.io/b6zNVGTCRR2Uo6288PdT_methods.png", "methods.png", "1122", "538", "#2ba1f8", "" ] } ] } [/block] # Requirements You'll need an OSX or Linux computer system to run through this guide. Windows is supported with Telemetry but some of the details here would be slightly different and thus it's out of scope. # Installation You'll need to install two pieces of software, our Telemetry Agent, and Sysstatsd. We created Syststatsd as a sample project that generates simple Graphite data for your system you install it on. You can find details on how to install these two packages in their respective Github pages: - [Telemetry Agent](https://github.com/telemetryapp/gotelemetry_agent/releases) - [Sysstatsd](https://github.com/telemetryapp/sysstatsd/releases) # Configure Board Visit the [Telemetry Manager application](https://manager.telemetryapp.com), login and either create a new board or use an existing one. Add a gauge to the board and take note of the *flow_tag*. You'll use this tag to send data to. [block:image] { "images": [ { "image": [ "https://files.readme.io/96e01e3-Screen_Shot_2017-07-26_at_10.42.52_AM.png", "Screen Shot 2017-07-26 at 10.42.52 AM.png", 263, 170, "#232a34" ] } ] } [/block] # Configure Agent Next, we'll need to configure the agent to pick up Graphite data and send it to Telemetry. [block:code] { "codes": [ { "code": "#\n# Server Configuration Parameters\n#\n\n[server]\n# API token found in the Agents tab in manager.telemetryapp.com\napi_token = \"abc123abc123abc123abc123abc123abc123\"\n# Submit new metrics in a batch at most every 1 second\nsubmission_interval = \"1s\"\n\n#\n# Local data storage for aggregation and graphite data\n#\n\n[data]\n# Location to store\n# path = \"c:\\\\telemetry_agent.db\"\n# WINDOWS USERS - Uncomment the line above and comment or remove the line below\npath = \"/tmp/telemetry_agent.db\"\n# Expire data after 7 days\nttl = \"7d\"\n\n#\n# Graphite Configuration Parameters\n#\n\n[graphite]\n# Listen on UDP port 2003 on all interfaces for Graphite data\nlisten_udp = \":2003\"\n\n#\n# Flow Configurations \n#\n\n#\n# A specific flow\n#\n[[flow]]\n# The flow tag\ntag = \"graphite_gauge_1\"\n# run the script every 2 seconds\ninterval = \"2s\"\n# The Lua script to run to generate updates\nscript = \"graphite.lua\"", "language": "toml" } ] } [/block] # Start Sysstatsd Start up Systatsd, tell it to report CPU statistics to your localhost on port 2003 (replace this if you've selected a different host and port for the Agent to run on). sysstatsd -c -s localhost:2003 Sysstatsd will send four graphite data points as HOSTNAME.cpu.user, HOSTNAME.cpu.sys, HOSTNAME.cpu.wait, HOSTNAME.cpu.idle every one second. # Handle Metrics Next you want to take data from the graphite CPU user graphite series and send metrics to the gauge you've created. Making sure to replace **HOSTNAME** with your hostname, create a graphite.lua file with the contents: [block:code] { "codes": [ { "code": "local st = require(\"telemetry/storage\")\n\n-- Get the last value of the graphite CPU User stats\n-- Replace HOSTNAME with your local systems hostname\n-- Assign this value to the cpu local variable\nlocal cpu = st.series(\"HOSTNAME.cpu.user\").last()\n\n-- Set the number flow 'value' property to the CPU user\n-- Set the 'type' to 'percent'\noutput.number = {value = cpu, type = \"percent\"}", "language": "lua" } ] } [/block] With the agent binary and the config file in the same directory start the agent by typing in your console: telemetry_agent -c config.toml If you're having trouble running the agent you can get more information through increasing the logging verbosity (try -v debug as a command line option). # Handle Notifications Finally, we'll send notifications if the CPU is greater than 50%. Modify the graphite.lua file with the following to send notifications: [block:code] { "codes": [ { "code": "local n = require(\"telemetry/notifications\")\n\n-- Send a notification if the CPU is too high\nif cpu > 50 then\n n.post(\"\", \"graphite_gauge_1\", \"High CPU\", \"CPU usage has exceeded 50%\")\nend", "language": "lua" } ] } [/block] If you save the changes to the graphite.lua file the agent should pick them up immediately and begin sending them when your CPU exceeds 50%. # Viewing your Board and Notifications Go to [https://viewer.telemetryapp.com](https://viewer.telemetryapp.com) to create a new viewer and input its pairing code in the manager at [https://manager.telemetryapp.com/viewers](https://manager.telemetryapp.com/viewers) If you do something that consumes a lot of CPU (such as reloading a heavy web page like www.theverge.com a couple times in your browser) you should see a notification being sent to your viewer. # More Graphite Sources Obviously, this is a trivial example. Graphite is a well supported protocol with many projects integrating and generating graphite data. You should be able to send all this graphite data to a Telemetry agent. Good places to start are with the [Collectd Project](https://collectd.org), [Statsd](https://github.com/etsy/statsd) and Graphite's list of [tools that work with Graphite](https://graphite.readthedocs.org/en/latest/tools.html)