io.opentracing.Tracer Maven / Gradle / Ivy
/*
* Copyright 2016-2017 The OpenTracing Authors
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package io.opentracing;
import io.opentracing.propagation.Format;
/**
* Tracer is a simple, thin interface for Span creation and propagation across arbitrary transports.
*/
public interface Tracer extends ActiveSpanSource {
/**
* Return a new SpanBuilder for a Span with the given `operationName`.
*
* You can override the operationName later via {@link Span#setOperationName(String)}.
*
*
A contrived example:
*
* Tracer tracer = ...
*
* // Note: if there is a `tracer.activeSpan()`, it will be used as the target of an implicit CHILD_OF
* // Reference for "workSpan" when `startActive()` is invoked.
* try (ActiveSpan workSpan = tracer.buildSpan("DoWork").startActive()) {
* workSpan.setTag("...", "...");
* // etc, etc
* }
*
* // It's also possible to create Spans manually, bypassing the ActiveSpanSource activation.
* Span http = tracer.buildSpan("HandleHTTPRequest")
* .asChildOf(rpcSpanContext) // an explicit parent
* .withTag("user_agent", req.UserAgent)
* .withTag("lucky_number", 42)
* .startManual();
*
*/
SpanBuilder buildSpan(String operationName);
/**
* Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.
*
* Example:
*
* Tracer tracer = ...
* Span clientSpan = ...
* TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
* tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
*
*
* @param the carrier type, which also parametrizes the Format.
* @param spanContext the SpanContext instance to inject into the carrier
* @param format the Format of the carrier
* @param carrier the carrier for the SpanContext state. All Tracer.inject() implementations must support
* io.opentracing.propagation.TextMap and java.nio.ByteBuffer.
*
* @see io.opentracing.propagation.Format
* @see io.opentracing.propagation.Format.Builtin
*/
void inject(SpanContext spanContext, Format format, C carrier);
/**
* Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.
*
* Example:
*
* Tracer tracer = ...
* TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
* SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
* ... = tracer.buildSpan('...').asChildOf(spanCtx).startActive();
*
*
* If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an
* IllegalArgumentException.
*
* @param the carrier type, which also parametrizes the Format.
* @param format the Format of the carrier
* @param carrier the carrier for the SpanContext state. All Tracer.extract() implementations must support
* io.opentracing.propagation.TextMap and java.nio.ByteBuffer.
*
* @return the SpanContext instance holding context to create a Span.
*
* @see io.opentracing.propagation.Format
* @see io.opentracing.propagation.Format.Builtin
*/
SpanContext extract(Format format, C carrier);
interface SpanBuilder {
/**
* A shorthand for addReference(References.CHILD_OF, parent).
*
*
* If parent==null, this is a noop.
*/
SpanBuilder asChildOf(SpanContext parent);
/**
* A shorthand for addReference(References.CHILD_OF, parent.context()).
*
*
* If parent==null, this is a noop.
*/
SpanBuilder asChildOf(BaseSpan parent);
/**
* Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times
* to represent multiple such References.
*
*
* If
*
* - the {@link Tracer}'s {@link ActiveSpanSource#activeSpan()} is not null, and
*
- no explicit references are added via {@link SpanBuilder#addReference}, and
*
- {@link SpanBuilder#ignoreActiveSpan()} is not invoked,
*
* ... then an inferred {@link References#CHILD_OF} reference is created to the
* {@link ActiveSpanSource#activeSpan()} {@link SpanContext} when either {@link SpanBuilder#startActive()} or
* {@link SpanBuilder#startManual} is invoked.
*
* @param referenceType the reference type, typically one of the constants defined in References
* @param referencedContext the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the
* referencedContext is the parent. If referencedContext==null, the call to
* {@link #addReference} is a noop.
*
* @see io.opentracing.References
*/
SpanBuilder addReference(String referenceType, SpanContext referencedContext);
/**
* Do not create an implicit {@link References#CHILD_OF} reference to the {@link ActiveSpanSource#activeSpan}).
*/
SpanBuilder ignoreActiveSpan();
/** Same as {@link Span#setTag(String, String)}, but for the span being built. */
SpanBuilder withTag(String key, String value);
/** Same as {@link Span#setTag(String, boolean)}, but for the span being built. */
SpanBuilder withTag(String key, boolean value);
/** Same as {@link Span#setTag(String, Number)}, but for the span being built. */
SpanBuilder withTag(String key, Number value);
/** Specify a timestamp of when the Span was started, represented in microseconds since epoch. */
SpanBuilder withStartTimestamp(long microseconds);
/**
* Returns a newly started and activated {@link ActiveSpan}.
*
*
* The returned {@link ActiveSpan} supports try-with-resources. For example:
*
* try (ActiveSpan span = tracer.buildSpan("...").startActive()) {
* // (Do work)
* span.setTag( ... ); // etc, etc
* } // Span finishes automatically unless deferred via {@link ActiveSpan#capture}
*
*
*
* If
*
* - the {@link Tracer}'s {@link ActiveSpanSource#activeSpan()} is not null, and
*
- no explicit references are added via {@link SpanBuilder#addReference}, and
*
- {@link SpanBuilder#ignoreActiveSpan()} is not invoked,
*
* ... then an inferred {@link References#CHILD_OF} reference is created to the
* {@link ActiveSpanSource#activeSpan()}'s {@link SpanContext} when either
* {@link SpanBuilder#startManual()} or {@link SpanBuilder#startActive} is invoked.
*
*
* Note: {@link SpanBuilder#startActive()} is a shorthand for
* {@code tracer.makeActive(spanBuilder.startManual())}.
*
* @return an {@link ActiveSpan}, already registered via the {@link ActiveSpanSource}
*
* @see ActiveSpanSource
* @see ActiveSpan
*/
ActiveSpan startActive();
/**
* Like {@link #startActive()}, but the returned {@link Span} has not been registered via the
* {@link ActiveSpanSource}.
*
* @see SpanBuilder#startActive()
* @return the newly-started Span instance, which has *not* been automatically registered
* via the {@link ActiveSpanSource}
*/
Span startManual();
/**
* @deprecated use {@link #startManual} or {@link #startActive} instead.
*/
@Deprecated
Span start();
}
}