{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

Tracer

interface Tracer

Tracer provides an API implemented by wrappers around common tracing libraries, such as AndroidX Tracing. Tracer wrappers should be registered with Tracing#registerTracer.

A trace tracks the progression of various actions during testing. Each action is wrapped in a "span". A span starts when the beginSpan method is called and ends when the Span#close() method is called.

Traces are recursive. Within a specific span, nested spans are created by invoking beginChildSpan and end when a corresponding Span#close() method is called. Nested spans must be entirely constrained within their parent span.

The Span interface implements Closeable to encourage its use in a try-resource block and ensure that the Span#close() method is always properly called. Example of usage: 

  class MyCustomTracingLibraryTracer implements Tracer {}
  Tracer tracer = new MyCustomTracingLibraryTracer();
  Tracing.getInstance().registerTracer(tracer);
  try(Span span = Tracing.getInstance().beginSpan("Some Action")) {
    ...action to be traced...
  }

Summary

Nested types
Tracer.Span

Span is a helper object denoting an ongoing time span and providing a way for the caller to close and end the span to record the end of the action being traced.

Public functions
Tracer.Span!
beginSpan(name: String!)

Starts a new time span to track progression of some action.

Public functions

beginSpan

fun beginSpan(name: String!): Tracer.Span!

Starts a new time span to track progression of some action.

The implementation must return a Span object which the caller must use later to close and end the span.

Parameters
name: String!

A name describing the action performed.
Returns
Tracer.Span!

A new span object that the caller must invoke later to close the span.