Trace

public class Trace implements Parcelable

Trace allows you to set beginning and end of a certain action in your app.

Summary

Constants
static final Parcelable.Creator<Trace>

A public static CREATOR field that implements Parcelable.Creator and generates instances of your Parcelable class from a Parcel.
static final int

Maximum allowed length of the Key of the Trace attribute
static final int

Maximum allowed length of the Value of the Trace attribute
static final int

Maximum allowed number of attributes allowed in a trace.
static final int

Maximum allowed length of the name of the Trace

Public fields
final String

Public methods
int

Describes the kinds of special objects contained in this Parcelable's marshalled representation.
@Nullable String

Returns the value of an attribute.
@NonNull Map<String, String>

Returns the map of all the attributes added to this trace.
long

Gets the value of the metric with the given name in the current trace.
void
@Keep
incrementMetric(@NonNull String metricName, long incrementBy)

Atomically increments the metric with the given name in this trace by the incrementBy value.
void
@Keep
putAttribute(@NonNull String attribute, @NonNull String value)

Sets a String value for the specified attribute.
void
@Keep
putMetric(@NonNull String metricName, long value)

Sets the value of the metric with the given name in this trace to the value provided.
void

Removes an already added attribute from the Traces.
void

Starts this trace.
void

Stops this trace.
void
@Keep
writeToParcel(@NonNull Parcel out, int flags)

Flatten this object into a Parcel.

Extension functions
final @NonNull T
<T extends Object> PerformanceKt.trace(
    @NonNull Trace receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull Trace, @NonNull T> block
)

Measures the time it takes to run the block wrapped by calls to start and stop using Trace.
final @NonNull T
<T extends Object> PerformanceKt.trace(
    @NonNull Trace receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull Trace, @NonNull T> block
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

Inherited Constants
From android.os.Parcelable
static final int
static final int

Constants

CREATOR

@Keep
public static final Parcelable.Creator<Trace> CREATOR

A public static CREATOR field that implements Parcelable.Creator and generates instances of your Parcelable class from a Parcel.

MAX_ATTRIBUTE_KEY_LENGTH

public static final int MAX_ATTRIBUTE_KEY_LENGTH = 40

Maximum allowed length of the Key of the Trace attribute

MAX_ATTRIBUTE_VALUE_LENGTH

public static final int MAX_ATTRIBUTE_VALUE_LENGTH = 100

Maximum allowed length of the Value of the Trace attribute

MAX_TRACE_CUSTOM_ATTRIBUTES

public static final int MAX_TRACE_CUSTOM_ATTRIBUTES = 5

Maximum allowed number of attributes allowed in a trace.

MAX_TRACE_NAME_LENGTH

public static final int MAX_TRACE_NAME_LENGTH = 100

Maximum allowed length of the name of the Trace

Public fields

name

public final String name

Public methods

describeContents

@Keep
public int describeContents()

Describes the kinds of special objects contained in this Parcelable's marshalled representation.

Returns
int

always returns 0.
See also
Parcelable

getAttribute

@Keep
public @Nullable String getAttribute(@NonNull String attribute)

Returns the value of an attribute.

Parameters
@NonNull String attribute

name of the attribute to fetch the value for
Returns
@Nullable String

the value of the attribute if it exists or null otherwise.

getAttributes

@Keep
public @NonNull Map<String, String> getAttributes()

Returns the map of all the attributes added to this trace.

Returns
@NonNull Map<String, String>

map of attributes and its values currently added to this Trace

getLongMetric

@Keep
public long getLongMetric(@NonNull String metricName)

Gets the value of the metric with the given name in the current trace. If a metric with the given name doesn't exist, it is NOT created and a 0 is returned. This method is atomic.

Parameters
@NonNull String metricName

Name of the metric to get. Requires no leading or trailing whitespace, no leading underscore '_' character, max length is 100 characters.
Returns
long

Value of the metric or 0 if it hasn't yet been set.

incrementMetric

@Keep
public void incrementMetric(@NonNull String metricName, long incrementBy)

Atomically increments the metric with the given name in this trace by the incrementBy value. If the metric does not exist, a new one will be created. If the trace has not been started or has already been stopped, returns immediately without taking action.

Parameters
@NonNull String metricName

Name of the metric to be incremented. Requires no leading or trailing whitespace, no leading underscore [_] character, max length of 100 characters.
long incrementBy

Amount by which the metric has to be incremented.

putAttribute

@Keep
public void putAttribute(@NonNull String attribute, @NonNull String value)

Sets a String value for the specified attribute. Updates the value of the attribute if the attribute already exists. If the trace has been stopped, this method returns without adding the attribute. The maximum number of attributes that can be added to a Trace are MAX_TRACE_CUSTOM_ATTRIBUTES.

Parameters
@NonNull String attribute

Name of the attribute
@NonNull String value

Value of the attribute

putMetric

@Keep
public void putMetric(@NonNull String metricName, long value)

Sets the value of the metric with the given name in this trace to the value provided. If a metric with the given name doesn't exist, a new one will be created. If the trace has not been started or has already been stopped, returns immediately without taking action. This method is atomic.

Parameters
@NonNull String metricName

Name of the metric to set. Requires no leading or trailing whitespace, no leading underscore '_' character, max length is 100 characters.
long value

The value to which the metric should be set to.

removeAttribute

@Keep
public void removeAttribute(@NonNull String attribute)

Removes an already added attribute from the Traces. If the trace has been stopped, this method returns without removing the attribute.

Parameters
@NonNull String attribute

Name of the attribute to be removed from the running Traces.

start

@Keep
public void start()

Starts this trace.

stop

@Keep
public void stop()

Stops this trace.

writeToParcel

@Keep
public void writeToParcel(@NonNull Parcel out, int flags)

Flatten this object into a Parcel. Please refer to https://developer.android.com/reference/android/os/Parcelable.html

Parameters
@NonNull Parcel out

the Parcel in which the object should be written.
int flags

Additional flags about how the object should be written.

Extension functions

PerformanceKt.trace

public final @NonNull T <T extends Object> PerformanceKt.trace(
    @NonNull Trace receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull Trace, @NonNull T> block
)

Measures the time it takes to run the block wrapped by calls to start and stop using Trace.

PerformanceKt.trace

public final @NonNull T <T extends Object> PerformanceKt.trace(
    @NonNull Trace receiver,
    @ExtensionFunctionType @NonNull Function1<@NonNull Trace, @NonNull T> block
)

Measures the time it takes to run the block wrapped by calls to start and stop using Trace.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-perf-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.