# Heroku **Contents**: * [Installing the Hosted Graphite Heroku Add-On](#installing-the-hosted-graphite-heroku-add-on) * [Heroku Auto-Dashboard](#heroku-auto-dashboard) * [Heroku Add-On Metrics](#heroku-add-on-metrics) * [Local Development Configuration](#local-development-configuration) * [Accessing the API Key Within Your App](#accessing-the-api-key-within-your-app) * [Custom Metrics](#custom-metrics) * [Router Path Metrics](#router-path-metrics) * [Router Aggregates](#router-aggregates) * [Path Aggregates](#path-aggregates) * [Process Aggregates](#process-aggregates) * [Host Aggregates](#host-aggregates) * [Heroku Event Annotations](#heroku-event-annotations) * [Monitoring Heroku Metrics on an Existing HG Account](#monitoring-heroku-metrics-on-an-existing-hg-account) {% embed url="" %} Heroku Video Tutorial {% endembed %} ### [Installing the Hosted Graphite Heroku Add-On](#installing-the-hosted-graphite-heroku-add-on) Hosted Graphite has a [Heroku Add-On](https://elements.heroku.com/addons/hostedgraphite)! Installing the add-on can be done through the UI of your Heroku account in the ‘Resources’ section, or by issuing the following command in your Heroku CLI: > ``` > heroku addons:create hostedgraphite -a > ``` Make sure to replace the variable **\** with the name of your application, as it appears in your Heroku account. Once the add-on is installed, a new application configuration key will be created, called `HOSTEDGRAPHITE_APIKEY`. Confirm the key by issuing this command: > ``` > heroku config:get HOSTEDGRAPHITE_APIKEY -a > ``` You can now navigate to your new account by clicking on the Hosted Graphite add-on link in the Heroku UI, and wait for the metrics to appear.

