using.html.md.erb

---
title: Registering and Emitting 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.

## <a id="overview"></a> Overview

Registering your app as a metric source allows you to see your custom metrics in <%= vars.product_name %>
Metrics and configure autoscaling rules with <%= vars.product_name %>
Autoscaler. 

For more information, see [<%= vars.product_name %> Metrics](https://docs.pivotal.io/app-metrics) and [<%= vars.product_name %> Autoscaler](../appsman-services/autoscaler/using-autoscaler.html).

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

To install the Metric Registrar CLI plugin, do the following:

1. Log in to the Cloud Foundry Command Line Interface (cf CLI).

1. Run 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**: Register a public endpoint for custom metrics to be parsed and emitted to Loggregator. See [Register a Public Metrics Endpoint](#register-endpoint) below.
* **Register a structured log format**: Register a structured log format that can be emitted to Loggregator. See [Register a Structured Log Format](#register-log-format).

<p class='note'><b>Note: </b> If you are migrating from and manually send data to Metrics Forwarder for <%= vars.product_name %>, Pivotal recommends registering a structured log format. See <a href="#register-log-format">Register a Structured Log Format.</p>

### <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 text-based exposition format common in many open-source libraries. It also provides several out-of-the-box metrics for different programming languages.

For more information about Prometheus, see [What is Prometheus?](https://prometheus.io/docs/introduction/overview/#what-is-prometheus) in the Prometheus documentation. 

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

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

#### <a id="prerequisites"></a> Prerequisites

Before registering a public metrics endpoint, you must do the following:

* For all Spring apps, update the `application.yml` file to include one or more Prometheus endpoints. For example:

	```
	management:
	  endpoints:
	    web:
	      exposure:
	        include: "metrics,prometheus"
	  endpoint:
	    metrics:
	      enabled: true
	    prometheus:
	      enabled: true
	```

* For all Spring apps, update the security configuration file to permit access to the Prometheus endpoints. For an example, see [metric-registrar-examples](https://github.com/pivotal-cf/metric-registrar-examples/blob/master/java-spring-security/src/main/java/io/pivotal/metric_registrar/examples/spring_security/SecurityConfig.java) in GitHub.

* For all other apps, see [client libraries] provided by the open-source community.

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

To register a public metrics endpoint for an app, do the following:

1. Log in to the cf CLI.

1. 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
	```  
	Where:
	* `APP-NAME` is the name of the app.
	* `PATH` is the path to the Prometheus endpoint.

	For example, if the app name is `example` and the metrics endpoint lives at `https://example.com/metrics` the command would be:
        
        ```
        cf register-metrics-endpoint example /metrics
        ```

#### <a id="endpoint-verify"></a> Verify a Public Metrics Endpoint

Pivotal recommends that you install the LogCache cf CLI plugin to view metrics.

To install and use the Log Cache cf CLI plugin, do the following:

1. To install Log Cache, run the following command:

    ```
    cf install-plugin -r CF-Community "log-cache"
    ```

1. To view metrics for an app, run the following command:

    ```
    cf tail --envelope-class=metrics <APP_NAME> 
    ```

    For example, if you provided a custom metric called `users_per_cpu` as a gauge, you should see the following output:
	
    <pre class="terminal">2019-06-18T10:49:28.27-0600 [app-name/1] GAUGE cpu:0.154763 percentage disk:14000128.000000 bytes disk_quota:33554432.000000 bytes memory:10190848.000000 bytes memory_quota:33554432.000000 bytes
    2019-06-18T10:49:26.42-0600 [app-name/1] GAUGE users_per_cpu:557.500000</pre>

    Where the first line is default container metrics and the second line is custom metrics `users_per_cpu`. <p class='note'><strong>Note:</strong> The Metric Registrar produces the following benign error message at every polling interval: <code>[LGR/] ERR Invalid syslog drain URL: parse failure</code></p>

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

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

1. Log in to the cf CLI.

1. Run the following command:

	```
	cf register-log-format APP-NAME FORMAT
	```

	Where:
	* `APP-NAME` is the name of the app.
	* `FORMAT` is either `json` or `DogStatsD`.

1. In your app, log a structured `json` or `DogStatsD` message to represent the custom metric.

#### <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>