tracing

Type Members

1. 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.

2. 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).

3. 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.

4. class ClientDestTracingFilter[Req, Rep] extends SimpleFilter[Req, Rep]

   

   com.twitter.finagle.Filter for clients to record the remote address of the server.

   com.twitter.finagle.Filter for clients to record the remote address of the server. We don't log the local addr here because it's already done in the client Dispatcher.

5. trait ClientRequestTracingFilter[Req, Res] extends SimpleFilter[Req, Res]

   

   Adds the basic tracing information to a request.

   Adds the basic tracing information to a request. Includes: rpc service name, method name, client sent and client received.

6. 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.

7. class NullTracer extends Tracer

   

   A no-op Tracer.

8. 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

9. final class SpanId extends Proxy

   

   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).

10. 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:

    1. 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 attemtps to override a terminal trace id will be ignored.

11. case class TraceId128(low: Option[SpanId], high: Option[SpanId]) extends Product with Serializable

    

12. 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.

13. trait Tracer extends AnyRef

    

    Tracers record trace events.

14. 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 a terminal flag, 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 of Tracers.

    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() and Trace.newInstance() in Java.

15. class TracingLogHandler extends Handler

    

    A logging Handler that sends log information via tracing