Formatters

When using the Coda Hale reporters it is important to know that the key inserted into the Coda Hale registry is also the one that will be used when using a reporter. To allow for users to configure the way data is reported we have created the concept of formatters.

Provided formatters

There is currently one provided formatter, the default formatter.

Default formatter

The default formatter creates a simple metric key format of category.identifier.metric.

• The category is one of: metrics or events.
• The identifier contains information about the instrumented entity. For actors this includes the system name, dispatcher name, and actor class, path, or group.
• The metric name identifies the metric being measured. For actors this could be mailbox-time, processing-time, or similar.

The metric key can be formatted by providing instructions in the configuration. The config below will delimit the parts with ".", and it will encode each part by replacing "." with "_" and "@" with "$". The replacements are applied in the same order as they are defined in the configuration.

copydelimiter = "."
encode = [
  {
    from = "."
    to = "_"
  },
  {
    from = "@"
    to = "$"
  }
]

The default formatter has the following default settings, and is enabled automatically:

copycinnamon.chmetrics {
  default-formatter {
    # Fully qualified class name for the formatter
    formatter-class = "com.lightbend.cinnamon.chmetrics.reporter.formatter.DefaultFormatter"

    # Delimiter string for the default formatter
    delimiter = "."

    # Encoding replacements for the default formatter
    encode = [
      {
        from = "."
        to = "_"
      },
      {
        from = "@"
        to = "_"
      },
      {
        from = ":"
        to = "_"
      },
      {
        from = "/"
        to = "_"
      }
    ]
  }
}

Formatter API

It is also possible to define your own formatter to create a specific format for how data is reported. To enable this we provide an interface that you must implement:

copypublic interface Formatter {
  /**
   * Encode a single name element within a full identifier. This allows delimiters in the name, or
   * special characters, to be encoded differently. Such as replacing '.' with '_'.
   *
   * @param name single name element within full identifier
   * @return encoded name to be included in full identifier
   */
  String encode(String name);

  /**
   * Join names into a single delimited identifier.
   *
   * @param names the parts of the full identifier to join together
   * @return a single delimited identifier
   */
  String join(List<String> names);
}

Custom formatter example

Let’s pretend that you would like to add “apple” to your keys because you like apples a lot. To do so, all you have to do is to implement the encode and join methods in whichever way you like:

copypackage sample.reporter;

import com.lightbend.cinnamon.chmetrics.reporter.Formatter;
import com.typesafe.config.Config;
import java.util.List;
import static java.util.stream.Collectors.joining;

public class AppleFormatter implements Formatter {

  public AppleFormatter(Config config) {
    // access to the config for the formatter here
  }

  @Override
  public String encode(String name) {
    return "apple_" + name;
  }

  @Override
  public String join(List<String> names) {
    return names.stream().collect(joining("."));
  }
}

To use this formatter all you have to do is to point to it in the configuration file:

copycinnamon.chmetrics.formatter = "apple-formatter"

apple-formatter {
  formatter-class = "sample.reporter.AppleFormatter"
}

Once setup any data will be reported in the following format:

copy"apple_category.apple_identifier.apple_metric"