# Getting Started ### **Contents** 1. [Understanding the Graphite Metric Format](#understanding-the-graphite-metric-format) 2. [Understanding Data Ingestion, Aggregation, and Retention](#understanding-time-series-data-ingestion-aggregation-and-retention) 3. [Sending Metrics](#sending-metrics) 1. [YOUR API KEY](#your-api-key) 4. [Use Your Data to Create Custom Dashboards](#use-your-data-to-create-custom-dashboards) 5. [Use Your Data to Create Custom Alerts](#use-your-data-to-create-custom-alerts) 1. [Configure Notification Channels](#configure-notification-channels) 6. [Integrate With Popular Services Like AWS, Azure, GCP, and Heroku](#integrate-with-popular-services-like-aws-azure-gcp-and-heroku) 7. [Sit Back and Relax](#sit-back-and-relax) ## [Understanding the Graphite Metric Format](#understanding-the-graphite-metric-format) 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](https://graphite.readthedocs.io/en/latest/feeding-carbon.html#step-1-plan-a-naming-hierarchy). * **value:** This is an integer or floating point number. Hosted Graphite can only ingest numeric values. * **timestamp** (optional): This is a [UNIX](https://en.wikipedia.org/wiki/Unix_time) 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](https://netcat.sourceforge.net/) 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 ](https://docs.hostedgraphite.com/account-management/account-diagnostics#invalid-metrics-graph)graph in the Account Diagnostics UI. ### [Understanding Data Ingestion, Aggregation, and Retention](#understanding-time-series-data-ingestion-aggregation-and-retention) 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](mailto:support@metricfire.com) 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 ### [Sending Metrics](#send-metrics) 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](https://docs.hostedgraphite.com/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](https://docs.hostedgraphite.com/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](https://docs.hostedgraphite.com/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:

HG Public Endpoints

Sending Metrics

Try our CLI-Demo tool to send a sample of performance metrics from your local machine to your HG account: **bash -c "$(curl -s '')"** These metrics can be visualized in the Welcome to HG dashboard that is automatically generated when you send test metrics from the CLI Demo:

CLI-Demo Tool

#### [YOUR API KEY](#your-api-key) 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](https://docs.hostedgraphite.com/sending-metrics), including details on supported protocols and Graphite tagging. Please reach out to if you need help sending meaningful metrics to help accomplish your monitoring goals. ### [Use Your Data to Create Custom Dashboards](#use-your-data-to-create-custom-dashboards) You can locate a full list of stored metrics using our [Metrics Search UI](https://www.hostedgraphite.com/app/metrics/), or [Metrics API](https://docs.hostedgraphite.com/api-guides/metrics-api):

Metrics Search UI

You can then navigate to Dashboards => + Add New Dashboard, and use your metrics to create queries in dashboard panels:

Add New Dashboard

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](https://graphite.readthedocs.io/en/latest/functions.html) 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.

Graphite Functions Example

Additionally, you can configure some more advanced features to your dashboards such as **Variables** and **Annotations**. Read more about this in our [Dashboard Guide](https://docs.hostedgraphite.com/dashboard-and-graphs). ### [Use Your Data to Create Custom Alerts](#use-your-data-to-create-custom-dashboards) 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:

Create alert

Then you can set the **criteria** to trigger an alert anytime the numeric value of the metric reports data outside of its expected bounds:

Set alert criteria

#### [Configure Notification Channels](#configure-notification-channels) 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](https://docs.hostedgraphite.com/alerting-guide) for more details.

Add notification channel

### [Integrate With Popular Services Like AWS, Azure, GCP, and Heroku](#integrate-with-popular-services-like-aws-azure-gcp-and-heroku) It’s never been easier to pull data from services running on your cloud infrastructure! See our [Add-Ons and Integrations ](https://docs.hostedgraphite.com/add-ons-and-integrations-guide)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](https://www.hostedgraphite.com/app/dashboard-library/) that offer a great starting point for many of our integrations:

Dashboard Library

### [Sit Back and Relax](#sit-back-and-relax) 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](https://docs.hostedgraphite.com/account-management/team-access), configure [additional features](https://docs.hostedgraphite.com/additional-features), and use our [APIs](https://docs.hostedgraphite.com/api-guides) 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 or through the in-app chat feature below, happy monitoring!