All Downloads are FREE. Search and download functionalities are using the official Maven repository.

io.opentracing.Tracer Maven / Gradle / Ivy

There is a newer version: 0.33.0
Show newest version
/*
 * Copyright 2016-2018 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 {

    /**
     * @return the current {@link ScopeManager}, which may be a noop but may not be null.
     */
    ScopeManager scopeManager();

    /**
     * @return the active {@link Span}. This is a shorthand for Tracer.scopeManager().active().span(),
     * and null will be returned if {@link Scope#active()} is null.
     */
    Span activeSpan();

    /**
     * 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.active()` Scope, its `span()` will be used as the target
     *   // of an implicit CHILD_OF Reference for "workScope.span()" when `startActive()` is invoked.
     *   try (Scope workScope = tracer.buildSpan("DoWork").startActive()) {
     *       workScope.span().setTag("...", "...");
     *       // etc, etc
     *   }
     *
     *   // It's also possible to create Spans manually, bypassing the ScopeManager activation.
     *   Span http = tracer.buildSpan("HandleHTTPRequest")
     *                     .asChildOf(rpcSpanContext)  // an explicit parent
     *                     .withTag("user_agent", req.UserAgent)
     *                     .withTag("lucky_number", 42)
     *                     .start();
     * 
*/ 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(Span 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 ScopeManager#active()} 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 ScopeManager#active()} {@link SpanContext} when either {@link SpanBuilder#startActive(boolean)} or * {@link SpanBuilder#start} 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 ScopeManager#active()}). */ 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 Scope}. * *

* The returned {@link Scope} supports try-with-resources. For example: *


         *     try (Scope scope = tracer.buildSpan("...").startActive(true)) {
         *         // (Do work)
         *         scope.span().setTag( ... );  // etc, etc
         *     }
         *     // Span does finishes automatically only when 'finishSpanOnClose' is true
         * 
* *

* If *

    *
  • the {@link Tracer}'s {@link ScopeManager#active()} 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 ScopeManager#active()}'s {@link SpanContext} when either * {@link SpanBuilder#start()} or {@link SpanBuilder#startActive} is invoked. * *

* Note: {@link SpanBuilder#startActive(boolean)} is a shorthand for * {@code tracer.scopeManager().activate(spanBuilder.start(), finishSpanOnClose)}. * * @param finishSpanOnClose whether span should automatically be finished when {@link Scope#close()} is called * @return a {@link Scope}, already registered via the {@link ScopeManager} * * @see ScopeManager * @see Scope */ Scope startActive(boolean finishSpanOnClose); /** * @deprecated use {@link #start} or {@link #startActive} instead. */ @Deprecated Span startManual(); /** * Like {@link #startActive()}, but the returned {@link Span} has not been registered via the * {@link ScopeManager}. * * @see SpanBuilder#startActive(boolean) * @return the newly-started Span instance, which has *not* been automatically registered * via the {@link ScopeManager} */ Span start(); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy