/* * Copyright 2016-17, OpenCensus 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.opencensus.trace; import io.opencensus.internal.Utils; import io.opencensus.trace.internal.BaseMessageEventUtils; import java.util.Collections; import java.util.EnumSet; import java.util.Map; import java.util.Set; import javax.annotation.Nullable; /** * An abstract class that represents a span. It has an associated {@link SpanContext} and a set of * {@link Options}. * *
Spans are created by the {@link SpanBuilder#startSpan} method. * *
{@code Span} must be ended by calling {@link #end()} or {@link #end(EndSpanOptions)}
*
* @since 0.5
*/
public abstract class Span {
private static final Map This function is only intended to be used by RPC systems (either client or server), not by
* higher level applications.
*
* @param networkEvent the network event to add.
* @deprecated Use {@link #addMessageEvent}.
* @since 0.5
*/
@Deprecated
public void addNetworkEvent(NetworkEvent networkEvent) {
addMessageEvent(BaseMessageEventUtils.asMessageEvent(networkEvent));
}
/**
* Adds a MessageEvent to the {@code Span}.
*
* This function can be used by higher level applications to record messaging event.
*
* This method should always be overridden by users whose API versions are larger or equal to
* {@code 0.12}.
*
* @param messageEvent the message to add.
* @since 0.12
*/
public void addMessageEvent(MessageEvent messageEvent) {
// Default implementation by invoking addNetworkEvent() so that any existing derived classes,
// including implementation and the mocked ones, do not need to override this method explicitly.
Utils.checkNotNull(messageEvent, "messageEvent");
addNetworkEvent(BaseMessageEventUtils.asNetworkEvent(messageEvent));
}
/**
* Adds a {@link Link} to the {@code Span}.
*
* Used (for example) in batching operations, where a single batch handler processes multiple
* requests from different traces.
*
* @param link the link to add.
* @since 0.5
*/
public abstract void addLink(Link link);
/**
* Sets the {@link Status} to the {@code Span}.
*
* If used, this will override the default {@code Span} status. Default is {@link Status#OK}.
*
* Only the value of the last call will be recorded, and implementations are free to ignore
* previous calls. If the status is set via {@link EndSpanOptions.Builder#setStatus(Status)} that
* will always be the last call.
*
* @param status the {@link Status} to set.
* @since 0.9
*/
public void setStatus(Status status) {
// Implemented as no-op for backwards compatibility (for example gRPC extends Span in tests).
// Implementation must override this method.
Utils.checkNotNull(status, "status");
}
/**
* Marks the end of {@code Span} execution with the given options.
*
* Only the timing of the first end call for a given {@code Span} will be recorded, and
* implementations are free to ignore all further calls.
*
* @param options the options to be used for the end of the {@code Span}.
* @since 0.5
*/
public abstract void end(EndSpanOptions options);
/**
* Marks the end of {@code Span} execution with the default options.
*
* Only the timing of the first end call for a given {@code Span} will be recorded, and
* implementations are free to ignore all further calls.
*
* @since 0.5
*/
public final void end() {
end(EndSpanOptions.DEFAULT);
}
/**
* Returns the {@code SpanContext} associated with this {@code Span}.
*
* @return the {@code SpanContext} associated with this {@code Span}.
* @since 0.5
*/
public final SpanContext getContext() {
return context;
}
/**
* Returns the options associated with this {@code Span}.
*
* @return the options associated with this {@code Span}.
* @since 0.5
*/
public final Set