Android OpenTelemetry exporter walkthrough

Since our SDKs are also open source, you can collect and forward your mobile telemetry data to another service without being a paid Embrace user. 

In this tutorial, we’ll show you how to do this for a powerful OpenTelemetry data type – traces (and spans).

We’ll guide you through the steps to instrument and collect OpenTelemetry spans from your app via Embrace’s Android SDK, and then how to send those traces from your interconnected spans on to a generic exporter. 

You can also learn more from our video tutorials on OTel signal instrumentation here.

If you’re an iOS developer, head over to our iOS tutorials for OpenTelemetry.

As a prerequisite for the rest of this tutorial, you’ll need to integrate the Embrace SDK. If you’ve already done so, feel free to skip ahead to step 2. If not, follow these instructions on how to get set up with the SDK first. 

Let’s now grab the open source Embrace SDK and import it into our project. You can find the repo here. 

To get started using the Embrace SDK, you’ll need to first update your settings.gradle:

pluginManagement {
    repositories {
        mavenCentral()
    }
    val swazzler_version: String by settings
    plugins {
        id("io.embrace.swazzler") version "${swazzler_version}" apple false
    }

and be sure to define swazzler_version as the latest version in gradle.properties

swazzler_version=6.6.0

Finally, in app/build.gradle, apply the plugin:

plugins {
    id("io.embrace.swazzler")
}

If you are having difficulty, be sure to check out the documentation for adding Embrace as a dependency.

Before we begin the Embrace Android SDK, we can add one or multiple exporters to give a destination for our traces once that data is actually generated. 

The exporter is a component that will connect the Embrace SDK, which will collect the traces and spans, with an external OpenTelemetry collector that will receive the data.

Note: In the Embrace Android SDK, you must add all exporters before starting the SDK

2A: Download the exporter

You don’t have to build an exporter yourself as there are a few open source options available to you. For this example, we’ll be using the OpenTelemetry Zipkin exporter for Java . This will let the Embrace SDK send your traces and spans data to Zipkin, an observability backend that lets you visualize your data nicely.

2B: Attach the Zipkin exporter object 

The exporter object provides the interface for the Embrace SDK to send our traces and spans to an exporter. By default, the Embrace SDK won’t send telemetry anywhere, but you can tell it to do that by attaching an exporter object. The parameter can be either a collector location, or an endpoint for an observability backend.

If we wanted to export to an OTel Collector running locally via HTTP, we could build the following exporter:

val customLocalExporter = OtlpHttpSpanExporter.builder()
    .setEndpoint("http://10.0.2.2:4318")

With a Zipkin image running locally, we can build the exporter from the OpenTelemetry-Java link above. The ports are pre-configured for the ZipkinSpanExporter (port 9411), so you shouldn’t need to change any settings.

val zipkinLocalExporter = ZipkinSpanExporter.build()

Embrace.getInstance().addSpanExporter(customLocalExporter)
Embrace.getInstance().addSpanExporter(zipkinLocalExporter)

Prior to any instrumentation, but after adding all exporters, you should start the Embrace Android SDK:

Embrace.getInstance().start(this)

Now that we’ve got the exporter and its destination set up, we can back into our source code and instrument some spans. 

If you’re not familiar with spans and traces, they allow you to observe flows or transaction in your app (trace) by breaking it up into its component operations (spans). You’ll know you should use traces and spans if you want to observe a process over time by collecting the steps that complete that process.

For example, a trace might be taking a dog for a walk, and the spans or “units of work” that make up that trace might be finding one’s shoes, picking up waste, and returning home.

Let’s define our trace around the walk, as follows:

val walkTrace = Embrace.getInstance().startSpan("Afternoon Walk")

The .startSpan call both creates the span, and starts it beginning right now.

Spans can have parent-child relationships, which can be helpful in building and understanding hierarchy. Let’s add a child span to the walk trace we’ve already instrumented, making that original span a parent:

val findShoesSpan = walkTrace?.let {
    Embrace.getInstance().startSpan("Find Leash", it) 
}

We can give our spans even more context by adding attributes and events. Attributes are represented by key-value pairs, while events record a point-in-time condition.

If your walk brought you to Golden Gate Park, your parent trace might have an attribute key of “walk-location” with the value “park”:

walkTrace?.addAttribute("walk-location", "park")

findShoesSpan?.addEvent("Barked and misbehaved")

For spans to be completed and exported, they must be stopped in the client instrumentation. The Embrace SDKs have no automatic instrumentation to end a span if device changes occur, as span ends must be defined.

// stop span
walkTrace?.stop()

// stop span with failure
walkTrace?.stop(ErrorCode.FAILURE)

Run your sample app a few times to generate some data. 

In step 2, we set up an exporter to send our spans to Zipkin. No further configuration is required to connect the SDK to the Zipkin instance. Now that we’ve run the app a few times, let’s check out the Zipkin UI and see if the data was indeed captured.

Success! We’ve integrated the Embrace Android SDK, set up an exporter to connect the application to Zipkin, instrumented our spans, and now are able to view them as traces in this tracing system. Full mobile-client instrumentation is available in our OpenTelemetry SDK, even if you don’t want to use Embrace as your backend.