What are best practices to name metrics and sources?

It’s important to spend some time to model out the naming convention you pick. Ideally you should start by thinking about what problem are you trying to solve.

Librato metrics has a two dimensional name space. You define names for Metrics and Sources.

The general guidance is that metric names explain the unit or type of the measurements and source names represent where the measurements came from.

We recommend using dotted decimal notation for both metrics and sources to build a hierarchy.

Here are some examples:

This metric contains information on CPU Usage and the source indicates which machines the CPU usage information came from:

metric: cpu_usage
source: web.PRODUCTION.11
source: web.STAGING.2

This metric contains information about how many times an application was launched and the source indicates information about where the app was launched.

metric: app_name.version_3.launch
source: android_4.2
source: OSversion_6.x

This metric contains temperature data and the source indicates where that data was collected.

metric: temperature.celsius
source: EU.Berlin.location3
source: US.NewYorkCity.location_1

Naming limitations for sources and metrics

  1. Metric and Source names must be safe to use as part of a URL. This means try to keep metric names to letters, digits, hyphen, period, and underscore (/[\.a-zA-Z0-9_-]/). Metric and Source names can be up to 255 characters in length.
  2. Metric names can not currently be used with regular expressions. If you want to be able to filter the data based on a string you should put that string into the source name.

Recommendations:

  1. Avoid extremely short metric or source names. Be as descriptive in the metric and source names as you can be.
  2. Metrics with large numbers of unique sources are difficult to visualize. Consider aggregating multiple sources into a single source or using a more generic source name.
  3. Metrics are designed to handle numeric data. Annotations are designed to handle events that occur at a point in time or span a window of time.