Packages

abstract class Tracing extends AnyRef

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.

Linear Supertypes
AnyRef, Any
Known Subclasses
Trace
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Tracing
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Instance Constructors

  1. new Tracing()

Abstract Value Members

  1. abstract def idOption: Option[TraceId]

    Get the current identifier, if it exists.

  2. abstract def tracers: Seq[Tracer]

    returns

    the current list of tracers

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##: Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  8. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  9. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  10. def hasId: Boolean

    True if there is an identifier for the current trace.

  11. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  12. final def id: TraceId

    Get the current trace identifier.

    Get the current trace identifier. If no identifiers have been pushed, a default one is provided.

  13. final def isActivelyTracing: Boolean

    Return true if tracing is enabled with a good tracer pushed and at least one tracer decides to actively trace the current id.

  14. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  15. final def isTerminal: Boolean

    Return true if the current trace id is terminal.

  16. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  17. final def nextId: TraceId

    Create a derived id from the current TraceId.

  18. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  19. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  20. final def peerId: TraceId

    Create a derived id from the current TraceId.

    Create a derived id from the current TraceId. Whereas nextId derives a new Id by making it a child of the current, peerId creates a new Id by making it a peer of the current

  21. final def record(message: String): Unit
  22. final def record(ann: Annotation, duration: Duration): Unit
  23. final def record(ann: Annotation): Unit
  24. final def record(rec: Record): Unit

    Record a raw Record.

    Record a raw Record. This will record to a _unique_ set of tracers in the stack.

  25. final def recordBinaries(annotations: Map[String, Any]): Unit
  26. final def recordBinary(key: String, value: Any): Unit
  27. final def recordCallSite(): Unit

    WARNING: This method call is expensive.

    WARNING: This method call is expensive. It must be sampled. Record the method name, namespace, absolute filepath and line number.

  28. final def recordClientAddr(ia: InetSocketAddress): Unit
  29. final def recordClientRecv(): Unit
  30. final def recordClientRecvError(error: String): Unit
  31. final def recordClientRecvFragment(): Unit
  32. final def recordClientSend(): Unit
  33. final def recordClientSendFragment(): Unit
  34. final def recordFilePath(filePath: String): Unit
  35. final def recordLineNumber(lineNumber: Int): Unit
  36. final def recordLocalAddr(ia: InetSocketAddress): Unit
  37. final def recordMethodName(methodName: String): Unit
  38. final def recordNamespace(namespace: String): Unit
  39. final def recordRpc(name: String): Unit
  40. final def recordServerAddr(ia: InetSocketAddress): Unit
  41. final def recordServerRecv(): Unit
  42. final def recordServerRecvFragment(): Unit
  43. final def recordServerSend(): Unit
  44. final def recordServerSendError(error: String): Unit
  45. final def recordServerSendFragment(): Unit
  46. final def recordServiceName(serviceName: String): Unit
  47. final def recordWireRecv(): Unit
  48. final def recordWireRecvError(error: String): Unit
  49. final def recordWireSend(): Unit
  50. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  51. def time[T](message: String)(f: => T): T

    Time an operation and add a binary annotation to the current span with the duration.

    Time an operation and add a binary annotation to the current span with the duration.

    T

    return type

    message

    The message describing the operation

    f

    operation to perform

    returns

    return value of the operation

  52. def timeFuture[T](message: String)(f: Future[T]): Future[T]

    Time an async operation and add a binary annotation to the current span with the duration.

  53. def toString(): String
    Definition Classes
    AnyRef → Any
  54. def traceLocal[T](name: String)(f: => T): T

    Create a span that begins right before the function is called and ends immediately after the function completes.

    Create a span that begins right before the function is called and ends immediately after the function completes. This span will never have a corresponding remote component and is contained completely within the process it is created.

  55. def traceLocalFuture[T](name: String)(f: => Future[T]): Future[T]

    Create a span that begins right before the function is called and ends immediately after the async operation completes.

    Create a span that begins right before the function is called and ends immediately after the async operation completes. This span will never have a corresponding remote component and is contained completely within the process it is created.

  56. def traceLocalSpan(name: String, timestamp: Time, duration: Duration): Unit

    Create a span with the given name, timestamp and Duration.

    Create a span with the given name, timestamp and Duration. This is useful for debugging, or if you do not have complete control over the whole execution, e.g. you can not use traceLocalFuture.

  57. def traceLocalSpan(name: String, duration: Duration): Unit

    Create a span with the given name and Duration, with the end of the span at Time.now.

  58. def traceService[T](service: String, rpc: String, hostOpt: Option[InetSocketAddress] = None)(f: => T): T

    Convenience method for event loops in services.

    Convenience method for event loops in services. Put your service handling code inside this to get proper tracing with all the correct fields filled in.

  59. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  60. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  61. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()

Deprecated Value Members

  1. final def record(message: String, duration: Duration): Unit
    Annotations
    @deprecated
    Deprecated

    (Since version 2019-20-10) Use Trace#traceLocal instead

Inherited from AnyRef

Inherited from Any

Ungrouped