If you create a Hosted Graphite account via the Heroku Add-On, you do not need to configure any log drains. For more documentation around our Heroku Marketplace Add-On, please visit the [Hosted Graphite on Heroku](https://devcenter.heroku.com/articles/hostedgraphite) page. ### [Heroku Auto-Dashboard](#heroku-auto-dashboard) This dashboard will be automatically created when you enable the Heroku Add-On, or configure Log-Drain metrics to your [existing Hosted Graphite account](#monitoring-heroku-metrics-on-an-existing-hg-account).

Using Heroku’s [Log Drain](https://devcenter.heroku.com/articles/log-drains) and [Log-Runtime](https://devcenter.heroku.com/articles/log-runtime-metrics) metrics we retrieve and process Heroku’s syslog information for your Dynos including: * **CPU Load averages** - 1/5/15-minute averages * **Memory and Swap** - Resident memory, disk cache, swap, total memory, and cumulative totals for pages written to/read from disk. * **HTTP metrics** - The number of requests broken down by HTTP method and status codes, data transferred, and connect/service times. * **Process metrics** - Memory stats from your [One-off process](https://devcenter.heroku.com/articles/process-model) as defined in your Procfile (scheduler, release, run, worker, etc). **Troubleshooting**: If you are not receiving the web (dyno) metrics, you need to **enable log-runtime metrics** for your Heroku app. Log into your Heroku CLI and run the following commands: ``` heroku labs:enable log-runtime-metrics -a ``` ``` heroku restart -a ``` ### [Heroku Add-On Metrics](#heroku-add-on-metrics) If you use the Heroku [Postgres add-on](https://elements.heroku.com/addons/heroku-postgresql) at the **standard** or **premium** tier, these metrics will automatically be forwarded to your Hosted Graphite account. They are prefixed with: **heroku.\.heroku-postgres.\.\** and report dyno statistics for cpu load, memory, db\_size, tables, active/waiting-connections, tmp-disk-available/used, read/write operations, and more! We also have a handy Heroku Postgres dashboard that is available in our [Dashboard Library](https://docs.hostedgraphite.com/dashboard-and-graphs/dashboard-library).

If you use the Heroku [Redis add-on](https://devcenter.heroku.com/articles/heroku-redis) at **any** tier, these metrics will be automatically forwarded to your Hosted Graphite account. They are prefixed with: **heroku.\.heroku-redis.\.\** and report dyno statistics for load, memory, reads/writes, connections, and more! We also have a Heroku Redis dashboard that is available in our [Dashboard Library](https://docs.hostedgraphite.com/dashboard-and-graphs/dashboard-library).

If you use the Heroku [Kafka add-on](https://devcenter.heroku.com/articles/kafka-on-heroku) at the **Standard** tier or above, these metrics will automatically forward to your Hosted Graphite account. They are prefixed with: **heroku.\.heroku-kafka.\.\.\** and report per-node statistics for load, memory, reads/writes, operations, and more! We also have a Heroku Kafka dashboard that is available in our [Dashboard Library](https://docs.hostedgraphite.com/dashboard-and-graphs/dashboard-library).

#### [**Local Development Configuration**](#local-development-configuration) In your local development environment, it will be necessary to replicate the above configuration. Since the [Foreman tool](https://devcenter.heroku.com/articles/procfile#developing-locally-with-foreman) will look in the `.env` file for development environment variables, use the following command to copy the `HOSTEDGRAPHITE_APIKEY` from the Heroku config (Do not check the file `.env` into source control). > ``` > heroku config -s | grep HOSTEDGRAPHITE_APIKEY >> .env -a > ``` > > ``` > more .env > ``` More information on accessing your API key is detailed in the below section. #### [Accessing the API Key Within Your App](#accessing-the-api-key-within-your-app) Now that the add-on has been set up, the Hosted Graphite [*API Key*](https://docs.hostedgraphite.com/welcome-to-hosted-graphite#api-key) will be available via the environment variable **HOSTEDGRAPHITE\_APIKEY**. See the appropriate language snippet below for an example of how to access this variable in your app. **Ruby** See also: [*Sending Metrics with Ruby*](https://docs.hostedgraphite.com/language-guide/ruby) ``` apikey = ENV['HOSTEDGRAPHITE_APIKEY'] ``` **Python** See also: [*Sending Metrics with Python*](https://docs.hostedgraphite.com/language-guide/python-2.x) ``` apikey = os.environ['HOSTEDGRAPHITE_APIKEY'] ``` **Java** See also: [*Sending Metrics with Java*](https://docs.hostedgraphite.com/language-guide/java) ``` String apikey = System.getenv("HOSTEDGRAPHITE_APIKEY"); ``` **PHP** See also: [*Sending Metrics with PHP*](https://docs.hostedgraphite.com/language-guide/php) ``` $apikey = getenv('HOSTEDGRAPHITE_APIKEY'); ``` **Node.js** See also: [*Sending Metrics with Node.js*](https://docs.hostedgraphite.com/language-guide/node.js) ``` var apikey = process.env.HOSTEDGRAPHITE_APIKEY; ``` ### [Custom Metrics](#custom-metrics) You can also send custom application metrics to your Hosted Graphite account. We provide code snippets in our [language guide](https://docs.hostedgraphite.com/language-guide) that can be configured throughout the codebase of your Heroku app to send Graphite metrics through a socket connection. Custom metrics can be tailored to track anything you want in your app like logins, sign ups, or cancellations. If you migrated your Heroku app monitoring from Librato, please note that Hosted Graphite does not support custom metrics via your app's log-drains. See this helpful [video tutorial](https://www.youtube.com/watch?v=Xzr6pFwhDGM) on how to configure a custom StatsD metric to report an event from your Heroku app to your Hosted Graphite account. ### [Router Path Metrics](#router-path-metrics) If you enable the Path Metrics feature in the Heroku **Config**, we will collect and forward router statistics (connection times, request methods/statuses) **per path** in your Heroku application. This will increase the total number of metrics being stored in the Hosted Graphite backend, but will give you **increased visibility** into activity within your app, and a higher level of alerting functionality. We offer these metrics in a dot.notation.format, or an underscore\_format giving you the option to choose the metric cardinality that works best for you: **heroku.\.\.router.\.\** or **heroku.\.\.router.\.\** If left on the 'default' metric format, you will receive the standard router metrics giving you a good overview of the activity within your Heroku app. The default router metrics are what can be seen on your [Heroku Auto Dashboard](#heroku-auto-dashboard).

### [Router Aggregates](#router-aggregates) Our Heroku Router Aggregates features offer several ways to reduce metric cardinality by grouping router metrics that vary by dynamic elements such as paths, process identifiers, and hostnames. These options help simplify your router metric output while preserving the most useful statistical information. #### [Path Aggregates](#path-aggregates) If you have Path Metrics enabled, but experience a high cardinality of metrics due to unique identifiers being created in your app's URLs, our Router Aggregates feature will combine these values to reduce your metric overhead. For example, lets say your app generates endpoints with ID placeholders for a customer each time a route is accessed: "GET /api/path/\" This could create a lot of unique heroku router metrics in your account and you might be better of receiving only 1 metric with a combined value. Simply define a path with the variable in curly brackets {placeholder-id} to combine multiple metrics into one! **NOTE**: Path metrics must first be enabled in your HG account, and you can define as many Router Aggregate paths as you like.

#### [Process Aggregates](#process-aggregates) Heroku runs your app code in Dynos defined by [One-Off](https://devcenter.heroku.com/articles/process-model) and [Worker](https://devcenter.heroku.com/articles/background-jobs-queueing) process types in your Procfile (you must have [Log-Runtime Metrics](https://devcenter.heroku.com/articles/log-runtime-metrics) enabled on your Heroku app to receive process metrics). This feature rolls up multiple process instance IDs into a single metric stream, which is good for reducing cardinality and giving you a good performance overview. By default, you will receive individual process metrics, but we recommend enabling aggregation per process to significantly decrease your total metric count. **Contact us** to enable Process Aggregation for any specific Heroku process metrics not listed in our Heroku UI (advanced\_scheduler, clock, celeryworker, worker\_pipeline, beat, mail\_syncer, notifications, orchestrator, priority, etc).

#### [Host Aggregates](#host-aggregates) Some Heroku apps report router metrics under multiple hostnames, such as a mix of your Heroku default domain (myapp.herokuapp.com), a custom domain ([www.herokuapp.com](http://www.herokuapp.com)), or internal service domains (UID-123.herokuapp.com). These hostname variations will produce multiple metric series even though they represent the same application. If you don't require data for each host/subdomain of your app, enable the Host Aggregation feature to combine all individual hostname data sets into a single 'overview' series of: **heroku.router.\***

### [Heroku Event Annotations](#heroku-event-annotations) We also provide a convenient webhook that you can upload to your Heroku account and import real-time Heroku events to your Hosted Graphite account:

Just add our HG webhook into your Heroku account, you can configure [annotations](https://docs.hostedgraphite.com/api-guides/annotations-and-events-api#dashboard-annotations) on your dashboards to display events from your Heroku environment around deployments, builds, domains, collaborators, add-ons, and more. The latest version of our Heroku Auto-Dashboard has the Heroku annotation built in, and you can generate the newest version of this dashboard from our [Dashboard Library](https://docs.hostedgraphite.com/dashboard-and-graphs/dashboard-library). ### [Monitoring Heroku Metrics on an Existing HG Account](#monitoring-heroku-metrics-on-an-existing-hg-account) Its easy to forward your log drain metrics to an existing Hosted Graphite account. This is actually a better value because a dedicated HG account allows you to configure multiple heroku apps, get the full 2 year data retention, and premium level support for the same price as the Heroku add-on (depending on how many metrics your app produces).

**First**, make sure the Heroku ‘appname format’ is enabled in the Heroku Confg if you wish to include your appname in the metric naming scheme (recommended). Navigate to Add-Ons => Heroku, and confirm that the checkbox is checked. **Next**, enable [Log-Runtime metrics](https://devcenter.heroku.com/articles/log-runtime-metrics) by running the following command in your Heroku CLI: > ``` > heroku labs:enable log-runtime-metrics -a > ``` **Then**, after enabling runtime metrics, you need to restart your Heroku application: > ``` > heroku restart -a > ``` **Finally**, you can just point the Heroku app logs to your existing Hosted Graphite account by running the following command: > ``` > heroku drains:add https://webhooks.hostedgraphite.com/heroku//logs/\?apikey= -a > ``` **NOTE: t**o avoid duplicate metric sets, make sure to enable both the 'appname format' checkbox in the Add-Ons UI, **and** include the appname in the above `drains:add` command. You are able to ship metrics from as many Heroku apps as you like, and metrics will appear as events happen within your app (status.\*, method.\*, etc).