embrace-android-api/io.embrace.android.embracesdk.spans/TracingApi

TracingApi

interface TracingApi

The public API used to add traces to your application. Note that recordCompletedSpan can be used before the SDK is initialized. The actual trace won't be recorded until the SDK is started, but it's safe to use this prior to SDK initialization.

Functions

Link copied to clipboard
open fun createSpan(name: String): EmbraceSpan?

Create an EmbraceSpan with the given name that will be the root span of a new trace. Returns null if the EmbraceSpan cannot be created given the current conditions of the SDK or an invalid name.

abstract fun createSpan(name: String, parent: EmbraceSpan?): EmbraceSpan?

Create an EmbraceSpan with the given name and parent. Passing in a parent that is null result in a new trace with this EmbraceSpan as its root. Returns null if the EmbraceSpan cannot be created, e.g if the parent has not been started, the name is invalid, or some other factor due to the current conditions of the SDK.

Link copied to clipboard
abstract fun getSpan(spanId: String): EmbraceSpan?

Return the EmbraceSpan corresponding to the given spanId if it is active or it has completed in the current session. Returns null if a span corresponding to the given spanId cannot be found, which can happen if this span never existed or if was completed in a prior session.

Link copied to clipboard
abstract fun isTracingAvailable(): Boolean
Link copied to clipboard
open fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long): Boolean

Record a span with the given name, start time, and end time (epoch time in milliseconds). The created span will be the root span of a new trace.

open fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long, parent: EmbraceSpan?): Boolean

Record a span with the given name, parent, start time, and end time (epoch time in milliseconds). Passing in a parent that is null will result in a new trace with the new span as its root.

open fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long, errorCode: ErrorCode?): Boolean

Record a span with the given name, error code, start time, and end time (epoch time in milliseconds). The created span will be the root span of a new trace. A non-null ErrorCode can be passed in to denote the operation the span represents was ended unsuccessfully under the stated circumstances.

open fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long, errorCode: ErrorCode?, parent: EmbraceSpan?): Boolean

Record a span with the given name, parent, error code, start time, and end time (epoch time in milliseconds). Passing in a parent that is null will result in a new trace with the new span as its root. A non-null ErrorCode can be passed in to denote the operation the span represents was ended unsuccessfully under the stated circumstances.

open fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long, attributes: Map<String, String>?, events: List<EmbraceSpanEvent>?): Boolean

Record a span with the given name, start time, and end time (epoch time in milliseconds). The created span will be the root span of a new trace. You can also pass in a Map with String keys and values to be used as the attributes of the recorded span, or a List of EmbraceSpanEvent to be used as the events of the recorded span.

abstract fun recordCompletedSpan(name: String, startTimeMs: Long, endTimeMs: Long, errorCode: ErrorCode?, parent: EmbraceSpan?, attributes: Map<String, String>?, events: List<EmbraceSpanEvent>?): Boolean

Record a span with the given name, error code, parent, start time, and end time (epoch time in milliseconds). Passing in a parent that is null will result in a new trace with the new span as its root. A non-null ErrorCode can be passed in to denote the operation the span represents was ended unsuccessfully under the stated circumstances. You can also pass in a Map with String keys and values to be used as the attributes of the recorded span, or a List of EmbraceSpanEvent to be used as the events of the recorded span.

Link copied to clipboard
open fun <T> recordSpan(name: String, code: () -> T): T

Execute the given block of code and record a new trace around it. If the span cannot be created, the block of code will still run and return correctly. If an exception or error is thrown inside the block, the span will end at the point of the throw and the Throwable will be rethrown.

open fun <T> recordSpan(name: String, parent: EmbraceSpan?, code: () -> T): T

Execute the given block of code and record a new span around it with the given parent. Passing in a parent that is null will result in a new trace with the new span as its root. If the span cannot be created, the block of code will still run and return correctly. If an exception or error is thrown inside the block, the span will end at the point of the throw and the Throwable will be rethrown.

open fun <T> recordSpan(name: String, attributes: Map<String, String>?, events: List<EmbraceSpanEvent>?, code: () -> T): T

Execute the given block of code and record a new trace around it with optional attributes and list of EmbraceSpanEvent. If the span cannot be created, the block of code will still run and return correctly. If an exception or error is thrown inside the block, the span will end at the point of the throw and the Throwable will be rethrown.

abstract fun <T> recordSpan(name: String, parent: EmbraceSpan?, attributes: Map<String, String>?, events: List<EmbraceSpanEvent>?, code: () -> T): T

Execute the given block of code and record a new span around it with the given parent with optional attributes and list of EmbraceSpanEvent. Passing in a parent that is null will result in a new trace with the new span as its root. If the span cannot be created, the block of code will still run and return correctly. If an exception or error is thrown inside the block, the span will end at the point of the throw and the Throwable will be rethrown.

Link copied to clipboard
open fun startSpan(name: String): EmbraceSpan?

Create, start, and return a new EmbraceSpan with the given name that will be the root span of a new trace. Returns null if the EmbraceSpan cannot be created or started.

open fun startSpan(name: String, parent: EmbraceSpan?): EmbraceSpan?

Create, start, and return a new EmbraceSpan with the given name and parent. Returns null if the EmbraceSpan cannot be created or started, like if the parent has been started.

abstract fun startSpan(name: String, parent: EmbraceSpan?, startTimeMs: Long?): EmbraceSpan?

Create, start, and return a new EmbraceSpan with the given name, parent, and start time (epoch time in milliseconds). Returns null if the EmbraceSpan cannot be created or started, like if the parent has been started.