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

An instrumenter of the start and end of a request/response lifecycle. Almost all instrumentation of libraries falls into modeling start and end, generating observability signals from these such as a tracing Span, or metrics such as the duration taken, active requests, etc. 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 false.
• Call start(Context, Object) at the beginning of a request.
• Call end(Context, Object, Object, Throwable) at the end of a request.

Method Summary

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

Methods inherited from class java.lang.Object

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

Method Detail

newBuilder

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

Returns a new InstrumenterBuilder.

The instrumentationName is the name of the instrumentation library, not the name of the instrument*ed* library. The value passed in this parameter should uniquely identify the instrumentation library so that during troubleshooting it's possible to pinpoint what tracer produced problematic telemetry.

In this project we use a convention to encode the minimum supported version of the instrument*ed* 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)

Returns whether instrumentation should be applied for the Instrumenter. If true, call start(Context, Object) and end(Context, Object, Object, Throwable) around the operation being instrumented, or if false execute the operation directly without calling those methods.

start

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

Starts a new operation to be instrumented. 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. The returned Context should be propagated along with the operation and passed to end(Context, Object, Object, Throwable) when it is finished.

end

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

Ends an instrumented operation. The Context must be what was returned from start(Context, Object). request 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 none was thrown.