Getting Started
An easy-to-follow outline of how to send data to a Hosted Graphite account, and then use that data towards building custom dashboards and alerts to get insight into your infrastructure.
Contents
A Graphite metric is a unique time-series collection of name:value data that can be aggregated, graphed, and alerted on. In other words, a metric is a unique namespace that you can send data or query data from.
We bill on the total number of unique metrics stored within a Hosted Graphite account.
Understanding the metric data format is important as this is how our hosted carbon endpoint can accept data. Hosted Graphite metrics must use the following format: metric.name [value] [timestamp]
metric.name: This is a period-delimited path, such as 'servers.prod.memory.free'. The periods will turn each path component into a sub-tree, like a 'folder' structure. The graphite project website has some useful metric naming advice.
value: This is an integer or floating point number. Hosted Graphite can only ingest numeric values.
timestamp (optional): This is a UNIX timestamp which is the number of seconds since Jan 1st 1970 (always UTC, never local time). If no timestamp is provided, the current time will be assumed which is generally “good enough” for most uses.
Here’s an example of a metric name and numeric value fixed with an optional UNIX timestamp:
test.app.conc_users 59 1706296444
This means that the metric will be stored as being measured at the time specified, instead of the arrival time at our server. This is useful for sending historical data or when you need the timestamps to match exactly with the timestamps on your system logs.
Here’s an example of how to send a metric via TCP using the Netcat utility:
echo "YOUR-API-KEY.test.app.conc_users 59" | nc carbon.hostedgraphite.com 2003
Since this example was not fixed with a UNIX timestamp, the test.app.conc_users metric will be time-stamped upon ingestion.
NOTE: Metric names can contain only alphanumeric and *, ., -, _, $, %, #, = characters. Any other characters will prevent your metric from being ingested, and will be reported on your Invalid Metrics graph in the Account Diagnostics UI.
Once data hits our carbon endpoint, it travels through our ingestion layers, is timestamped, and aggregated before reaching our storage backend. We aggregate and store data at these resolutions:
5-second data is stored for 1 day (please contact us to request this resolution)
30-second data is stored for 3 days
300-second (5min) data is stored for 6 months
3600-second (1hr) data is stored for 2 years
When querying data in your Dashboards, we map the following time spans to the following resolutions:
0h-1h query displays 5s resolution data (available upon request)
1h-10h query displays 30s resolution data
10h-5d query displays 300s resolution data
5d-2y query displays 3600s resolution data
The most common types of metrics sent to Hosted Graphite include server metrics (from an agent), custom metrics (from within your application code), and integration metrics (from a 3rd party service that we integrate with).
To learn more about collecting server metrics via using an agent, please refer to our Agents Guide for a list of agents that are easy to configure with Graphite. Our agents can collect performance statistics from running processes within your servers.
For information on sending custom metrics without an agent, review our Language Guide. This is a guide for configuring custom metrics into your application code using socket connections.
Find out how to send integration metrics from popular PAAS services that we integrate with, such as AWS, Azure, GCP, Heroku, and more. Our Add-Ons and Integrations Guide will help you get started!
Information about sending metrics is also outlined in a handy guide that can be located by clicking on the 'Send Metrics' button on the Hosted Graphite account homepage:
Try our CLI-Demo tool to send a sample of performance metrics from your local machine to your HG account: bash -c "$(curl -s 'https://www.hostedgraphite.com/demos/cli_system_collector/?user=current')"
These metrics can be visualized in the Welcome to HG dashboard that is automatically generated when you send test metrics from the CLI Demo:
Every Hosted Graphite account has an associated API Key. This API Key must be sent along with your metric data to associate it with your account. In most cases, this means prefixing the key to your metric names, e.g: YOUR-API-KEY.metric.name which will ensure that your data is securely sent to our public carbon endpoint.
Additionally, if you ever need to rotate your old API Key, let us know and we would be happy to create a new one for you. We can also leave both keys active while you rotate them them throughout your codebase, and retire the old key at your convenience. It is best practice to rotate your API Key every two years or so.
You can find more information about how to send metrics in our Sending Metrics Guide, including details on supported protocols and Graphite tagging. Please reach out to [email protected] if you need help sending meaningful metrics to help accomplish your monitoring goals.
You can locate a full list of stored metrics using our Metrics Search UI, or Metrics API:
You can then navigate to Dashboards => + Add New Dashboard, and use your metrics to create queries in dashboard panels:
Wildcard (*) queries are supported and are useful in grabbing all series from a specified index in the metric path. You can also apply Graphite functions to your queries to manipulate the data in many different ways. Some commonly used functions include keepLastValue(), aliasByNode(), groupByNode(), summarize(), scale(), movingAverage() - and there are many more included in Graphite's library of functions.
Additionally, you can configure some more advanced features to your dashboards such as Variables and Annotations. Read more about this in our Dashboard Guide.
In a similar way to building metric queries in your dashboard panels, you can use these metric queries to create alerts in our Graphite Alerts UI. Simply name the alert, then add a metric query and description:
Then you can set the criteria to trigger an alert anytime the numeric value of the metric reports data outside of its expected bounds:
The default notification channel will be the email associated with your account, but you can configure additional email addresses to send alerts to your preferred email account. You can also send alerts to Slack, PagerDuty, Microsoft Teams, OpsGenie, and VictorOps or create custom alerting webhooks. Read about this in our Alerting Guide for more details.
It’s never been easier to pull data from services running on your cloud infrastructure! See our Add-Ons and Integrations guide for a full list of 3rd party services that we integrate with - like Sentry, New Relic, GitHub, Papertrail, Sitespeed, and more!
We even have pre-built dashboards in our Dashboard Library that offer a great starting point for many of our integrations:
You are now well on your way to having better visibility into your infrastructure which will help you quickly identify issues, optimize your systems and resource allocation, and save your team valuable time.
You can now invite team members, configure additional features, and use our APIs to programmatically manage your monitoring environment. If you have any questions or issues, our team is standing by 24/7 to offer fast and friendly assistance.
You can contact us at [email protected] or through the in-app chat feature below, happy monitoring!
Last updated
Was this helpful?