Using Metric Registrar

Page last updated:

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.

For information about how the Metric Registrar processes custom app metrics and how to configure the Metric Registrar, see Metric Registrar and Custom App Metrics.

Overview

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

For more information, see the App Metrics documentation and Scaling an App Using App Autoscaler.

Install the Plugin

To install the Metric Registrar CLI plugin:

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

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

Note: If you are migrating from and manually send data to Metrics Forwarder, VMware recommends registering a structured log format. For more information, see Register a Structured Log Format below.

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.

Note: 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.

Note: Metrics endpoints must be served over HTTPS.

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:

1. Log in to the cf CLI.

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

   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
   

   Or, if pulling metrics from a different URL:

   cf register-metrics-endpoint example otherexample.com/metrics
   

   Note: When specifying a path to a metrics endpoint, the path must start with a / character.

   Note: When specifying a URL to a metrics endpoint, the scheme must be omitted and the URL must use HTTPS.

   Note: Each metrics endpoint registered with Metric Registrar creates a service instance. If the generated service name is longer than 50 characters, it is encoded with a hash.

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

1. To install Log Cache, run:

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

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

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

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:

1. Log in to the cf CLI.

2. Run:

   cf register-log-format APP-NAME FORMAT
   

   Where:

   • APP-NAME is the name of your app.
   • FORMAT is either json or DogStatsD.

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

JSON

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

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

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

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

DogStatsD Log Format

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 DogStatsD in the Datadog documentation.

_e{title.length,text.length}:title|text|d:timestamp|
h:hostname|p:priority|t:alert_type|#tag1,tag2

gauge.name:value|g|@sample_rate|#tag1:value,tag2

counter.name:value|c|@sample_rate|#tag1:value,tag2