microcosm-metrics

Opinionated metrics configuration.

Designed to support DataDog statsd-compatible servers.

Usage

1. Configure a metrics client:

   graph.use("datadog_statsd")
   

2. Use the resulting graph.metrics client:

   graph.metrics.increment("foo")
   

Tags

A tag for the environment will always be added: it will either be the value of the environment variable MICROCOSM_ENVIRONMENT or "undefined" if it is not defined or is empty. A tag for the service will always be added, which will be the microcosm object graph's name (the first argument to create_object_graph).

Further tags can be added by controlling the configuration for datadog_statsd.tags, for example by defining the environment variable <NAME>__DATADOG_STATSD__TAGS to a JSON-serialized list and using load_from_environ_as_json. In that case, note that none of the tags are allowed to end in a :.

Decorators

The two most common metrics usages are supported via decorator interfaces.

To time function calls, use:

@graph.metrics_timing("my_func")
def my_func():
    pass

To count function outcomes, use:

@graph.metrics_counting("my_func")
def my_func():
    pass

For counting, the default behavior is to count function calls. To count different outcomes, use a custom Classifier. The classifier only adds a single tag called classifier and no longer modifies the metric key.

class TruthyClassifier(Classifier):

    def label_result(self, result):
        return "truthy" if bool(result) else "falsey"

    def label_error(self, error):
        return None

Then pass the classifier class to the counting decorator:

@graph.metrics_counting("my_func", classifier=TruthyClassifier)
def my_func():
    pass

Again, the classifier no longer modifies the metric key and only adds a single tag called classifier.

StatsD Testing

First, run the statsd server. For example, using Docker:

docker run --name statsd -d \
           -p 0.0.0.0:9102:9102 \
           -p 0.0.0.0:8125:9125/udp \
           prom/statsd-exporter

Then, use the included CLIT to validate connectivity:

publish-metric --host $(docker-machine ip default)

The resulting metric should appear in the /metrics endpoint.

DataDog Testing

First, run the DataDog Agent (requires an API_KEY). For example, using Docker:

docker run -d --name datadog-agent -p 8125:8125/udp -e API_KEY=${API_KEY} datadog/docker-dd-agent:latest

Then, use the included CLI to validate connectivity:

publish-metric --host $(docker-machine ip default)

The resulting metric should appear in DataDog "Metric Summary" right away.