using.html.md.erb

---
title: Registering Custom App Metrics
owner: Metric Registrar
---
This topic describes how to install the Metric Registrar CLI plugin and emit custom app
metrics to the Metric Registrar by registering your app as a metric source.

Registering your app as a metric source allows you to see your custom metrics in PCF
Metrics and configure autoscaling rules with PCF
Autoscaler. For more information about these products, see the [PCF Metrics](https://docs.pivotal.io/pcf-metrics) and [PCF Autoscaler](../appsman-services/autoscaler/using-autoscaler.html) documentation. 

## <a id="install-plugin"></a> Install the Plugin

Install the Metric Registrar CLI plugin by running the following command:

```
cf install-plugin -r CF-Community "metric-registrar"
```

## <a id="register"></a> Register Your App

To register your app as a metric source, do one of the following:

* Register a public endpoint for custom metrics to be parsed and emitted to the Loggregator. 
* Register a structured log format that can be emitted to Loggregator.

### <a id="register-endpoint"></a> Register a Public Metrics Endpoint

The Metric Registrar supports custom metrics created with the open-source tool Prometheus. Prometheus uses a response format common in many open-source libraries. It also provides several out-of-the-box metrics. For more information about Prometheus, see [prometheus.io](https://prometheus.io/). 

For examples of apps that use Prometheus to publish metrics to an endpoint, see the [metric-registrar-examples](https://github.com/pivotal-cf/metric-registrar-examples) repository.

<p class="note"><strong>Note</strong>: These endpoints must be public for the Metric Registrar to retrieve the data. If you do not want to expose public endpoints for your app, see <a href="#register-log-format">Register a Structured Log Format</a> below.</p>

For each Prometheus endpoint in your app, run the following command to register the endpoint as a metric source:

```
 cf register-metrics-endpoint APP-NAME PATH
```  

### <a id="register-log-format"></a> Register a Structured Log Format

The Metric Registrar supports metrics emitted in JSON or DogStatsD formats. For more information about these formats, see the [JSON](#json) and [DogStatsD](#dogstatsd) sections below. 

Run the following command to register your app as a metric source:

```
cf register-log-format APPNAME FORMAT
```
Where `FORMAT` is either `json` or `DogStatsD`. 

#### <a id="json"></a> JSON

The table below shows the supported JSON format for event, gauge, and counter log types. 

<table>
<tr>
	<th>Type</th>
	<th>Format</th>
</tr>
<tr>
	<td>Events</td>
	<td><pre>{
  "type": "event",
  "title": "title",
  "body": "body",
  "tags": {
    "tag1": "tag value"
  }
}</pre></td>
</tr>
<tr>
	<td>Gauges</td>
	<td><pre>{
  "type": "gauge",
  "name": "some-counter",
  "value": <float>,
  "tags": {
    "tag1": "tag value"
  }
}</pre></td>
</tr>
<tr>
	<td>Counters</td>
	<td><pre>{
  "type": "counter",
  "name": "some-counter",
  "delta": <uint>,
  "tags": {
    "tag1": "tag value"
  }
}</pre></td>
</tr>

</table>

#### <a id="dogstatsd"></a> DogStatsD

The table below shows the supported DogStatsD format for event, gauge, and counter log types. It also lists the supported fields. For more information about DogStatsD, see the [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/) topic in the Datadog documentation. 

<table>
<tr>
	<th>Type</th>
	<th>Format</th>
	<th>Supported Fields</th>
</tr>
<tr>
	<td>Events</td>
	<td><pre>_e{title.length,text.length}:title|text|d:timestamp|</br>h:hostname|p:priority|t:alert_type|#tag1,tag2</pre>
	</td>
	<td>
		
			<code>title</code><br>
			<code>text</code>
		
	</td>
</tr>
<tr>
	<td>Gauges</td>
	<td><pre>gauge.name:value|g|@sample_rate|#tag1:value,tag2</pre></td>
	<td>
		
			<code>gauge.name</code><br>
			<code>value</code>
		
	</td>
</tr>
<tr>
	<td>Counters</td>
	<td><pre>counter.name:value|c|@sample_rate|#tag1:value,tag2</pre></td>
	<td>
		
			<code>counter.name</code><br>
			<code>value</code>
		
	</td>
</tr>

</table>