Using Metric Registrar

You can install the Metric Registrar CLI plug-in and emit custom app metrics to Metric Registrar by registering your app as a metric source.

For information about how Metric Registrar approaches custom App Metrics and how to configure Metric Registrar, see Metric Registrar and custom App Metrics.

Registering your app as a metric source lets you see custom metrics in App Metrics and configure autoscaling rules with App Autoscaler.

For more information, see App Metrics and Scaling an app using App Autoscaler.

Installing the plug-in

To install the Metric Registrar CLI plugin:

Run:

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

Register Your App

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

Register a metrics endpoint: Register a metrics endpoint for custom metrics to be parsed and emitted to Loggregator. For more information, see Register a Metrics Endpoint.
Register a structured log format: Register a structured log format that can be emitted to Loggregator. For more information, see Register a Structured Log Format.

If you are migrating from and manually sending data to Metrics Forwarder, VMware, register a structured log format. For more information, see Register a structured log format.

Register a 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? in the Prometheus documentation.

For examples of apps that use Prometheus to publish metrics to an endpoint, see metric-registrar-examples in GitHub.

Important These endpoints are public by default. If you do not want to expose public metrics endpoints for your app, see Register a Structured Log Format below.

Prerequisites

Before registering a metrics endpoint, you must:

For all Spring apps, update the application.yml file to include one or more Prometheus endpoints. For example:
```
management:
  endpoints:
    web:
      exposure:
        include: "prometheus"
```
For all Spring apps, update the security configuration file to permit access to the Prometheus endpoints. For an example, see metric-registrar-examples in GitHub.
For all other apps, see Client libraries in the Prometheus documentation.

Register a public metrics endpoint

To register a public metrics endpoint for an app:

Log in to the cf CLI.
For each Prometheus endpoint in your app, register the endpoint as a metric source by running:
```
cf register-metrics-endpoint APP-NAME PATH-OR-URL --insecure
```
Where:
- APP-NAME is the name of the app.
- PATH-OR-URL is the path to the Prometheus endpoint, or a URL without the scheme.
For example, if the app name is example and the metrics endpoint is at https://example.com/metrics, the command would be:
```
cf register-metrics-endpoint example /metrics --insecure
```
Or, if pulling metrics by specifying an alternative route also mapped to the same app:
```
cf register-metrics-endpoint example otherexample.com/metrics --insecure
```
Important When you specify a URL to a metrics endpoint, the scheme must be omitted and the URL must use HTTPS. When you specify a path to a metrics endpoint, the path must start with a slash (`/`) character. Each metrics endpoint registered with Metric Registrar creates a service instance. If the generated service name is longer than 50 characters, it's encoded with a hash. In Metric Registrar v1.3.1 and later, you must use the `--insecure` flag for the same values that you provided in previous versions.

Verifying a metrics endpoint

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

To install and use the Log Cache cf CLI plugin:

To install Log Cache, run:

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

To view metrics for an app, run:
```
cf tail --envelope-class=metrics APP-NAME
```
Where APP-NAME is the name of your app.

For example, if you provided a custom metric called users_per_cpu as a gauge, you should see the following output:
```
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
```
Where the first line is default container metrics and the second line is custom app metrics users_per_cpu.

Important Metric Registrar produces the following benign error message at every polling interval: [LGR/] ERR Invalid syslog drain URL: parse failure

Registering a private metrics endpoint

To register a private metrics endpoint:

Set up a Prometheus endpoint that serves on any port other than 8080.
Register the endpoint by running:
```
cf register-metrics-endpoint APP-NAME PATH --internal-port PORT
```
Where:
- APP-NAME is the name of the app.
- PATH is the path to the Prometheus endpoint.
- PORT is the port where the Prometheus endpoint is served.

Register a structured log format

The Metric Registrar supports metrics emitted in JSON or DogStatsD formats. For more information about these formats, see JSON and DogStatsD below.

To register your app as a metric source:

Log in to the cf CLI.
Run:
```
cf register-log-format APP-NAME FORMAT
```
Where:
- APP-NAME is the name of your app.
- FORMAT is either `json` or `DogStatsD`.
In your app, log a structured json or DogStatsD message to represent the custom metric.

Supported JSON format

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

Type	Format
Events	{ "type": "event", "title": "title", "body": "body", "tags": { "tag1": "tag value" } }
Gauges	{ "type": "gauge", "name": "some-counter", "value": , "tags": { "tag1": "tag value" } }
Counters	{ "type": "counter", "name": "some-counter", "delta": , "tags": { "tag1": "tag value" } }

Type

Format

Events

{
   "type": "event",
   "title": "title",
   "body": "body",
   "tags": {
     "tag1": "tag value"
   }
}

Gauges

{
   "type": "gauge",
   "name": "some-counter",
   "value": 
     
      ,
   "tags": {
     "tag1": "tag value"
   }
}

Counters

{
   "type": "counter",
   "name": "some-counter",
   "delta": 
     
      ,
   "tags": {
     "tag1": "tag value"
   }
}

DogStatsD Log Format

The following table shows the supported DogStatsD format for event, gauge, and counter log types. It also lists the supported fields. For more information about DogStatsD, see DogStatsD in the Datadog documentation.

Type	Format	Supported Fields
Events	_e{title.length,text.length}:title\|text\|d:timestamp\| h:hostname\|p:priority\|t:alert_type\|#tag1,tag2	`title` `text`
Gauges	gauge.name:value\|g\|@sample_rate\|#tag1:value,tag2	`gauge.name` `value`
Counters	counter.name:value\|c\|@sample_rate\|#tag1:value,tag2	`counter.name` `value`

Register using syslog drain User Provided Service

Metric Registrar uses the syslog drain User Provided Service.

To create a Metric Registrar Service:

Create the service by running:
```
cf create-user-provided-service SERVICE-NAME -l BINDING
```
Where:
- SERVICE-NAME is the name you choose for the service.
- BINDING is the service binding. The binding can use the following schemes:
  - secure-endpoint://
  - metrics-endpoint://
  - structured-format://
Bind the provided service by running:
```
cf bind-service APP-NAME SERVICE-NAME
```
Where:
- APP-NAME is the name of the app.
- SERVICE-NAME is the service name you chose in the previous step.

The Metric Registrar supports metrics emitted in JSON or DogStatsD formats. For metrics endpoints, the rest of the URI specifies the host, port, and path of the metrics endpoint.

For example:

secure-endpoint://:8081/metrics
metrics-endpoint:///metrics
structured-format://json

For a secure endpoint, you must expose the additional port you are serving on using Diego.

For example:

cf curl /v2/apps/APP-GUID -X PUT -d '{"ports": [PORT1, PORT2, PORT3...]}'

Where:

APP-GUID is the GUID of your app.
PORT1, PORT2, PORT3... is a comma separated list of the ports on which you want your app to receive traffic.