Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt

Use this file to discover all available pages before exploring further.

Use the Honeycomb OpenTelemetry Android SDK to collect telemetry data from your Android application and send it to Honeycomb. Instrumenting your application lets you measure how it behaves on actual devices, detect performance issues, and better understand how users experience your application. This guide walks you through the process of instrumenting an Android application in your local development environment and verifying that telemetry is successfully flowing to Honeycomb.

​
Before You Begin

Before getting started, make sure you have:
  • A Honeycomb account If you don’t already have an account, sign up for one. Honeycomb stores your data in either a US-based or EU-based location, depending on your account region:
  • Required Tools
    • Kotlin
    • An existing Android application to instrument
  • A Honeycomb Ingest API Key For this guide, you’ll need a Honeycomb Ingest API Key with the Can create services/datasets permission. This key lets your application send telemetry to Honeycomb and create a dataset for your service.
    When deploying to production, replace this key with a separate key that does not allow dataset creation. This helps protect your data structure in live environments.

​
Add Dependencies

Add the required SDK dependencies. The Honeycomb Android SDK relies on the OpenTelemetry Android SDK, so both are required. When adding OpenTelemetry dependencies, make sure the library is compatible with the Honeycomb Android SDK. In your build.gradle.kts, add these dependencies: 
dependencies {
    implementation("io.opentelemetry.android:android-agent:0.11.0-alpha")
    implementation("io.honeycomb.android:honeycomb-opentelemetry-android:0.0.10")
}
If your application’s minSDK version is lower than 26, enable core library desugaring to support Java 8+ features: 
android {
    // ...
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

dependencies {
    coreLibraryDesugaring(libs.desugar.jdk.libs)
}
If your application’s minSdk version is below 24, then running instrumentation tests or debug application builds requires that you:
  • Use Android Gradle Plugin (AGP) 8.3.0 or later.
  • Add android.useFullClasspathForDexingTransform=true to your gradle.properties.

​
Configure the SDK

To start collecting telemetry, configure the SDK early in your application’s lifecycle. This ensures that events such as startup time and early view loads are captured. We recommend setting it up in the onCreate() method of your Application class, so configuration happens at application start. Here’s a basic example configuration: 
import io.honeycomb.opentelemetry.android.Honeycomb
import io.honeycomb.opentelemetry.android.HoneycombOptions
import io.opentelemetry.android.OpenTelemetryRum

class ExampleApp: Application() {
    var otelRum: OpenTelemetryRum? = null

    override fun onCreate() {
        super.onCreate()

        val options = HoneycombOptions.builder(this)
            // Uncomment the line below to send to EU instance. Defaults to US.
            // .setApiEndpoint("https://api.eu1.honeycomb.io:443")
            .setApiKey("YOUR-API-KEY")
            .setServiceName("YOUR-SERVICE-NAME")
            .setServiceVersion("0.0.1")
            .setDebug(true)
            .build()

        otelRum = Honeycomb.configure(this, options)
    }
}
In this example, key configuration options include: apiKey : Your Ingest API Key, which lets your application send telemetry directly to Honeycomb. serviceName : The name of your application, which Honeycomb will use as your dataset name. Choose something meaningful and consistent.
If you don’t provide a service name, the dataset name will default to unknown_service.
serviceVersion : The current version of your application. This helps track changes in behavior over different versions of your application. debug : Set to true to enable debug logs, which can help troubleshoot configuration issues during development.

​
Enable Automatic Instrumentation

The OpenTelemetry Android Agent provides automatic instrumentation for common Android application components like activities, fragments, crashes, and rendering performance.

​
Enabling All Instrumentations

To enable all OpenTelemetry automatic instrumentations by default,include these dependencies: 
dependencies {
    implementation("io.opentelemetry.android:android-agent:0.11.0")
    implementation("io.honeycomb.android:honeycomb-opentelemetry-android:0.0.9")
}

​
Enabling Individual Instrumentations

To be more selective, add only the modules you need:
FeatureDependency
Activity navigationio.opentelemetry.android:instrumentation-activity
Application Not Responding (ANR)io.opentelemetry.android:instrumentation-anr
Crash (uncaught exception)io.opentelemetry.android:instrumentation-crash
Fragment navigationio.opentelemetry.android:instrumentation-fragment
Slow renderingio.opentelemetry.android:instrumentation-slowrendering

​
Verify That Data is Being Sent

Once your application is instrumented, check that telemetry data is reaching Honeycomb:
  1. Confirm that debugging is enabled by setting .setDebug(true) in your SDK configuration.
  2. Build and run your application.
  3. Check your logs for output like this: 
    🐝 Honeycomb SDK Debug Mode Enabled 🐝
Honeycomb options: HoneycombOptions(...)
Not sampling, emitting all spans
  4. Log in to Honeycomb, and open your environment. You should see a new dataset named after your serviceName value.
If you don’t see any data, visit Troubleshooting.

​
Explore Your Data

Take a look at the data that you have generated using automatic instrumentation through the Android Launchpad or a custom Board.

​
Explore with the Android Launchpad

If you’re using Honeycomb for Frontend Observability, the Android Launchpad provides a starting point for reviewing the telemetry from your Android application. The Launchpad helps you:
  • Monitor cold start and resume times
  • Detect app hangs and crashes
  • Identify views with high render times
It’s a great place to start exploring how your application behaves in real-world conditions.

​
Explore using Boards

You can also explore your data by creating a Board from a pre-configured Board template. Our specialized template for mobile Android data includes a curated set of ready-made queries and visualizations based on the fields collected by the Honeycomb OpenTelemetry Android SDK. This template gives you an immediate, actionable view into common mobile metrics, like application start times, cold launches, crashes, and session flows, without needing to build anything from scratch. You can use it as-is or customize it to fit your needs. To learn more, visit Use Board Templates.

​
Troubleshooting

Running into issues? Here are some common problems and ways to fix them.
Still stuck? Check out our Support Knowledge Base or post a question in our Pollinators Community.

​
My dataset isn’t showing up in Honeycomb

Make sure that you:
  • Replaced "YOUR-API-KEY" with a valid Ingest API Key.
  • Gave the key Can create datasets permission.
The Honeycomb OpenTelemetry Android SDK uses the value passed to .setApiKey() to send your telemetry data. This must be set correctly for data to reach Honeycomb.

​
My dataset name looks wrong

Check the value passed to .setServiceName(). This value determines the name of your dataset in Honeycomb. If you leave it blank, the default will be unknown_service, which can make identifying your application harder later on.