package tracing
- Alphabetic
- Public
- Protected
Package Members
- package opencensus
Type Members
- sealed class AnnotatingTracingFilter[Req, Rep] extends SimpleFilter[Req, Rep]
A generic filter that can be used for annotating the Server and Client side of a trace.
A generic filter that can be used for annotating the Server and Client side of a trace. Finagle-specific trace information should live here.
- sealed abstract class Annotation extends AnyRef
An ADT describing a tracing annotation.
An ADT describing a tracing annotation. Prefer Tracing API to creating raw Annotation instances (especially, when used from Java).
- class BufferingTracer extends Tracer with Iterable[Record]
A tracer that buffers each record in memory.
A tracer that buffers each record in memory. These may then be iterated over.
- case class Flags(flags: Long) extends Product with Serializable
Represents flags that can be passed along in request headers.
Represents flags that can be passed along in request headers.
- flags
Initial flag state. May be 0.
- class NullTracer extends Tracer
A no-op Tracer.
A no-op Tracer.
- Note
supplying this tracer to a finagle client or server will not prevent trace information from being propagated to the next peer, but it will ensure that the client or server does not log any trace information about this host. If traces are being aggregated across your fleet, it will orphan subsequent spans.
- case class Record(traceId: TraceId, timestamp: Time, annotation: Annotation, duration: Option[Duration]) extends Product with Serializable
Records information of interest to the tracing system.
Records information of interest to the tracing system. For example when an event happened, the service name or ip addresses involved.
- traceId
Which trace is this record a part of?
- timestamp
When did the event happen?
- annotation
What kind of information should we record?
- duration
Did this event have a duration? For example: how long did a certain code block take to run
- final class SpanId extends Proxy with Serializable
Defines trace identifiers.
Defines trace identifiers. Span IDs name a particular (unique) span, while TraceIds contain a span ID as well as context (parentId and traceId).
- final case class TraceId(_traceId: Option[SpanId], _parentId: Option[SpanId], spanId: SpanId, _sampled: Option[Boolean], flags: Flags, traceIdHigh: Option[SpanId] = None, terminal: Boolean = false) extends Product with Serializable
A trace id represents one particular trace for one request.
A trace id represents one particular trace for one request.
A request is composed of one or more spans, which are generally RPCs but may be other in-process activity. The TraceId for each span is a tuple of three ids:
- a shared id common to all spans in an overall request (trace id) 2. an id unique to this part of the request (span id) 3. an id for the parent request that caused this span (parent id)
For example, when service M calls service N, they may have respective TraceIds like these:
TRACE ID SPAN ID PARENT ID SERVICE M e4bbb7c0f6a2ff07.a5f47e9fced314a2<:694eb2f05b8fd7d1 | | | +-----------------+ | | v v SERVICE N e4bbb7c0f6a2ff07.263edc9b65773b08<:a5f47e9fced314a2
Parent id and trace id are optional when constructing a TraceId because they are not present for the very first span in a request. In this case all three ids in the resulting TraceId are the same:
TRACE ID SPAN ID PARENT ID SERVICE A 34429b04b6bbf478.34429b04b6bbf478<:34429b04b6bbf478
- _traceId
The low 64bits of the id for this request.
- _parentId
The id for the request one step up the service stack.
- spanId
The id for this particular request
- _sampled
Should we sample this request or not? True means sample, false means don't, none means we defer decision to someone further down in the stack.
- flags
Flags relevant to this request. Could be things like debug mode on/off. The sampled flag could eventually be moved in here.
- traceIdHigh
The high 64bits of the id for this request, when the id is 128bits.
- terminal
Whether this trace id is terminal. Any attempts to override a terminal trace id will be ignored.
- case class TraceId128(low: Option[SpanId], high: Option[SpanId]) extends Product with Serializable
- class TraceInitializerFilter[Req, Rep] extends SimpleFilter[Req, Rep]
The TraceInitializerFilter takes care of span lifecycle events.
The TraceInitializerFilter takes care of span lifecycle events. It is always placed first in the service com.twitter.finagle.Filter chain (or last in the com.twitter.finagle.Stack) so that protocols with trace support will override the span resets, and still be properly reported here.
- Note
This should be replaced by per-codec trace initializers that is capable of parsing trace information out of the codec.
- class TracelessFilter extends TypeAgnostic
A filter to clear tracing information
- trait Tracer extends AnyRef
Tracers record trace events.
- abstract class Tracing extends AnyRef
This is a tracing system similar to Dapper:
This is a tracing system similar to Dapper:
“Dapper, a Large-Scale Distributed Systems Tracing Infrastructure”, Benjamin H. Sigelman, Luiz André Barroso, Mike Burrows, Pat Stephenson, Manoj Plakal, Donald Beaver, Saul Jaspan, Chandan Shanbhag, 2010.
It is meant to be independent of whatever underlying RPC mechanism is being used, and it is up to the underlying codec to implement the transport.
Trace(a singleton object) maintains the state of the tracing stack stored in com.twitter.finagle.context.Contexts. The current TraceId has aterminalflag, indicating whether it can be overridden with a different TraceId. Setting the current TraceId as terminal forces all future annotation to share that TraceId. When reporting, we report to all tracers in the list ofTracers.The Tracing API is structured in a way it's caller's responsibility to check if the current stack of tracers is actively tracing (
Trace.isActivelyTracing) to avoid unnecessarily allocations.It's recommended to "capture" a Tracing instance while performing multiple tracing operations to minimize the number of com.twitter.finagle.context.Contexts lookups and increase throughput.
// Performs six context lookups (two for isActivelyTracing, two for each record call). if (Trace.isActivelyTracing()) { Trace.record("foo") Trace.record("foo") } // Performs just two context lookups and captures the results in the `Trace` instance. val trace = Trace() if (trace.isActivelyTracing) { trace.record("foo") trace.record("bar") }
- Note
Use
Trace.getInstance()andTrace.newInstance()in Java.
- class TracingLogHandler extends Handler
A logging Handler that sends log information via tracing
Value Members
- object AnnotatingTracingFilter
- object Annotation
- object BroadcastTracer
- object ClientTracingFilter
Annotate the request with Client specific records (ClientSend, ClientRecv)
- object ConsoleTracer extends Tracer
- object DefaultTracer extends Tracer with Proxy
- object Flags extends Serializable
- object ForwardAnnotation
Allow us to inject annotations into children trace contexts.
Allow us to inject annotations into children trace contexts. Example, with dark traffic or retries we want to be able to tag the produced spans from each call (the light/dark calls, or each individual retry) with information that allows us to tie them together as a single logical item: a light request paired with a dark request, or an initial request and a series of retries. The problem lies in the fact that at the time we have the information about the relationship, the child trace context doesn't actually yet exist. In order to trace where it is needed, we need to have a hook into the trace context of these children requests which don't yet exist. We do this by placing annotations we want each child trace context to carry inside the local context and accessing them when the child trace context is realized through a stack module. The stack module will place a filter in the correct trace context, after the Trace Initialization Filter, which allows us to record the annotations in the proper place.
- object NullTracer extends NullTracer
A singleton instance of a no-op NullTracer.
- object Record extends Serializable
- object ResourceTracingFilter
Annotate the low level resource utilization of traced requests such as the accumulated cpu time of executed continuations.
- object ServerTracingFilter
Annotate the request with Server specific records (ServerRecv, ServerSend)
- object SpanId extends Serializable
- object Trace extends Tracing
A singleton instance of Tracing (a facade-style API) that performs a number of Contexts lookups on each operation.
- object TraceId extends Serializable
- object TraceId128 extends Serializable
- object TraceInitializerFilter
- object TraceServiceName
Exposes an API for setting the global service name for this finagle process which is used to identify traces that belong to the respective process.
- object Tracer
- object Tracing
- object WireTracingFilter
Annotate the request events directly before/after sending data on the wire (WireSend, WireRecv)
- object enabled extends GlobalFlag[Boolean]
- object traceId128Bit extends GlobalFlag[Boolean]