# Android Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Frum%2Fsdk-installation%2Fandroid.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Frum%2Fsdk-installation%2Fandroid.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) This guide shows you how to easily integrate the Coralogix RUM SDK into your native Android apps. Coralogix Android SDK supports Android 7.0+ (API level 24) and above. ## Features[​](#features "Direct link to Features") In addition to capturing errors, including ANRs, this SDK can intercept network calls, send log messages with customized severity levels, report errors, and track your customers' page transitions. ## Installation[​](#installation "Direct link to Installation") 1 . Add the [Maven Central Repository](https://central.sonatype.com/artifact/com.coralogix/android-sdk) to your project. Then, add the dependency to your module's `build.gradle`. ``` dependencies { implementation 'com.coralogix:android-sdk:2.11.0' } ``` 2 . Sync your project. Note If you encounter a dependency that requires Java 8+ APIs, such as enabling core library desugaring to ensure compatibility across Android versions, see [Troubleshooting](#troubleshooting) for next steps. ## Initialization[​](#initialization "Direct link to Initialization") Initialize the Coralogix SDK with the application context. In the initialization snippet, set mandatory fields: `applicationName`, `coralogixDomain`, `publicKey`, `environment`. ``` import com.coralogix.android.sdk.CoralogixRum import com.coralogix.android.sdk.model.CoralogixDomain import com.coralogix.android.sdk.model.CoralogixOptions val config = CoralogixOptions( applicationName = "MyApp", coralogixDomain = CoralogixDomain.EU2, publicKey = "my_public_key", environment = "dev" ) class DemoApplication : Application() { override fun onCreate() { super.onCreate() CoralogixRum.initialize(this, config) } } ``` Refer to the following fields for `CoralogixOptions`. | Property | Type | Description | Required | Example | | --------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `applicationName` | `String` | Name of the application | Yes | `"MyApp"` | | `coralogixDomain` | `CoralogixDomain` | The region associated with your Coralogix [**domain**](https://docs-docusaurus.kinsta.page/user-guides/account-management/account-settings/coralogix-domain/.md) | Yes | `EU1, EU2, US1, US2, US3, AP1, AP2, AP3` | | `publicKey` | `String` | Coralogix token, publicly visible `public_key` value | Yes | `"my_public_key"` | | `labels` | `Map` | An optional set of labels that are added to every span for enrichment purposes | No | `labels = mapOf("payment" to "visa")` | | `environment` | `String` | Specify the environment, such as development, staging, or production | Yes | `"production"` | | `version` | `String` | Version of the application | No | `"v.1.0"` | | `userContext` | `UserContext` | User context information, such as user ID, name, email, and additional metadata | No | `UserContext(userId = "123", username = "User", email = "newUserEmail@example.com", metadata = mapOf("role" to "Admin"))` | | `viewContext` | `ViewContext` | Description of current activity | No | `"MyActivityName"` | | `instrumentations` | `Map` | Map to turn on/off specific instrumentation. Defaults to all true. | No | `instrumentations = mapOf( Instrumentation.Network to false)` | | `ignoreUrls` | `List` | A list of URLs to ignore for logging and monitoring purposes. Supports strings and regular expressions for matching. | No | `ignoreUrls = listOf("https://jsonplaceholder\\.typicode\\.com/.*", ".*\\.svg", ".*\\.ico")` | | `ignoreErrors` | `List` | List of error patterns to be ignored for logging and monitoring. Supports strings and regular expressions for matching. | No | `ignoreErrors = listOf("^IllegalArgumentException$", "IOException", "ANR")` | | `collectIPData` | `Boolean` | Allow the option to send IP address to identify session country. Defaults to `true`. | No | `true` | | `sessionSampleRate` | `Number` | Percentage of overall sessions being tracked. Defaults to 100%. | No | `100%` | | `traceParentInHeader` | `Boolean` | Add trace context propagation in headers across service boundaries. Defaults to `false`. | No | `true` | | `fpsSamplingSeconds` | `Number` | Interval (in seconds) for collecting and logging frame rate data for performance tracking. Defaults to 300 sec. | No | `10` | | `beforeSend` | `lambda function` | Enable event access and modification before sending to Coralogix, supporting content modification, and event discarding. | No | `beforeSend = { event -> if (event.userContext?.user_email?.endsWith("@example.com", ignoreCase = true) == true) {event.copy(userContext = event.userContext?.copy(user_email = "sensetive-info",),)} else {event}},` | | `tracesExporter` | `(CoralogixTraceExporterData) -> Unit` | Optional callback that receives the raw OTLP span payload alongside the standard RUM export, enabling distributed-tracing integration. See [Trace Exporter](#trace-exporter). | No | `tracesExporter = { data -> /* forward OTLP payload */ }` | ## Configuration[​](#configuration "Direct link to Configuration") ### Instrumentation[​](#instrumentation "Direct link to Instrumentation") You can enable or disable specific instrumentation features using the `instrumentations` map. By default, all instrumentations are enabled. **Example** ``` instrumentations = mapOf( Instrumentation.Network to false // Disables network instrumentation ) ``` `Instrumentation` **enum:** * **Error** - Monitors error events. * **Network** - Intercepts network calls and, optionally, propagates trace context in headers across service boundaries. * **Custom** - Allows developers to define and track custom events, giving insights into specific actions or behaviors in the application that are critical to the business. * **MobileVitals** – Collects key app performance metrics, including CPU, memory, FPS, cold start, and warm start events. Learn more in [Mobile Vitals](https://docs-docusaurus.kinsta.page/user-guides/rum/product-features/mobile-performance/.md). * **Anr** - Detects Application Not Responsive (ANR) events. * **UserInteraction** – Automatically tracks user interactions. Currently, only click and long click events are supported. * **Lifecycle** - Captures app lifecycle activity and fragment events that occur during runtime, providing insights into the application's behavior and performance. * Activity lifecycle events: * **onActivityCreated** - Triggered when the activity is first created, initializing the activity and setting up the UI. * **onActivityStarted** - Called when the activity becomes visible to the user, but may not yet be interactive. * **onActivityResumed** - Invoked when the activity enters the `resumed` state, making it fully interactive and allowing user input. * **onActivityPaused** - Called when the activity is partially obscured, such as when another activity or a dialog appears, but the activity is still partially visible. * **onActivityStopped** - Triggered when the activity is no longer visible to the user and enters the `stopped` state. * **onActivitySaveInstanceState** - Called to save the current state of the activity (e.g., UI data, user input) so it can be restored if the activity is restarted. * **onActivityDestroyed** - Called just before the activity is destroyed, allowing for final cleanup of resources and references. * Fragment lifecycle events: * **onFragmentAttached** - Called when the fragment is attached to its host activity. This is the point where the fragment is associated with the activity lifecycle. * **onFragmentCreated** - Called when the fragment is created. This occurs only once per fragment instance, even if it is attached and detached multiple times. * **onFragmentViewCreated** - Called after the fragment’s view is created and fully inflated. At this point, the fragment's UI is ready. * **onFragmentStarted** - Triggered when the fragment enters the `started` phase and becomes visible to the user. * **onFragmentResumed** - Called when the fragment enters the `resumed` phase, meaning the fragment is now interactive and the user can interact with it. * **onFragmentPaused** - Called when the fragment is partially obscured by another UI element (e.g., another activity, dialog box), but still visible. * **onFragmentStopped** - Called when the fragment is no longer visible to the user and has entered the `stopped` state. * **onFragmentSaveInstanceState** - Called to save the fragment's state (e.g., UI data, input) when the system needs to save its state (during pauses, backgrounding, or configuration changes), so it can be restored later. * **onFragmentViewDestroyed** - Called when the fragment’s view is destroyed and is no longer available, typically when the fragment is removed or replaced. * **onFragmentDestroyed** - Called when the fragment instance is fully destroyed, releasing any remaining resources. * **onFragmentDetached** - Called when the fragment is detached from its host activity, ending the association between the fragment and its host. ### Mobile Vitals[​](#mobile-vitals "Direct link to Mobile Vitals") Set which Mobile Vitals you want to track on Android. By default, all detectors are enabled. You can selectively enable or disable specific detectors (for example, CPU or memory) using the `mobileVitalsOptions` map in your CoralogixOptions configuration. ``` val config = CoralogixOptions( // ... mobileVitalsOptions = mapOf( MobileVitalType.CpuUsage to true, MobileVitalType.MemoryUsage to false // disables memory detector ) ) ``` You can configure the following Mobile Vital detectors: | Detector key | Description | | ---------------------------------- | ------------------------------------ | | `MobileVitalType.CpuUsage` | CPU utilization and main-thread time | | `MobileVitalType.MemoryUsage` | Memory footprint and utilization | | `MobileVitalType.Fps` | Frame rate (FPS) | | `MobileVitalType.ColdStartTime` | App cold start duration | | `MobileVitalType.WarmStartTime` | App warm start duration | | `MobileVitalType.SlowFrozenFrames` | Slow and frozen frame counts | Learn more about metric coverage and visualization in [Mobile Vitals](https://docs-docusaurus.kinsta.page/user-guides/rum/product-features/mobile-performance/.md). ### Ignoring errors and URLs[​](#ignoring-errors-and-urls "Direct link to Ignoring errors and URLs") * **Ignore errors:** Use `ignoreErrors` to exclude errors matching specific criteria. Supports strings and regular expressions. ``` "^IllegalArgumentException$", "IOException", "ANR" ``` * **Ignore URLs:** Use `ignoreUrls` to exclude URLs matching specific patterns from being traced. ``` "\\\\.typicode\\\\.com/.*", ".*\\\\.svg", ".*\\\\.ico", ``` ### Network interception[​](#network-interception "Direct link to Network interception") To enable RUM to intercept network events, add `CoralogixOkHttpInterceptor` to your network client. #### OkHttp[​](#okhttp "Direct link to OkHttp") ``` val okHttpClient = OkHttpClient.Builder() .addInterceptor(CoralogixOkHttpInterceptor()) .build() val request = Request.Builder() .url("https://api.example.com/data") .build() val response = okHttpClient.newCall(request).execute() println(response.body?.string()) ``` #### Retrofit[​](#retrofit "Direct link to Retrofit") ``` val okHttpClient = OkHttpClient.Builder() .addInterceptor(CoralogixOkHttpInterceptor()) .build() val retrofit = Retrofit.Builder() .baseUrl("https://api.example.com/") .client(okHttpClient) .addConverterFactory(GsonConverterFactory.create()) .build() interface ApiService { @GET("data") suspend fun getData(): Response } val apiService = retrofit.create(ApiService::class.java) val response = apiService.getData() println(response.body()) ``` #### Ktor[​](#ktor "Direct link to Ktor") Note Only OkHttp engine is supported. ``` val httpClient = HttpClient(OkHttp) { engine { preconfigured = OkHttpClient.Builder() .addInterceptor(CoralogixOkHttpInterceptor()) .build() } } val response = httpClient.get("https://api.example.com/data") println(response.bodyAsText()) ``` #### Glide (image loading)[​](#glide-image-loading "Direct link to Glide (image loading)") ``` val okHttpClient = OkHttpClient.Builder() .addInterceptor(CoralogixOkHttpInterceptor()) .build() val glide = Glide.get(context) glide.registry.replace( GlideUrl::class.java, InputStream::class.java, OkHttpUrlLoader.Factory(okHttpClient) ) Glide.with(context) .load("https://api.example.com/image.png") .into(imageView) ``` ### Network capture rules[​](#network-capture-rules "Direct link to Network capture rules") By default, the SDK captures request URLs, status codes, and timings via `CoralogixOkHttpInterceptor`. Use `networkCaptureConfig` in `CoralogixOptions` to capture specific request and response headers or payloads on a per-URL basis. ``` val config = CoralogixOptions( // ... networkCaptureConfig = listOf( NetworkCaptureRule( urlPattern = "https://api.example.com/.*", reqHeaders = listOf("X-Request-Id"), resHeaders = listOf("X-Response-Time"), collectReqPayload = true, collectResPayload = false ) ) ) ``` | `NetworkCaptureRule` field | Description | | -------------------------- | ------------------------------------------------------------ | | `urlPattern` | Regex pattern that matches request URLs the rule applies to. | | `reqHeaders` | List of request header names to capture. | | `resHeaders` | List of response header names to capture. | | `collectReqPayload` | When `true`, capture the request body. | | `collectResPayload` | When `true`, capture the response body. | ### Trace exporter[​](#trace-exporter "Direct link to Trace exporter") Forward span data to your own collector or backend by setting a trace exporter callback. The callback receives each span batch the SDK produces. Spans continue to flow to Coralogix when this callback is set. ``` val config = CoralogixOptions( // ... tracesExporter = { spanData -> forwardToCustomCollector(spanData) } ) ``` ### Modify events with beforeSend[​](#modify-events-with-beforesend "Direct link to Modify events with beforeSend") Use `beforeSend` to inspect, transform, or discard events before they reach Coralogix. ``` val config = CoralogixOptions( // ... beforeSend = { event -> if (event.userContext?.email?.endsWith("@coralogix.com", ignoreCase = true) == true) { event.copy(userContext = event.userContext?.copy(email = "redacted")) } else { event } } ) ``` ## Custom Spans[​](#custom-spans "Direct link to Custom Spans") Use Custom Spans to instrument business-critical operations in your Android app. Spans appear in Coralogix as standalone records or grouped under a parent global span. Custom Spans require SDK version 2.11.0 or above. ### Get the tracer[​](#get-the-tracer "Direct link to Get the tracer") Acquire a tracer from `CoralogixRum`. Optionally scope which auto-instruments are ignored within the span context: ``` val tracer = CoralogixRum.getCustomTracer( listOf(CoralogixIgnoredInstrument.NETWORK_REQUESTS) ) ``` ### Start a global span[​](#start-a-global-span "Direct link to Start a global span") A global span is a top-level operation: ``` val global = tracer.startGlobalSpan( name = "checkout-flow", labels = mapOf("cartSize" to 3, "currency" to "USD") ) ``` ### Add child spans[​](#add-child-spans "Direct link to Add child spans") Within a global span's context, create child spans for sub-operations: ``` val child = global.startCustomSpan("fetch-prices") child.setAttribute("endpoint", "/api/v1/prices") // ... do work ... child.endSpan() global.endSpan() ``` ## Integration functions[​](#integration-functions "Direct link to Integration functions") This section lists public functions used to interact with the Coralogix RUM SDK. ### Set user context[​](#set-user-context "Direct link to Set user context") Provide user context dynamically as user metadata becomes available. **Example** ``` CoralogixRum.setUserContext( userContext = UserContext( userId = "123", username = "User User", email = "user@example.com", metadata = mapOf("key" to "value") ) ) ``` ### Set labels[​](#set-labels "Direct link to Set labels") Update labels dynamically during runtime. **Example** ``` CoralogixRum.setLabels( labels = mapOf( "environment" to "production", "version" to "1.0.2" ) ) ``` ### Initiate custom measurements[​](#initiate-custom-measurements "Direct link to Initiate custom measurements") Initiate a custom measurement to send numeric data to Coralogix for precise monitoring and analysis. **Example** ``` CoralogixRum.sendCustomMeasurement("my-measurement", 1000) ``` ### Set view context[​](#set-view-context "Direct link to Set view context") When using the SDK, the `ViewContext` will be set to the activity/fragment name by default. Manually update as necessary. **Example** ``` CoralogixRum.setViewContext( viewName = "CustomViewName" ) ``` ### Log messages[​](#log-messages "Direct link to Log messages") Send log messages with customized severity levels. **Example** ``` CoralogixRum.log( CoralogixLogSeverity.Error, "Custom log message error" ) ``` `CoralogixLogSeverity` defines severity levels for logs in the Coralogix system. | Case | Raw Value | Severity Level | | ---------- | --------- | -------------- | | `Debug` | 1 | Debug | | `Verbose` | 2 | Verbose | | `Info` | 3 | Informational | | `Warn` | 4 | Warning | | `Error` | 5 | Error | | `Critical` | 6 | Critical | ### Report errors[​](#report-errors "Direct link to Report errors") Report errors appear in the Coralogix platform with level 5 severity. **Example** ``` try { // code that might throw an error } catch (t: Throwable) { CoralogixRum.reportError(t) } ``` ### Custom spans[​](#custom-spans-1 "Direct link to Custom spans") Instrument your own code with arbitrary OpenTelemetry spans that appear in the Coralogix RUM trace view. While a global span is active, all auto-instrumented spans (network, error, user-interaction) inherit its `traceId` and carry `parentSpanId`, so they appear as children in the same trace. Note `getCustomTracer()` requires `traceParentInHeader` to be enabled in `CoralogixOptions`. The tracer can only be obtained once per session. **Example** ``` val tracer = CoralogixRum.getCustomTracer() ?: return val globalSpan = tracer.startGlobalSpan( name = "checkout-flow", labels = mapOf("cart.item_count" to 3) ) ?: return val childSpan = globalSpan.startCustomSpan(name = "payment-step") childSpan.setAttribute("payment.method", "credit_card") // ... do work ... childSpan.endSpan() globalSpan.endSpan() ``` #### Opt out auto-instrumented spans[​](#opt-out-auto-instrumented-spans "Direct link to Opt out auto-instrumented spans") To exclude specific auto-instrumented events from the active global span, pass `CoralogixIgnoredInstrument` values when acquiring the tracer. ``` val tracer = CoralogixRum.getCustomTracer( ignoredInstruments = setOf(CoralogixIgnoredInstrument.NETWORK_REQUESTS) ) ``` Network requests are then captured as standalone RUM events without a `parentSpanId`. For details about prerequisites, use cases, and limitations, see [Custom Spans](https://docs-docusaurus.kinsta.page/user-guides/rum/sdk-features/custom-spans/.md). ### Trace Exporter[​](#trace-exporter-1 "Direct link to Trace Exporter") Set the `tracesExporter` callback in `CoralogixOptions` to receive each OTel span as a raw OTLP payload alongside the normal RUM export. Use this to forward spans to your own distributed-tracing pipeline without running a separate OpenTelemetry collector. ``` val options = CoralogixOptions( // ... tracesExporter = { data -> // data is a CoralogixTraceExporterData OTLP payload // forward to your backend or OTLP-compatible endpoint } ) ``` For payload format and forwarding considerations, see [Trace Exporter](https://docs-docusaurus.kinsta.page/user-guides/rum/sdk-features/trace-exporter/.md). ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") If you encounter a dependency that requires Java 8+ APIs, such as enabling core library desugaring to ensure compatibility across Android versions, do the following: 1 . Update `compileOptions` by adding the following to your `build.gradle` file. ``` android { compileOptions { **isCoreLibraryDesugaringEnabled = true** } } ``` 2 . Add Desugaring Dependency by including the library in your dependencies. ``` dependencies { coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4") } ``` This enables modern Java features on older Android versions.