Android - Send Traces, Logs, and Metrics with OpenTelemetry

Overview

The OpenTelemetry Android agent instruments your app and sends traces, logs, and metrics to SigNoz. You configure one endpoint, and all three signals use it.

Once the agent starts, it collects these on its own:

• Spans for activity and fragment lifecycle events.
• Events on the logs signal for crashes, ANRs, network changes, slow frames, and session starts.

You then add your own telemetry through the OpenTelemetry API. Records that your app emits inside a span arrive with a trace ID and a span ID already set. SigNoz links each of those log lines to the trace that produced it.

Prerequisites

• An Android app that builds with Android Gradle Plugin (AGP) 9.1.0 or later.
• compileSdk 37 or later. The agent depends on androidx.core:core:1.19.0, which requires both this AGP version and this SDK level.
• An instance of SigNoz (either Cloud or Self-Hosted)

sdkmanager --channel=3 --install "platforms;android-37.0" "build-tools;37.0.0"

Set up the agent

Step 1: Add the dependencies

Add the Byte Buddy plugin to your root build file. Byte Buddy rewrites bytecode at build time, and the android-log instrumentation in the Logs section needs it.

AGP 9 includes Kotlin support, so do not apply the org.jetbrains.kotlin.android plugin. AGP 9.4.1 ships Kotlin 2.2.0, but the agent needs 2.4.10, so pin the Kotlin Gradle plugin on the buildscript classpath:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.4.10")
    }
}
 
plugins {
    id("com.android.application") version "9.4.1" apply false
    id("net.bytebuddy.byte-buddy-gradle-plugin") version "1.18.14" apply false
}

Apply both plugins in your module build file and add the agent:

plugins {
    id("com.android.application")
    id("net.bytebuddy.byte-buddy-gradle-plugin")
}
 
dependencies {
    implementation(platform("io.opentelemetry.android:opentelemetry-android-bom:1.7.0-alpha"))
    implementation("io.opentelemetry.android:android-agent")
}

The bill of materials (BOM) sets the version for every other OpenTelemetry Android dependency, so you omit versions elsewhere.

dependencies {
    implementation("io.opentelemetry.android:core")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")
}

If your minSdk is below 26, turn on core library desugaring in the same file. Desugaring lets an older Android version run newer Java APIs:

android {
    compileSdk = 37
 
    defaultConfig {
        minSdk = 23
    }
 
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}
 
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

The agent also needs this property so that desugaring runs correctly below API 26:

android.useFullClasspathForDexingTransform=true

Step 2: Start the agent

Create an Application class and start the agent in onCreate(), as early as you can after super.onCreate().

package com.example.shop
 
import android.app.Application
import io.opentelemetry.android.OpenTelemetryRum
import io.opentelemetry.android.agent.OpenTelemetryRumInitializer
 
class ShopApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        rum = OpenTelemetryRumInitializer.initialize(
            context = this,
            configuration = {
                httpExport {
                    baseUrl = "https://ingest.<region>.signoz.cloud:443"
                    baseHeaders = mapOf("signoz-ingestion-key" to "<your-ingestion-key>")
                }
                resource {
                    put("service.name", "<service_name>")
                    put("service.version", "<service_version>")
                }
            },
        )
    }
 
    companion object {
        var rum: OpenTelemetryRum? = null
    }
}

package com.example.shop;
 
import android.app.Application;
 
import io.opentelemetry.android.AndroidResource;
import io.opentelemetry.android.OpenTelemetryRum;
import io.opentelemetry.android.RumBuilder;
import io.opentelemetry.exporter.otlp.http.logs.OtlpHttpLogRecordExporter;
import io.opentelemetry.exporter.otlp.http.metrics.OtlpHttpMetricExporter;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.sdk.resources.Resource;
 
public class ShopApplication extends Application {
 
    public static OpenTelemetryRum rum;
 
    private static final String BASE_URL = "https://ingest.<region>.signoz.cloud:443";
    private static final String KEY = "<your-ingestion-key>";
 
    @Override
    public void onCreate() {
        super.onCreate();
 
        Resource resource = AndroidResource.createDefault(this).toBuilder()
                .put("service.name", "<service_name>")
                .put("service.version", "<service_version>")
                .build();
 
        rum = RumBuilder.builder(this)
                .setResource(resource)
                .addSpanExporterCustomizer(prev -> OtlpHttpSpanExporter.builder()
                        .setEndpoint(BASE_URL + "/v1/traces")
                        .addHeader("signoz-ingestion-key", KEY)
                        .build())
                .addLogRecordExporterCustomizer(prev -> OtlpHttpLogRecordExporter.builder()
                        .setEndpoint(BASE_URL + "/v1/logs")
                        .addHeader("signoz-ingestion-key", KEY)
                        .build())
                .addMetricExporterCustomizer(prev -> OtlpHttpMetricExporter.builder()
                        .setEndpoint(BASE_URL + "/v1/metrics")
                        .addHeader("signoz-ingestion-key", KEY)
                        .build())
                .build();
    }
}

Verify these values:

• <region>: Your SigNoz Cloud region.
• <your-ingestion-key>: Your SigNoz ingestion key.
• <service_name>: The name of your app in SigNoz, for example android-otel-demo. If you omit the resource attributes, the agent uses your app label, which can contain spaces.
• <service_version>: Your release version, for example 2.4.0. SigNoz records a deployment every time this value changes.

