Android
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
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
Add the Maven Central Repository to your project. Then, add the dependency to your module's build.gradle
.
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 for next steps.
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 | Yes | US1, US2, EU1, EU2, API, AP2, AP3 |
publicKey |
String |
Coralogix token, publicly visible public_key value |
Yes | "my_public_key" |
labels |
Map<String,String> |
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(user_id = "123", user_name = "User", user_email = "[email protected]", user_metadata = mapOf("role" to "Admin")) |
viewContext |
ViewContext |
Description of current activity | No | "MyActivityName" |
instrumentations |
Map<Instrumentation, Boolean> |
Map to turn on/off specific instrumentation. Defaults to all true. | No | instrumentations = mapOf( Instrumentation.Network to false) |
ignoreUrls |
List<String> |
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<String> |
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}}, |
Configuration
Instrumentation
You can enable or disable specific instrumentation features using the instrumentations
map. By default, all instrumentations are enabled.
Example
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.
- Anr - Automatically detects Application Not Responsive (ANR) events.
- MobileVitals – Automatically tracks cold/warm start times and Frame Rate (FPS).
- 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.
-
Ignoring errors and URLs
- Ignore errors: Use
ignoreErrors
to exclude errors matching specific criteria. Supports strings and regular expressions.
- Ignore URLs: Use
ignoreUrls
to exclude URLs matching specific patterns from being traced.
Network interception
To enable RUM to intercept network events, add CoralogixOkHttpInterceptor
to your network client.
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
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<DataModel>
}
val apiService = retrofit.create(ApiService::class.java)
val response = apiService.getData()
println(response.body())
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)
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)
Integration functions
This section lists public functions used to interact with the Coralogix RUM SDK.
Set user context
Provide user context dynamically as user metadata becomes available.
Example
CoralogixRum.setUserContext(
userContext = UserContext(
userId = "123",
username = "User User",
email = "[email protected]",
metadata = mapOf("key" to "value")
)
)
Set labels
Update labels dynamically during runtime.
Example
Initiate custom measurements
Initiate a custom measurement to send numeric data to Coralogix for precise monitoring and analysis.
Example
Set view context
When using the SDK, the ViewContext
will be set to the activity/fragment name by default. Manually update as necessary.
Example
Log messages
Send log messages with customized severity levels.
Example
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 appear in the Coralogix platform with level 5 severity.
Example
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:
Support
Need help?
Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.
Feel free to reach out to us via our in-app chat or by sending us an email to [email protected].