Package io.opentelemetry.instrumentation.api.instrumenter

Class Instrumenter<REQUEST,RESPONSE>

java.lang.Object

io.opentelemetry.instrumentation.api.instrumenter.Instrumenter<REQUEST,RESPONSE>

public class Instrumenter<REQUEST,RESPONSE>
extends Object

The Instrumenter encapsulates the entire logic for gathering telemetry, from collecting the data, to starting and ending spans, to recording values using metrics instruments.

An Instrumenter is called at the start and the end of a request/response lifecycle. When instrumenting a library, there will generally be four steps.

• Create an Instrumenter using InstrumenterBuilder. Use the builder to configure any library-specific customizations, and also expose useful knobs to your user.
• Call shouldStart(Context, Object) and do not proceed if it returns false.
• Call start(Context, Object) at the beginning of a request.
• Call end(Context, Object, Object, Throwable) at the end of a request.

For more detailed information about using the Instrumenter see the Using the Instrumenter API page.

Method Summary

Modifier and Type	Method	Description
static <REQUEST, RESPONSE> InstrumenterBuilder<REQUEST,RESPONSE>	builder(io.opentelemetry.api.OpenTelemetry openTelemetry, String instrumentationName, SpanNameExtractor<? super REQUEST> spanNameExtractor)	Returns a new InstrumenterBuilder.
void	end(io.opentelemetry.context.Context context, REQUEST request, RESPONSE response, Throwable error)	Ends an instrumented operation.
boolean	shouldStart(io.opentelemetry.context.Context parentContext, REQUEST request)	Determines whether the operation should be instrumented for telemetry or not.
io.opentelemetry.context.Context	start(io.opentelemetry.context.Context parentContext, REQUEST request)	Starts a new instrumented operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

builder

public static <REQUEST,
RESPONSE>
InstrumenterBuilder<REQUEST,RESPONSE> builder(io.opentelemetry.api.OpenTelemetry openTelemetry,
 String instrumentationName,
 SpanNameExtractor<? super REQUEST> spanNameExtractor)

Returns a new InstrumenterBuilder.

The instrumentationName indicates the instrumentation library name, not the instrumented library name. The value passed in this parameter should uniquely identify the instrumentation library so that during troubleshooting it's possible to determine where the telemetry came from.

In OpenTelemetry instrumentations we use a convention to encode the minimum supported version of the instrumented library into the instrumentation name, for example io.opentelemetry.apache-httpclient-4.0. This way, if there are different instrumentations for different library versions it's easy to find out which instrumentations produced the telemetry data.

shouldStart

public boolean shouldStart(io.opentelemetry.context.Context parentContext,
 REQUEST request)

Determines whether the operation should be instrumented for telemetry or not. If the return value is true, call start(Context, Object) and end(Context, Object, Object, Throwable) around the instrumented operation; if the return value is false false execute the operation directly without calling those methods.

The parentContext is the parent of the resulting instrumented operation and should usually be Context.current(). The request is the request object of this operation.

start

public io.opentelemetry.context.Context start(io.opentelemetry.context.Context parentContext,
 REQUEST request)

Starts a new instrumented operation. The returned Context should be propagated along with the operation and passed to the end(Context, Object, Object, Throwable) method when it is finished.

The parentContext is the parent of the resulting instrumented operation and should usually be Context.current(). The request is the request object of this operation.

end

public void end(io.opentelemetry.context.Context context,
 REQUEST request,
 @Nullable
 RESPONSE response,
 @Nullable
 Throwable error)

Ends an instrumented operation. It is of extreme importance for this method to be always called after start(). Calling start() without later end() will result in inaccurate or wrong telemetry and context leaks.

The context must be the same value that was returned from start(Context, Object). The request parameter is the request object of the operation, response is the response object of the operation, and error is an exception that was thrown by the operation or null if no error occurred.