126 lines
2.9 KiB
Java
126 lines
2.9 KiB
Java
package datadog.trace.tracer;
|
|
|
|
/**
|
|
* A single measurement of time with arbitrary key-value attributes.
|
|
*
|
|
* <p>All spans are thread safe.
|
|
*
|
|
* <p>To create a Span, see {@link Tracer#buildTrace()}
|
|
*/
|
|
public interface Span {
|
|
|
|
/** @return The trace this span is associated with. */
|
|
Trace getTrace();
|
|
|
|
/** Stop the span's timer. Has no effect if the span is already finished. */
|
|
void finish();
|
|
|
|
/**
|
|
* Stop the span's timer. Has no effect if the span is already finished.
|
|
*
|
|
* <p>It's undefined behavior to specify a finish timestamp which occurred before this span's
|
|
* start timestamp.
|
|
*
|
|
* @param finishTimestampNanoseconds Epoch time in nanoseconds.
|
|
*/
|
|
void finish(long finishTimestampNanoseconds);
|
|
|
|
/** Returns true if a finish method has been invoked on this span. */
|
|
boolean isFinished();
|
|
|
|
/**
|
|
* Attach a {@link LifecycleInterceptor} to this span.
|
|
*
|
|
* @param interceptor the interceptor to attach.
|
|
*/
|
|
void addInterceptor(LifecycleInterceptor interceptor);
|
|
|
|
/**
|
|
* Get the span context for this span.
|
|
*
|
|
* @return the span context.
|
|
*/
|
|
SpanContext getContext();
|
|
|
|
/**
|
|
* Get a meta value on a span.
|
|
*
|
|
* @param key The meta key
|
|
* @return The value currently associated with the given key. Null if no associated. TODO: can
|
|
* return null
|
|
*/
|
|
Object getMeta(String key);
|
|
|
|
/**
|
|
* Set key-value metadata on the span.
|
|
*
|
|
* <p>TODO: Forbid setting null?
|
|
*/
|
|
void setMeta(String key, String value);
|
|
|
|
/** {@link Span#setMeta(String, String)} for boolean values */
|
|
void setMeta(String key, boolean value);
|
|
|
|
/** {@link Span#setMeta(String, String)} for number values */
|
|
void setMeta(String key, Number value);
|
|
|
|
/** Get the span's name */
|
|
String getName();
|
|
/**
|
|
* Set the span's name.
|
|
*
|
|
* @param newName the new name for the span.
|
|
*/
|
|
void setName(String newName);
|
|
|
|
String getResource();
|
|
|
|
void setResource(String newResource);
|
|
|
|
String getService();
|
|
|
|
void setService(String newService);
|
|
|
|
String getType();
|
|
|
|
void setType(String newType);
|
|
|
|
boolean isErrored();
|
|
|
|
/** Attach a throwable to this span. */
|
|
void attachThrowable();
|
|
|
|
/**
|
|
* Mark the span as having an error.
|
|
*
|
|
* @param isErrored true if the span has an error.
|
|
*/
|
|
void setError(boolean isErrored);
|
|
|
|
// TODO: OpenTracing Span#log methods. Do we need something here to support them? Current DDSpan
|
|
// does not implement.
|
|
|
|
/**
|
|
* A LifecycleInterceptor allows adding hooks to particular events between a span starting and
|
|
* finishing.
|
|
*/
|
|
interface LifecycleInterceptor {
|
|
/**
|
|
* Called after a span is started.
|
|
*
|
|
* @param span the started span
|
|
*/
|
|
void spanStarted(Span span);
|
|
|
|
/** Called after a span's metadata is updated. */
|
|
void afterMetadataSet(Span span, Object key, Object value);
|
|
|
|
/**
|
|
* Called after a span is finished.
|
|
*
|
|
* @param span the started span
|
|
*/
|
|
void spanFinished(Span span);
|
|
}
|
|
}
|