StatsD Metrics

The metrics observer emits StatsD-compatible time-series metrics about the performance of your application. These metrics are useful to get a cross-sectional view of how your application is performing in a broad sense.

Configuration

Make sure your service calls configure_observers() during application startup and then add the following to your configuration file to enable and configure the StatsD metrics observer.

[app:main]

...


# required: the prefix added to all metrics emitted.
# if present, the observer is enabled.
metrics.namespace = myservice

# optional: an endpoint to send the metrics datagrams to.
# if not specified, metrics will only be emitted to debug logs.
metrics.endpoint = statsd.local:8125

# optional: the percent of statsd metrics to sample
# if not specified, it will default to 100% (all metrics sent)
# config must be passed to the `Baseplate` constructor to use this option
metrics_observer.sample_rate = 100%

...

Outputs

For each span in the application, the metrics observer emits a Timer tracking how long the span took and increments a Counter for success or failure of the span (failure being an unexpected exception).

For the ServerSpan representing the request the server is handling, the timer has a name like {namespace}.server.{route_or_method_name} and the counter looks like {namespace}.server.{route_or_method_name}.{success,failure}. If the request timed out an additional counter will be emitted with path {namespace}.server.{route_or_method_name}.timed_out.

For each span representing a call to a remote service or database, the timer has a name like {namespace}.clients.{context_name}.{method} and the counter {namespace}.clients.{context_name}.{method}.{success,failure} where context_name is the name of the client in the context configuration.

Calls to incr_tag() will increment a counter like {namespace}.{tag_name} by the amount specified.

When using baseplate-serve, various process-level runtime metrics will also be emitted. These are not tied to individual requests but instead give insight into how the whole application is functioning. See Process-level metrics for more information.

Direct Use

When enabled, the metrics observer also adds a Client object as an attribute named metrics to the RequestContext:

def my_handler(request):
    request.metrics.counter("foo").increment()

To keep your application more generic, it’s better to use local spans for custom local timers and incr_tag() for custom counters.