{"_id":"57fcc4870312b20e00ac64e6","parentDoc":null,"__v":0,"category":{"_id":"57fcc4860312b20e00ac64c7","__v":0,"version":"57fcc4860312b20e00ac64c0","project":"5435687035740020002a1c04","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-25T22:05:12.981Z","from_sync":false,"order":6,"slug":"agent-integration","title":"Data Agent"},"project":"5435687035740020002a1c04","user":"547d27d12eaee50800ed1157","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-04-29T12:13:14.731Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Agent Not Required\",\n  \"body\": \"Designed to support Dashboards and data-driven​ Digital Signage the Agent isn't required to use TelemetryTV, indeed many users needing to send data to TelemetryTV send metrics directly to the TelemetryTV API.  The Agent is convenience software, removing the need to worry about scheduling, API formats, aggregation and more.\"\n}\n[/block]\nThe TelemetryTV Agent is an application designed to simplify integrating external systems with the TelemetryTV API by scheduling and submitting metrics on your behalf.  The Agent is typically run as a software daemon, in the background as a service. \n\nBy using the Agent, you have the opportunity to remove nearly all the complexity associated with pushing metrics to TelemetryTV, and focus exclusively on getting the most out of your data.\n\nThe Agent is free and open-source, and the sources can be accessed on our [Github page](https://github.com/telemetryapp/gotelemetry_agent). We also provide binaries for Windows, Linux, and OS X.\n\nThe Agent serves to perform several important functions that you'd otherwise have to handle yourself:\n\n- Handles communication to the TelemetryTV API\n- Scheduled updates and ensures they occur on a deterministic basis\n- Aggregates metrics allowing you to gather data before it leaves your system\n- Performs analysis on streamed data allowing for anomaly detection and the like\n\n# Small Cross-Platform Binary\n\nThe agent is deployed as a small binary application that typically consumes less than 10MB of memory.  It's also cross-platform, allowing it to be deployed on OS X, Linux, and Windows. \n \n\n# One or Many Agents?\n\nYou should try to deploy agents as close to the data as possible.  This allows for aggregation to occur early in the stream, saving network and system resources.    Whether you deploy a single agent or many agents really is going to be determined by your environment.   \n\n# Inside the Firewall and Near your Data \n\nThe agent is designed to be deployed inside your firewall next to your data.   This allows you to keep your data proprietary to you while only sending the derived metrics you need to TelemetryTV.   Residing inside the firewall allows you to push these metrics out, rather than having to set up an API that something needs to reach in through the firewall to bring data out.   This will help satisfy many security and compliance requirements that many organizations are required to follow for data protection.\n\n# Three Integration Methods\n\nThe Agent Provides three broad integration methods:\n\n**Executable Programs** -  This is where you have an executable on your computer that when run it will do something, generate a TelemetryTV metrics data structure for a particular flow, print it to standard out and exit.   The agent will then take this output and forward it to the TelemetryTV API.    This lets you use virtually any language and data store in order to send metrics to TelemetryTV.  See the [Executables](doc:executables) documentation page for more information on how to integrate executables with the agent.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/StC5aPL7QuC4CAmaIm0v_exec.png\",\n        \"exec.png\",\n        \"993\",\n        \"210\",\n        \"#1097f8\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**Lua Script** - The TelemetryTV Agent embeds the Lua language.   We provide extensions to Lua to ease the integration of external data sources like Graphite,  JSON API's and even Excel documents.   Typically Lua scripts are quite brief and to the point.   If you need more power than Lua is able to deliver you'll want to look at having an executable program instead.  See the [Lua Scripts](doc:asl-scripts) documentation page for more information on how to integrate Lua scripts with the agent.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/qwry9G50Qxm4sWRVNMFX_methods.png\",\n        \"methods.png\",\n        \"1405\",\n        \"369\",\n        \"#5a8f1c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**Graphite & Lua** - TelemetryTV supports the [Graphite protocol](http://graphite.readthedocs.org).  This does not let you send data directly to TelemetryTV, but rather to the agent.  You then must use a Lua script to extract this data and derive metrics for use in a Telemetry flow.  See the [Graphite](doc:graphite) documentation page for more information on how to integrate Graphite data sources with the agent\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/dGwXo6wTqiaKWGZMXg6L_methods.png\",\n        \"methods.png\",\n        \"1122\",\n        \"538\",\n        \"#2ba1f8\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n# Getting Started\n\nTo get started you'll need to [install the agent](doc:agent-setup) and [configure it](doc:agent-configuration-file).","excerpt":"","slug":"telemetry-agent","type":"basic","title":"Introduction"}
[block:callout] { "type": "info", "title": "Agent Not Required", "body": "Designed to support Dashboards and data-driven​ Digital Signage the Agent isn't required to use TelemetryTV, indeed many users needing to send data to TelemetryTV send metrics directly to the TelemetryTV API. The Agent is convenience software, removing the need to worry about scheduling, API formats, aggregation and more." } [/block] The TelemetryTV Agent is an application designed to simplify integrating external systems with the TelemetryTV API by scheduling and submitting metrics on your behalf. The Agent is typically run as a software daemon, in the background as a service. By using the Agent, you have the opportunity to remove nearly all the complexity associated with pushing metrics to TelemetryTV, and focus exclusively on getting the most out of your data. The Agent is free and open-source, and the sources can be accessed on our [Github page](https://github.com/telemetryapp/gotelemetry_agent). We also provide binaries for Windows, Linux, and OS X. The Agent serves to perform several important functions that you'd otherwise have to handle yourself: - Handles communication to the TelemetryTV API - Scheduled updates and ensures they occur on a deterministic basis - Aggregates metrics allowing you to gather data before it leaves your system - Performs analysis on streamed data allowing for anomaly detection and the like # Small Cross-Platform Binary The agent is deployed as a small binary application that typically consumes less than 10MB of memory. It's also cross-platform, allowing it to be deployed on OS X, Linux, and Windows. # One or Many Agents? You should try to deploy agents as close to the data as possible. This allows for aggregation to occur early in the stream, saving network and system resources. Whether you deploy a single agent or many agents really is going to be determined by your environment. # Inside the Firewall and Near your Data The agent is designed to be deployed inside your firewall next to your data. This allows you to keep your data proprietary to you while only sending the derived metrics you need to TelemetryTV. Residing inside the firewall allows you to push these metrics out, rather than having to set up an API that something needs to reach in through the firewall to bring data out. This will help satisfy many security and compliance requirements that many organizations are required to follow for data protection. # Three Integration Methods The Agent Provides three broad integration methods: **Executable Programs** - This is where you have an executable on your computer that when run it will do something, generate a TelemetryTV metrics data structure for a particular flow, print it to standard out and exit. The agent will then take this output and forward it to the TelemetryTV API. This lets you use virtually any language and data store in order to send metrics to TelemetryTV. See the [Executables](doc:executables) documentation page for more information on how to integrate executables with the agent. [block:image] { "images": [ { "image": [ "https://files.readme.io/StC5aPL7QuC4CAmaIm0v_exec.png", "exec.png", "993", "210", "#1097f8", "" ] } ] } [/block] **Lua Script** - The TelemetryTV Agent embeds the Lua language. We provide extensions to Lua to ease the integration of external data sources like Graphite, JSON API's and even Excel documents. Typically Lua scripts are quite brief and to the point. If you need more power than Lua is able to deliver you'll want to look at having an executable program instead. See the [Lua Scripts](doc:asl-scripts) documentation page for more information on how to integrate Lua scripts with the agent. [block:image] { "images": [ { "image": [ "https://files.readme.io/qwry9G50Qxm4sWRVNMFX_methods.png", "methods.png", "1405", "369", "#5a8f1c", "" ] } ] } [/block] **Graphite & Lua** - TelemetryTV supports the [Graphite protocol](http://graphite.readthedocs.org). This does not let you send data directly to TelemetryTV, but rather to the agent. You then must use a Lua script to extract this data and derive metrics for use in a Telemetry flow. See the [Graphite](doc:graphite) documentation page for more information on how to integrate Graphite data sources with the agent [block:image] { "images": [ { "image": [ "https://files.readme.io/dGwXo6wTqiaKWGZMXg6L_methods.png", "methods.png", "1122", "538", "#2ba1f8", "" ] } ] } [/block] # Getting Started To get started you'll need to [install the agent](doc:agent-setup) and [configure it](doc:agent-configuration-file).