In the Kotlin form, set baseUrl to the host and port only. The agent appends /v1/traces, /v1/logs, and /v1/metrics itself. A baseUrl that already ends in a signal path produces a 404. The Java form sets each full URL, as shown above.

Register the class in your manifest and grant internet access:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
 
    <application android:name=".ShopApplication">
        <!-- your activities -->
    </application>
</manifest>

Build and run the app. The agent reports on its own from here, and you add your own telemetry with the OpenTelemetry API.

Traces

The agent creates spans for activity and fragment lifecycle events without any code from you. An app launch produces an AppStart span with Created, Paused, and Stopped spans under it.

HTTP client spans are not part of the agent. To trace OkHttp or HttpURLConnection calls, and to propagate trace context to your backend, add the matching instrumentation:

dependencies {
    implementation("io.opentelemetry.android.instrumentation:okhttp3-library")
    byteBuddy("io.opentelemetry.android.instrumentation:okhttp3-agent:1.7.0-alpha")
}

To time your own work, get a tracer from the agent and create spans:

val tracer = ShopApplication.rum!!.openTelemetry.getTracer("com.example.shop.checkout")
 
val parent = tracer.spanBuilder("checkout").startSpan()
try {
    parent.makeCurrent().use {
        val child = tracer.spanBuilder("authorize-payment").startSpan()
        try {
            child.makeCurrent().use {
                child.setAttribute("payment.method", "card")
            }
        } finally {
            child.end()
        }
    }
} finally {
    parent.end()
}

Any log record emitted while a span is current carries that span's trace ID and span ID.

Logs

Capture existing android.util.Log calls

The android-log instrumentation rewrites every android.util.Log call in your app into an OpenTelemetry log record. Add both artifacts to your module build file:

dependencies {
    implementation("io.opentelemetry.android.instrumentation:android-log-library")
    byteBuddy("io.opentelemetry.android.instrumentation:android-log-agent:1.7.0-alpha")
}

The byteBuddy line must carry an explicit version. The BOM constrains the implementation configuration only. Without a version the build fails with Could not find io.opentelemetry.android.instrumentation:android-log-agent:. and an empty version after the colon.

You write no other code. Your existing calls now produce records:

Log.i("PaymentGateway", "initiating payment intent pi_3Q8xR2")
Log.e("PaymentGateway", "payment authorization failed", exception)

Each record carries the log tag as the android.log.tag attribute. The overloads that accept a Throwable also set exception.type and exception.stacktrace. The severity maps as follows:

Send your own log records

Use the OpenTelemetry logs API when you want a record with your own body and attributes:

ShopApplication.rum
    ?.openTelemetry
    ?.logsBridge
    ?.loggerBuilder("com.example.shop.checkout")
    ?.build()
    ?.logRecordBuilder()
    ?.setSeverity(Severity.INFO)
    ?.setBody("order placed")
    ?.setAttribute(stringKey("order.id"), "ord_7742")
    ?.setAttribute(longKey("cart.item_count"), 3)
    ?.emit()

The string you pass to loggerBuilder becomes the scope name in SigNoz. Use it to separate your own records from the ones the agent produces.

Metrics

The agent exports metrics every 60 seconds, but no bundled instrumentation records any. Your app produces every metric it sends:

val meter = ShopApplication.rum!!.openTelemetry.meterProvider.get("com.example.shop.checkout")
 
val orders = meter.counterBuilder("shop.orders.placed")
    .setDescription("Orders placed from the Android app")
    .setUnit("{order}")
    .build()
orders.add(1, Attributes.of(stringKey("payment.method"), "card"))
 
val duration = meter.histogramBuilder("shop.checkout.duration")
    .setUnit("s")
    .build()
duration.record(0.842, Attributes.of(stringKey("checkout.step"), "payment"))

SigNoz stores a histogram as several metrics. shop.checkout.duration arrives as shop.checkout.duration.bucket, .count, .min, .max, and .sum.

Validate

Give the app a minute after launch. The Kotlin DSL buffers telemetry on disk by default and reads a buffer file only after it is about 33 seconds old. Metrics wait for the 60 second export interval.

Filter on your service in each explorer, for example service.name = 'android-otel-demo'.

Open Traces Explorer and open a trace.

Open Logs Explorer, then open one record to see the attributes the agent adds for you.

Open Metrics and search for the metric you recorded.

adb logcat -s HttpExporter:W

dexdump -d app/build/outputs/apk/debug/app-debug.apk | grep -F -c 'AndroidLogSubstitutions;.substitutionFor'

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>

<application
    android:name=".ShopApplication"
    android:networkSecurityConfig="@xml/network_security_config">

adb logcat | grep "Failed to export"

httpExport {
    baseUrl = "http://<collector-host>:4318"
}

Limitations

These apply to version 1.7.0-alpha of the agent.

• No bundled instrumentation records a metric. Every metric comes from your own code.
• Disk buffering writes to the cache directory of the app. Android can delete that directory at any time, so buffered telemetry can be lost before it is exported.
• The android-log instrumentation covers android.util.Log only. It does not cover Timber, println, or other logging libraries. Route those through the OpenTelemetry logs API.

Next steps

• Run the finished sample app for Kotlin or Java to see the whole setup working before you change your own app.
• Open a slow screen in the Trace Explorer and read its logs from the same trace, which the agent links for you.
• Set up alerts on checkout latency, crash volume, or the error logs this page produces.
• Build a dashboard for the metrics your app records, such as order counts and checkout duration.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.