app-metrics-plugin

App Metrics Plugin

This is a CF CLI plugin. See here for more details.

This plugin hits your app's metrics endpoint across all your app instances and displays human readable output.

Install

# To add the CF-Community plugin repo (if not already added)
cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org

# To install latest release
cf install-plugin -r CF-Community app-metrics

# To install a dev build of the plugin
./scripts/install.sh

Usage

This plugin provides two commands.

app-metrics command allows you to obtain metrics from apps instrumented with expvar.

NAME:
   app-metrics - Hits the expvar metrics endpoint across all your app instances

USAGE:
   cf app-metrics APP_NAME

OPTIONS:
   -template       path of the template files to render metrics
   -endpoint       path of the metrics endpoint
   -raw            prints raw json output

app-metrics-prometheus command allows you to obtain metrics from apps instrumented with prometheus.

NAME:
   app-metrics-prometheus - Hits the prometheus metrics endpoint across all your app instances

USAGE:
   cf app-metrics-prometheus APP_NAME

OPTIONS:
   -endpoint       path of the metrics endpoint

Uninstall

cf uninstall-plugin app-metrics

Purpose

Instrumenting applications with various metrics to provide insight into its operation is an important practice for modern day developers. I shouldn't have to explain this further.

The purpose of this plugin is to be able hit the metrics endpoint across all your application instances. There are many ways to instrument your applications including Dropwizard, Prometheus and go-metrics.

For golang applications, there is a package called Expvar available as part of the standard library which makes your metrics available via a HTTP endpoint

Problem this plugin alleviates

So if you have an app deployed on Cloudfoundry at myapp.domain.cf-app.com you can GET its metrics by hitting http://myapp.domain.cf-app.com/metrics.

However, if you scale up the application to greater than one instance, Cloudfoundry's router will load balance your requests across your app instances. This means that you will be getting metrics from a random instance every time.

This plugin will hit your metrics endpoint (defaults to /debug/metrics) across all your app instances and display the output in a human readable fashion.

Expvar

By default it hides the properties cmdline and memstats as they tend to clutter up the output.

Prometheus

Uses functionality in the prom2json to display prometheus metrics in json format.

Tests

./scripts/test.sh

Sample Outputs

# Default Template
$ cf app-metrics expvar-sample -endpoint /debug/vars

Instance: 0
Metrics:
  metric.float: 123.345
  metric.int: 10
  metric.map: map[metric1:10 metric2:11]
  metric.string: expvarApp

Instance: 1
Metrics:
  metric.float: 123.345
  metric.int: 10
  metric.map: map[metric1:10 metric2:11]
  metric.string: expvarApp

# Raw output
$ cf app-metrics expvar-sample -endpoint /debug/vars -raw | jq .
[
  {
    "Instance": 0,
    "Error": "",
    "Metrics": {
      "metric.float": 123.345,
      "metric.int": 10,
      "metric.map": {
        "metric1": 10,
        "metric2": 11
      },
      "metric.string": "expvarApp"
    }
  }
]

Future Work

See the project for what is in the To Do list.

Releasing

In order to create a new release, follow these steps

1. Create local tag and binaries

./scripts/build-all.sh release VERSION_NUMBER #(e.g. 0.7.0)

1. Copy the output of the previous command from the first line (should be '- name: AppsMetrics Plugin' to the last checksum line (should be something like checksum: fde5fd52c40ea4c34330426c09c143a76a77a8db)
2. Push the tag git push --follow-tags
3. On github, create new release based on new tag here
4. Upload the three binaries from the ./bin folders to the release (Linux, OSX and Win64)
5. Fork this repo and clone it locally
6. Edit the repo-index.yml to override the existing section about the plugin with the text previously copied in Step 2
7. Run go run sort/main.go repo-index.yml in the cli-plugin-repo to alphabetize the properties
8. Run BINARY_VALIDATION=true go test
9. Push the change to your fork
10. Create a PR against the original repo