OpenTracing Metrics

The OpenTracing Metrics project enables any OpenTracing compliant Tracer to be decorated with support for reporting span based application metrics.

The project currently has support for reporting metrics via:

• Prometheus

A Tracer is decorated in the following way:

	Tracer tracer = ...;
	MetricsReporter reporter = ...;
	Tracer metricsTracer = io.opentracing.contrib.metrics.Metrics.decorate(tracer, reporter);

Metric Labels

Labels are used as a way to separate sampled metric values into related groups. A combination of label values will uniquely define a specific metric.

If one of the metric labels returned for a particular sampling point (i.e. span) returns a null value, then the metric will not be recorded. This provided a means to selective choose which metrics values are of interest.

For example, by default if the span.kind tag is not specified, it's label value will be null. This means that metrics for internal spans will by default not be recorded. If an application/service developer wants specific internal span metrics recorded, they can add a MetricLabel that returns an appropriate value for the span.kind for the spans of interest.

Label Types

Label types:

• ConstMetricLabel

When a label will have a constant value, e.g. service name

• OperationMetricLabel

The label tags the span's operation name

• TagBaggageMetricLabel

This label attempts to obtain the value associated with the requested name from the span tags, followed by the span's baggage, and if not found uses a default value.

Default Labels

By default, the metrics are reported using the following labels:

• operation - the operation associated with the span

• span.kind - the span.kind tag associated with the span, by default if not specified, then the metrics for the span will not be recorded

• error - the error tag, by default the value will be false

TODO: Need to move these into an abstract metrics reporter so common across all impls.

Adding Metric Labels

An application may want to add specific labels to help classify the metrics being reported by each span.

For example, many Tracer implementations associate spans with a service name. This can also be achieved for the span metrics, by specifying a ConstMetricLabel when creating the reporter.

Customizing Metric Labels

When initializing the MetricsReporter, it would be possible to provide a MetricLabel for a default label, to override its value.

For example, a MetricLabel implementation could be provided for the error label, which could override the standard boolean value and potentially provide an alternative set of values based on other tags or baggage values associated with a span.

Reporting Metrics with Prometheus

Prometheus metrics reporting is provided by a specific implementation of the MetricsReporter interface.

For example,

	List<MetricLabel> labels = ...;

	MetricsReporter reporter = new PrometheusMetricsReporter(labels);

The class supports two constructors, the one shown above which accepts a custom list of metric labels (as discussed in the previous section), and a second which also enables the Prometheus CollectorRegistry instance to be provided.

The responsibility for identifying how Prometheus metrics are exposed is outside the scope of the MetricsReporter allowing the application to decide whether to expose via HTTP endpoint, use the Push Gateway, etc. For example, using the servlet with a Jetty server:

	Server server = new Server(1234);
	ServletContextHandler context = new ServletContextHandler();
	context.setContextPath("/");
	server.setHandler(context);
	context.addServlet(new ServletHolder(new MetricsServlet()), "/metrics");
	server.start();

Release

Follow instructions in RELEASE