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. val LocalBeginAnnotation: String
  5. val LocalEndAnnotation: String
  6. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  7. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  8. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  9. def equals(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef → Any
  10. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  11. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  12. def hasId: Boolean

    True if there is an identifier for the current trace.

  13. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  14. 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.

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

  16. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  17. final def isTerminal: Boolean

    Return true if the current trace id is terminal.

  18. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  19. final def nextId: TraceId

    Create a derived id from the current TraceId.

  20. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  21. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  22. final def record(message: String): Unit
  23. final def record(ann: Annotation, duration: Duration): Unit
  24. final def record(ann: Annotation): Unit
  25. 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.

  26. final def recordBinaries(annotations: Map[String, Any]): Unit
  27. final def recordBinary(key: String, value: Any): Unit
  28. 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.

  29. final def recordClientAddr(ia: InetSocketAddress): Unit
  30. final def recordClientRecv(): Unit
  31. final def recordClientRecvError(error: String): Unit
  32. final def recordClientRecvFragment(): Unit
  33. final def recordClientSend(): Unit
  34. final def recordClientSendFragment(): Unit
  35. final def recordFilePath(filePath: String): Unit
  36. final def recordLineNumber(lineNumber: Int): Unit
  37. final def recordLocalAddr(ia: InetSocketAddress): Unit
  38. final def recordLocalSpan(name: String, timestamp: Time, duration: Duration): Unit

    Adds an annotation such that the zipkin UI can properly display it

    Adds an annotation such that the zipkin UI can properly display it

    Attributes
    protected
    Note

    This method does *not* check isActivelyTracing -- the onus is on the user to include this check.

  39. final def recordMethodName(methodName: String): Unit
  40. final def recordNamespace(namespace: String): Unit
  41. final def recordRpc(name: String): Unit
  42. final def recordServerAddr(ia: InetSocketAddress): Unit
  43. final def recordServerRecv(): Unit
  44. final def recordServerRecvFragment(): Unit
  45. final def recordServerSend(): Unit
  46. final def recordServerSendError(error: String): Unit
  47. final def recordServerSendFragment(): Unit
  48. final def recordServiceName(serviceName: String): Unit
  49. final def recordWireRecv(): Unit
  50. final def recordWireRecvError(error: String): Unit
  51. final def recordWireSend(): Unit
  52. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  53. 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

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

  55. def toString(): String
    Definition Classes
    AnyRef → Any
  56. 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.

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

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

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

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

  61. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  62. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  63. 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