{"_id":"57fcc4870312b20e00ac64ec","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":"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"},"parentDoc":null,"project":"5435687035740020002a1c04","user":"5435682035740020002a1c01","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-05-01T21:38:55.084Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"Metrics can be sent both over UDP or TCP using a simple plain-text protocol that is compatible with the Graphite protocol.  Thus the Agent can function as a drop-in replacement for a Graphite server in your existing infrastructure.\n\nThis feature is meant to provide TelemetryTV users with a simple way to coordinate the collection of metrics from multiple sources, and simplify a large class of operations, such as aggregations and statistical analysis, that would otherwise require either specialized tools or significant coding effort.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Existing Graphite Tools\",\n  \"body\": \"There are many existing open source and commercial Graphite projects,  too many to list here individually.  You can read more about Graphite and find existing tools on the [Graphite Website](https://graphite.readthedocs.org/en/latest/)\"\n}\n[/block]\n# Types of Metrics\n\nThe Agent supports two kinds of metrics:\n\n- **Counters** are signed 64-bit integer values. They can bet set to arbitrary values, and incremented (or decremented) in a thread-safe way by multiple concurrent external providers.\n- **Series** are collections of floating-point values associated with a specific timestamp. You can push metrics to a series from multiple sources, aggregate them by date, and perform statistical analysis on them.\n\nYou can use the Agent's [integrated Lua support](doc:lua-introduction) to programmatically combine the two types of values and extend their functionality. For example, you could use a counter to determine the number of workers active at any given time—incrementing the value by one every time a new worker comes online, and decrementing it when it goes offline—and then periodically integrate the then-current value into a series to provide a historical record of worker activity.\n\nThe Agent expects metrics to be sent to it over the network; this approach works well both in the case in which the Agent runs on the same machine as the process that generates the metrics, and in the case where the Agent runs on dedicated hardware and must collect information from multiple sources distributed across multiple servers.\n\n# Sending Metrics to a Series\n\nYou can add a data point to a series by sending a plain-text packet to the Agent using this format:\n\n`<name> <value> <timestamp>`\n\nHere, `<name>` is the name of the series you wish to populate; names must start with a letter and can contain letters, digits, periods, and underscores. Typically—especially in an environment the contains many different data sources—you will want to give your series a name that reflects some kind of hierarchical structure (e.g.: `db.virginia.load.server-23`), but this is not a requirement.\n\nThe `<value>` parameter is the textual representation of the signed floating-point value that you want to insert in the Agent's data store. The Agent only accept decimal values; you cannot use scientific notation or hex strings.\n\nFinally, the `<timestamp>` parameter is a textual representation of the UNIX timestamp at which the data point should be recorded in the series.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Be mindful of latency\",\n  \"body\": \"It's important to consider latency when submitting data to the Agent. The fact that a particular data point was _sent_ at a given moment in time does not necessarily mean that it will be inserted in the Agent's data store at the same time.\\n\\nAll kinds of unpredictable factors, including network lag, congestion, and load on the Agent's machine, could cause the data point to be inserted with potentially significant delay, causing fluctuations in the accuracy of the resulting statistical analysis.\"\n}\n[/block]\n# Sending Metrics to a Counter \n\nThe Graphite protocol makes no allowance for counters, but the Agent extends the plain-text protocol to let you sending metrics to them. For example:\n\n`<name> <value>`\n\nLike with data series, `name` is the name of the counter that you wish to modify, where value can be one of the following:\n\n- A numeric value, which replaces the counter's current value (e.g.: `123.32`)\n- A positive delta, which increments the counter's current value (e.g.: `+1`)\n- A negative delta, which _decrements_ the counter's current value (e.g.: `-123.11`)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Consider concurrency\",\n  \"body\": \"Counters can be safely incremented and decremented by multiple sources at the same time. You should, however, only use the value replacement function from a single source, because multiple sources will simply overwrite each other.\"\n}\n[/block]\n# Examples\n\nPlease see the [Graphite Configuration Example](doc:graphite-example) and the [Logfile Configuration Example](doc:tailing-logfiles) for examples on how to integrate Graphite with TelemetryTV.","excerpt":"","slug":"graphite","type":"basic","title":"Graphite"}
Metrics can be sent both over UDP or TCP using a simple plain-text protocol that is compatible with the Graphite protocol. Thus the Agent can function as a drop-in replacement for a Graphite server in your existing infrastructure. This feature is meant to provide TelemetryTV users with a simple way to coordinate the collection of metrics from multiple sources, and simplify a large class of operations, such as aggregations and statistical analysis, that would otherwise require either specialized tools or significant coding effort. [block:callout] { "type": "info", "title": "Existing Graphite Tools", "body": "There are many existing open source and commercial Graphite projects, too many to list here individually. You can read more about Graphite and find existing tools on the [Graphite Website](https://graphite.readthedocs.org/en/latest/)" } [/block] # Types of Metrics The Agent supports two kinds of metrics: - **Counters** are signed 64-bit integer values. They can bet set to arbitrary values, and incremented (or decremented) in a thread-safe way by multiple concurrent external providers. - **Series** are collections of floating-point values associated with a specific timestamp. You can push metrics to a series from multiple sources, aggregate them by date, and perform statistical analysis on them. You can use the Agent's [integrated Lua support](doc:lua-introduction) to programmatically combine the two types of values and extend their functionality. For example, you could use a counter to determine the number of workers active at any given time—incrementing the value by one every time a new worker comes online, and decrementing it when it goes offline—and then periodically integrate the then-current value into a series to provide a historical record of worker activity. The Agent expects metrics to be sent to it over the network; this approach works well both in the case in which the Agent runs on the same machine as the process that generates the metrics, and in the case where the Agent runs on dedicated hardware and must collect information from multiple sources distributed across multiple servers. # Sending Metrics to a Series You can add a data point to a series by sending a plain-text packet to the Agent using this format: `<name> <value> <timestamp>` Here, `<name>` is the name of the series you wish to populate; names must start with a letter and can contain letters, digits, periods, and underscores. Typically—especially in an environment the contains many different data sources—you will want to give your series a name that reflects some kind of hierarchical structure (e.g.: `db.virginia.load.server-23`), but this is not a requirement. The `<value>` parameter is the textual representation of the signed floating-point value that you want to insert in the Agent's data store. The Agent only accept decimal values; you cannot use scientific notation or hex strings. Finally, the `<timestamp>` parameter is a textual representation of the UNIX timestamp at which the data point should be recorded in the series. [block:callout] { "type": "warning", "title": "Be mindful of latency", "body": "It's important to consider latency when submitting data to the Agent. The fact that a particular data point was _sent_ at a given moment in time does not necessarily mean that it will be inserted in the Agent's data store at the same time.\n\nAll kinds of unpredictable factors, including network lag, congestion, and load on the Agent's machine, could cause the data point to be inserted with potentially significant delay, causing fluctuations in the accuracy of the resulting statistical analysis." } [/block] # Sending Metrics to a Counter The Graphite protocol makes no allowance for counters, but the Agent extends the plain-text protocol to let you sending metrics to them. For example: `<name> <value>` Like with data series, `name` is the name of the counter that you wish to modify, where value can be one of the following: - A numeric value, which replaces the counter's current value (e.g.: `123.32`) - A positive delta, which increments the counter's current value (e.g.: `+1`) - A negative delta, which _decrements_ the counter's current value (e.g.: `-123.11`) [block:callout] { "type": "info", "title": "Consider concurrency", "body": "Counters can be safely incremented and decremented by multiple sources at the same time. You should, however, only use the value replacement function from a single source, because multiple sources will simply overwrite each other." } [/block] # Examples Please see the [Graphite Configuration Example](doc:graphite-example) and the [Logfile Configuration Example](doc:tailing-logfiles) for examples on how to integrate Graphite with TelemetryTV.