Our agent is a simple way to get your metrics into Hosted Graphite. You install it on your machines, and it collects and forwards metrics for you.
If you have any questions about the agent, get in touch.
- The Hosted Graphite Agent
- How it works
- Additional & custom metrics
- Source code
The simplest way to get started is by pulling down our installer script.
For Debian-based systems, including Ubuntu:
curl -s https://YOUR-API-KEY@www.hostedgraphite.com/agent/installer/deb/ | sudo sh
or for RHEL-based systems:
curl -s https://YOUR-API-KEY@www.hostedgraphite.com/agent/installer/rpm/ | sudo sh
If you would like to set up installation and configuration via Puppet, Chef or a similar configuration management system, see our repository install instructions.
- Faster submission of metric data from your application because it doesn’t have to do a DNS lookup, or connect out across the internet.
- More reliable delivery because the agent stores-and-forwards, buffering on disk when it can’t connect.
- Easier debugging for the “my metric is missing” problem, because our UI can tell you that an agent has stopped responding.
- More secure: the agent uses HTTPS and while we offer TLS-wrapped carbon protocols, it’s more effort to use than the plaintext ones. Sending straight to the agent bypasses this and we take care of it for you.
- No need to prefix your metrics with an API key for HG’s authentication: it’s handled for you, using API key in the agent config.
- No need to specify new firewall rules for carbon protocols and keep the rules updated - if you can already get HTTPS out of your network, even via a proxy, then it’ll work.
For more details of how the agent works on your machines, see System Layout.
The Agent list provides an overview of all agents associated with your account. From here, you can view the status of each agent and other information.
The coloured circle representing the State can take 3 values:
- Green: Agent is reporting normally with the correct time.
- Yellow: Agent has not reported in over 20 minutes, or is reporting with the wrong time.
- Red: Agent has reported errors in recent log messages.
An agent’s Clock Offset is the difference between the time reported by the agent and the time recorded on our server. Incorrect time can produce anomalies in metric data so it is advised to keep the agent’s clock accurate.
You can delete the record of an agent from this page, but be aware that this will not uninstall the agent. To uninstall an agent, use your package manager.
The Hosted Graphite Agent ships with local Carbon endpoints: you can send Graphite metrics to it as usual via udp and tcp on localhost and port 2003 (by default).
As your agent is configured to use your Hosted Graphite API key, it can accept metrics locally without any API key prefixing, and will handle authentication for you.
A quick example in Python, sending a metric via UDP:
import socket sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.sendto("foo.bar 1.2\n", ("localhost", 2003))
Any of our examples found on our language guide contain API key prefixing, and they send to <something>.carbon.hostedgraphite.com, so all you need to do is send to localhost instead. The API key prefixing for your metric names is optional.
You can also drop files containing metrics into /var/opt/hg-agent/drop, e.g.
my.metric 1.2 my.other.metric 3.4
which will be picked up and forwarded by the agent. This is useful particularly if you want to collect data that requires privileged access, e.g. via a small cron job.
Agent configuration is minimal and done via /etc/opt/hg-agent/hg-agent.conf. This is used to generate more complete configuration for diamond in /var/opt/hg-agent/diamond.conf.
Typically hg-agent.conf contains only an api_key:
You can find the right value for this on your Hosted Graphite account page, but it should be filled in automatically by the simple install process above.
Note that the agent takes control of diamond configuration: if you want more nuanced control, you can run a separate diamond instance or whatever metric collection system you wish. You can still take advantage of the agent’s authentication management and local buffering/forwarding facilities by configuring it to send Graphite data to localhost.
You can supply a custom prefix instead of hg_agent, e.g. to specify a host environment:
though keep in mind that the neat Base Metrics dashboard will no longer work for you.
You can also specify different methods of picking up the hostname, per hostname_method in Diamond’s config. By default the agent uses smart, but e.g. if you’d prefer the FQDN with . replaced by _:
If your system requires a proxy to get HTTPS access to the Internet:
If you would like the receiver to listen on something other than the default Carbon ports (defaults shown):
tcp_port: 2003 udp_port: 2003
If you’d like to keep more spool data for buffering locally during network outages (defaults shown):
max_spool_count: 10 spool_rotatesize: 10000000
Large customers with dedicated Hosted Graphite environments may need to specify metric data and metadata endpoints, e.g. for a cluster tst:
endpoint_url: https://tst.hostedgraphite.com/api/v1/sink heartbeat_url: https://heartbeat-tst.hostedgraphite.com/beat
You can check whether your hg-agent is reporting metadata to Hosted Graphite via the Agent list, and from there you can use the Base Metrics dashboard to see if metric data is flowing in. If not, you may need to dig a little deeper.
Logs are in /var/log/hg-agent: you can see the metrics generated by diamond in archive.log, as well as the various daemon logs supervisord.log, diamond.log, periodic.log, and forwarder.log e.g.
$ tail -f /var/log/hg-agent/forwarder.log
Process structure and other details are described in System Layout.
You can inspect the agent as a service like any other, e.g. on Ubuntu trusty:
$ sudo service hg-agent status
If you’d like to look at things from the agent’s supervisor point of view:
$ sudo /opt/hg-agent/bin/supervisorctl --config=/etc/opt/hg-agent/supervisor.conf status
The sources used to build the agent can be followed at:
and are licensed under an MIT license.
Versions of Supervisor & Diamond included can be found in the agent build scripts.
Hosted Graphite Agents can be uninstalled using your package manager.
For Debian-based systems:
sudo apt-get remove hg-agent
For RHEL-based systems:
sudo yum erase hg-agent