Manual instrumentation using the Elastic Distribution of OpenTelemetry Android

Learn how to manually instrument Android applications using the Elastic Distribution of OpenTelemetry SDK to capture spans, add attributes, and send trace data to Elastic.

You can create your custom spans, metrics, and logs, using the OpenTelemetry SDK APIs, which you can find in the OpenTelemetry object provided through the getOpenTelemetry() method.

Alternatively, for common operations, you can use the convenience EDOT Android extensions to create telemetry in a less verbose way.

After completing the setup process, EDOT Android has configured an OpenTelemetry object for you, which is available through the getOpenTelemetry() method.

Here's an example of how to create telemetry using the OpenTelemetry Java APIs:

import co.elastic.otel.android.ElasticApmAgent

fun myMethod() {
    val agent: ElasticApmAgent

    // Span example
    val tracer = agent.getOpenTelemetry().getTracer("my-tracer-scope")
    val span = tracer.spanBuilder("spanName").startSpan()
    // ...
    span.end()

    // Metric example
    val counter = agent.getOpenTelemetry().meterBuilder("meterScope").build().counterBuilder("myCounter").build()
    counter.add(1)

    // Logs example
    val logger = agent.getOpenTelemetry().logsBridge["logScope"]
    logger.logRecordBuilder().setBody("Log body").emit()
}

For more details on creating signals using the OpenTelemetry APIs, refer to the following pages:

• Manually create spans.
• Manually create metrics.
• Manually create logs.

For common use cases, such as spans and logs creation, EDOT Android provides a couple of Kotlin extension methods to allow you to create telemetry in a less verbose way.

The convenience methods make use of the same OpenTelemetry APIs internally to create telemetry. While they're not the only way to create the following signals, they make it easier to create them.

The following example shows how to manually create a span using the convenience extension:

import co.elastic.otel.android.ElasticApmAgent
import co.elastic.otel.android.extensions.span

fun myMethod() {
    val agent: ElasticApmAgent

    agent.span("spanName") {
        // The span body.
    }
}

1. The span name and its body are the only mandatory parameters from this method. However, there are other optional parameters, such as one to set custom attributes, that you can provide if needed. Refer to the method definition for more details.

The following example shows how to manually create a log record using the convenience extension:

import co.elastic.otel.android.ElasticApmAgent
import co.elastic.otel.android.extensions.log

fun myMethod() {
    val agent: ElasticApmAgent

    agent.log("My log body")
}

1. The log record body is the only mandatory parameter from this method. However, there are other optional parameters (such as one to set custom attributes), that you can provide if needed. Refer to the method definition for more details.