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:

api_key: YOUR-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.


Optional configuration

Metric path prefix

You can supply a custom prefix instead of hg_agent, e.g. to specify a host environment:

custom_prefix: hg_agent.prodenv


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 _:

hostname_method: fqdn



If your system requires a proxy to get HTTPS access to the Internet:



Local metric receiver / forwarder

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


Dedicated environments

Large customers with dedicated Hosted Graphite environments may need to specify metric data and metadata endpoints, e.g. for a cluster tst:




If you want the agent to monitor MongoDB on a host:

    enabled: True
    host: localhost
    port: 27017


You can specify any of the keys from Diamond’s MongoDB config here.