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.