Hosted Graphite Docs
Get StartedBook a Demo
  • Welcome to Hosted Graphite
  • Getting Started
  • HG-CLI
  • Sending Metrics
    • Supported Protocols
    • Graphite Tag Support
    • Metric Management
    • Metric APIs
  • Language Guide
    • Metric Libraries
    • .NET
    • Go
    • Java
    • Javascript
    • Node.js
    • PHP
    • Postman
    • Python 2.x
    • Python 3.x
    • Python Pickle
    • Ruby
    • Shell
    • TypeScript
  • Dashboard and Graphs
    • Primary Dashboards
    • Dashboard Library
    • Local Dashboard Integration
    • Worldmap Panel
    • Graphite Dashboard Guide
    • Graphite Graph Menu Reference
    • Other Dashboard Options
  • Alerting Guide
    • Alerting Overview
    • Alerts API
    • Notification Channels API
    • Scheduled Mutes API
    • Using Your Own Alerting
  • Agents Guide
    • The Hosted Graphite Agent
      • Base Metrics
      • System Layout
    • Telegraf
    • K8 Telegraf Daemon
    • OpenTelemetry
    • collectd Agent
    • StatsD Agent
    • Diamond
  • Add-Ons and Integrations Guide
    • AWS CloudWatch
    • Azure Monitor Metrics
    • GCP Metrics
    • Carbon-C-Relay
    • Circle CI
    • Cloudbees
    • Collectd Add Ons
    • GitHub
    • GitLab
    • Heroku
    • Hosted StatsD
    • New Relic
    • Papertrail
    • Pingdom
    • Sentry
    • Sitespeed
    • StatsD Add-on
    • Statuspage
  • Account Management
    • Access Keys
    • Account Diagnostics
    • Account Settings
    • Team Access: Limited Access Groups
    • SAML Authentication
    • Team Access
  • Additional Features
    • Aggregation Rules
    • Data Views
  • API Guides
    • Metrics API
    • Tag API
    • Graphite Render API
    • Render Variables API
    • Dashboard API
    • Annotations and Events API
    • Aggregation Rules API
    • Alerts APIs
  • FAQ
    • General
    • Business
    • Technical
    • Account Metrics and Limiting
    • Customization
    • Troubleshooting
    • Support
    • Changelog
Powered by GitBook
On this page
  • Installation
  • How it Works
  • Dashboards
  • Base system metrics
  • Configuration
  • Troubleshooting
  • Source Code
  • Uninstall
  • References

Was this helpful?

  1. Agents Guide

The Hosted Graphite Agent

Our agent is a simple way to get your metrics into Hosted Graphite. You install it on your machines, and it collects and forwards the system’s metrics for you.

PreviousAgents GuideNextBase Metrics

Last updated 6 months ago

Was this helpful?

If you have any questions about the agent, .

Contents

Get started 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

We support the following stable OS releases on 64-bit machines:

  • CentOS 7 forward (covering the RedHat family);

  • Debian buster forward;

  • Ubuntu 16.04 forward (LTS).

This should cover most installs on RHEL, CentOS, Amazon Linux, and Debian/Ubuntu family platforms.

  • 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 the 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.

The colored circle representing the State can take 3 values:

  • Green: The agent is reporting normally at the correct time.

  • Yellow: Agent has not reported in over 20 minutes, or is reporting with the wrong time.

  • Red: The 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.

Agent configuration is minimal and done via /etc/opt/hg-agent/hg-agent.conf. This is used to generate a more complete configuration for diamond in /var/opt/hg-agent/diamond.conf.

Typically hg-agent.conf contains only an api_key:

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:

custom_prefix: hg_agent.prodenv

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

https_proxy: http://10.10.1.10:1080
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
mongodb:
    enabled: True
    host: localhost
    port: 27017

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

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:

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 remove hg-agent

If you would like to set up installation and configuration via Puppet, Chef, or a similar configuration management system, see our .

Once your agent is sending metrics, you will find it in your , along with a link to an auto-generated dashboard named Hosted Graphite Agent.

The Hosted Graphite agent is an easy-to-use bundle of the popular metrics collector and the process manager along with an embedded build of Python and some support scripts.

For more details on how the agent works on your machines, see . The agent’s default metrics are listed and explained in .

The provides an overview of all agents associated with your account. From here, you can view the status of each agent and other information.

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, .

This dashboard can be located and uploaded from our . It displays many of the metrics reported by the Hosted Graphite agent but can be customized further.

You can find descriptions of how to read the base system metrics dashboard at .

You can find the right value for this on your , but it should be filled in automatically by the simple installation process above.

though keep in mind that the neat dashboard will no longer work for you.

You can also specify different methods of picking up the hostname, per hostname_method in . By default the agent uses smart, but e.g. if you’d prefer the FQDN with . replaced by _:

If you would like the receiver to listen on something other than the default ports (defaults shown):

If you want the agent to monitor on a host:

You can specify any of the keys from here.

You can check whether your hg-agent is reporting metadata to Hosted Graphite via the , and from there you can use the dashboard to see if metric data is flowing in. If not, you may need to dig a little deeper.

Process structure and other details are described in .

and are licensed under an .

Versions of Supervisor & Diamond included can be found in the .

repository install instructions
Diamond
Supervisor
Agent list
Dashboard Library
Hosted Graphite account page
Diamond’s config
Carbon
MongoDB
Diamond’s MongoDB config
System Layout
https://github.com/hostedgraphite/hg-agent
https://github.com/hostedgraphite/hg-agent-periodic
https://github.com/hostedgraphite/hg-agent-forwarder
MIT license
agent build scripts
Base Metrics
System Layout
get in touch
The Hosted Graphite Agent
Installation
Platforms
How it Works
Features
Dashboards
Agent list
Base system metrics
Configuration
Optional Configuration
Metric path prefix
Proxies
Local Metric Receiver / Forwarder
Dedicated environments
MongoDB
Troubleshooting
Source Code
Uninstall
References
Installation
Agent list
Base Metrics
Platforms
How it Works
Features
System Layout
Base Metrics
Dashboards
Agent list
use your package manager
Base system metrics
Base Metrics
Configuration
Optional Configuration
Metric path prefix
Base Metrics
Proxies
Local Metric Receiver / Forwarder
Dedicated environments
MongoDB
Troubleshooting
Agent list
Base Metrics
Source Code
Uninstall
References
Base system metrics dashboard