Initialization and options

Open in ChatGPTOpen in Claude

Initialization

The initialize method bootstraps the Coralogix RUM SDK and should be called once — typically in your Application.onCreate() method.

Parameter	Type	Description
application	Application	Your app’s Application instance. Used for context and lifecycle management.
options	CoralogixOptions	Configuration object defining SDK behavior, network endpoints, and instrumentation preferences.
framework	Framework	Indicates the current runtime, to control hybrid bridge behavior (internal use only, setting this parameter would cause undefined behavior, use default value only - Framework.Android).

Note

Calling initialize() multiple times will be ignored after the first successful initialization.

Example:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        val options = CoralogixOptions(
            applicationName = "MyApp",
            coralogixDomain = CoralogixDomain.EU1,
            publicKey = "<YOUR_PUBLIC_KEY>",
            environment = "production",
            version = BuildConfig.VERSION_NAME,
            sessionSampleRate = 100,
            labels = mapOf("platform" to "android", "someKey" to 3.14),
            instrumentations = mapOf(
                Instrumentation.Error to false,
                Instrumentation.Network to false
            )
        )

        CoralogixRum.initialize(this, options)
    }
}

Check initialization:

if (CoralogixRum.isInitialized()) {
    Log.d("TAG", "Coralogix SDK is initialized.")
}

CoralogixOptions

The CoralogixOptions class defines all configuration settings for the SDK.

data class CoralogixOptions(
    val applicationName: String,
    val coralogixDomain: CoralogixDomain,
    val publicKey: String,
    val labels: Map<String, Any?> = mapOf(),
    val environment: String = "",
    val version: String = "",
    val userContext: UserContext = UserContext(),
    val viewContext: ViewContext = ViewContext(),
    val instrumentations: Map<Instrumentation, Boolean> = mapOf(),
    val mobileVitalsOptions: Map<MobileVitalType, Boolean> = mapOf(),
    val ignoreUrls: List<String> = listOf(),
    val ignoreErrors: List<String> = listOf(),
    val collectIPData: Boolean = true,
    val sessionSampleRate: Int = 100,
    val excludeFromSampling: List<ExcludableInstrumentation> = emptyList(),
    val traceParentInHeader: TraceParentInHeaderConfig = TraceParentInHeaderConfig(),
    val debug: Boolean = false,
    val proxyUrl: String? = null,
    val beforeSend: ((EditableCxRum) -> EditableCxRum?)? = null,
    val beforeSendCallback: ((List<Map<String, Any?>>) -> Unit)? = null,
    val userInteractionOptions: UserInteractionOptions = UserInteractionOptions(),
    val networkCaptureConfig: List<NetworkCaptureRule> = emptyList(),
    val tracesExporter: ((CoralogixTraceExporterData) -> Unit)? = null,
    val urlMasking: UrlMaskingOptions = UrlMaskingOptions()
)

Key fields

Field	Type	Description
applicationName	String	The display name of your app, used in dashboards.
coralogixDomain	CoralogixDomain	Target Coralogix ingestion domain (see below).
publicKey	String	The public key used for authentication with Coralogix.
labels	Map<String, Any?>	Global labels added to every event.
environment	String	Environment name (dev, staging, prod, etc.).
version	String	Application version.
userContext	UserContext	Default user context for the session.
viewContext	ViewContext	Default view context for the session.
instrumentations	Map<Instrumentation, Boolean>	Can be used to disable SDK features (logs, errors, ANR, etc.).
mobileVitalsOptions	Map<MobileVitalType, Boolean>	Can be used to disable mobile vitals detectors (fps, cpu, etc.).
ignoreUrls	List<String>	URL substrings (or regex) the SDK leaves alone entirely — no network event and no traceparent header.
ignoreErrors	List<String>	Exception messages (or regex) to exclude from reporting.
collectIPData	Boolean	Whether to enrich outgoing events with user IP metadata.
sessionSampleRate	Int	Sampling rate (0–100%) to control data volume.
excludeFromSampling	List<ExcludableInstrumentation>	Instrumentation categories always exported regardless of sessionSampleRate. See Decoupling session sampling.
traceParentInHeader	TraceParentInHeaderConfig	Controls W3C traceparent header injection in network requests. Requires the network instrumentation to stay enabled.
debug	Boolean	Enables verbose SDK logs.
proxyUrl	String?	Optional proxy endpoint for data routing (see below).
beforeSend	(EditableCxRum) -> EditableCxRum?	Intercepts and modifies each event before sending (optional).
beforeSendCallback	(List<Map<String, Any?>>) -> Unit	Callback for hybrid frameworks, does nothing on native.
userInteractionOptions	UserInteractionOptions	Configuration for user-interaction instrumentation (optional).
networkCaptureConfig	List<NetworkCaptureRule>	Rules to capture request/response headers and payloads (optional).
tracesExporter	(CoralogixTraceExporterData) -> Unit	Optional callback that receives raw OTLP span data, enabling distributed-tracing integration. It runs before beforeSend, so your beforeSend redaction does not apply to it. See Receiving raw OTLP span data.
urlMasking	UrlMaskingOptions	Adds to the URL parameters the SDK masks, or changes how it masks them. Masking is always on. See URL masking.

CoralogixDomain

Defines the target Coralogix ingestion endpoint. The regional domains available to customer applications are:

Domain	Constant	URL
EU1	CoralogixDomain.EU1	https://ingress.eu1.rum-ingress-coralogix.com
EU2	CoralogixDomain.EU2	https://ingress.eu2.rum-ingress-coralogix.com
US1	CoralogixDomain.US1	https://ingress.us1.rum-ingress-coralogix.com
US2	CoralogixDomain.US2	https://ingress.us2.rum-ingress-coralogix.com
US3	CoralogixDomain.US3	https://ingress.us3.rum-ingress-coralogix.com
AP1	CoralogixDomain.AP1	https://ingress.ap1.rum-ingress-coralogix.com
AP2	CoralogixDomain.AP2	https://ingress.ap2.rum-ingress-coralogix.com
AP3	CoralogixDomain.AP3	https://ingress.ap3.rum-ingress-coralogix.com

Tip

Choose the domain corresponding to your Coralogix account region to minimize latency.

UserContext

Defines information about the current user.

data class UserContext(
    val userId: String = "",
    val username: String = "",
    val email: String = "",
    val metadata: Map<String, String> = mapOf(),
    val accountId: String? = null,
    val accountName: String? = null
)

Field	Description
userId	Unique identifier of the user.
username	Display name of the user.
email	User’s email address.
metadata	Custom user attributes for analytics segmentation.
accountId	Optional. Identifier of the account the user belongs to.
accountName	Optional. Display name of the account the user belongs to.

ViewContext

Describes the currently visible app screen.

data class ViewContext(
    val viewName: String = "",
    val activityName: String = "",
    val fragmentName: String = ""
)

Field	Description
viewName	Logical name of the current screen.
activityName	Host activity class name.
fragmentName	Active fragment class name.

Decoupling session sampling

sessionSampleRate decides what is reported, not whether the SDK runs. The SDK always initializes, so a sampled-out session still adds the traceparent header to outgoing requests and your traces stay correlated; it simply sends nothing else. Use excludeFromSampling to keep specific instrumentation categories flowing at 100 % even when the session is sampled out.

This is useful when you want a low session sample rate (e.g. 10 %) to reduce RUM data volume, but still need every custom log message to reach Coralogix for debugging.

val options = CoralogixOptions(
    applicationName = "MyApp",
    coralogixDomain = CoralogixDomain.EU1,
    publicKey = "<YOUR_PUBLIC_KEY>",
    sessionSampleRate = 10,                              // sample 10 % of sessions
    excludeFromSampling = listOf(
        ExcludableInstrumentation.Logs,                  // always export custom logs
        ExcludableInstrumentation.Errors                 // always export errors
    )
)

ExcludableInstrumentation values

Value	Exported event type	Source API
Errors	error	Automatic crash/exception capture
Logs	log	CoralogixRum.log(...)
Network	network-request	Automatic network instrumentation
UserInteractions	user-interaction	Automatic tap/scroll capture
MobileVitals	mobile-vitals	CPU, memory, FPS metrics
CustomSpan	custom-span	CoralogixRum.getCustomTracer()
CustomMeasurement	custom-measurement	CoralogixRum.sendCustomMeasurement(...)
Navigation	navigation	Automatic navigation event capture
Lifecycle	life-cycle	App foreground/background transitions

Note

Screenshot (session-replay frames) and internal SDK init events are intentionally absent from this list. Internal events from a sampled-out session are sent only when excludeFromSampling lists at least one category; with an empty list, a sampled-out session sends nothing at all, matching the browser SDK. Session-replay frames are governed by the session replay pipeline, which does not record a sampled-out session at all.

The instrumentations map has the final say. excludeFromSampling only relaxes the sampling condition, so it can never switch something back on that you set to false in instrumentations — a category disabled there stays disabled on sampled-in and sampled-out sessions alike. On a sampled-in session the exclude list has no effect at all.

Categories that are neither sampled in nor excluded are not started, so a sampled-out session does no work collecting events it would discard. When such a session later rotates into being sampled in — after 15 minutes of inactivity, after an hour, or when you call createNewSession() — the categories it skipped start then, and reporting resumes in full.

Inside a beforeSend hook, EditableCxRum.isSessionSampledIn tells you whether an event came from a sampled-in session or reached you only via excludeFromSampling, so you can filter excluded categories further (for example, keep only ANRs).

The traceparent sampled flag

The last byte of the traceparent header is the W3C sampled flag. From 2.24.2 it carries the session's sampling decision for that request: 00 when the session is sampled out and excludeFromSampling does not include Network, so the request only propagates trace context, and 01 otherwise. Before 2.24.2 every request carried 01.

The flag reflects sampling alone, so 01 is not a guarantee that the event arrives. These still drop a reported event after the header has gone out, and all of them leave the flag at 01:

• an event your beforeSend callback returns null for
• a request your app sends while the session is idle, which it becomes after 15 minutes without a touch or an activity resuming

Note

In a React Native app with the Coralogix Gradle plugin applied, this SDK injects the header, so the flag behaves as described here. Without the plugin, React Native injects the header from JavaScript, and Flutter always injects it from Dart; in both cases it currently always carries 01.

If your code builds the traceparent header itself instead of letting this SDK inject it, call CoralogixRum.networkRequestSampling() when each request starts and use its isSampled for the flag: 01 for true, 00 for false. Do not cache the answer, because the session can change at any time. isSampled is also false while network instrumentation is switched off and before the SDK is initialized. A request sent then carries 00 and is not reported, so the header and the events still agree. When you report the request with CoralogixRum.reportNetworkRequest, pass isSampled in NetworkRequestDetails.traceparentSampled and sessionId in NetworkRequestDetails.traceparentSessionId. The reported event then matches the flag the request was sent with and belongs to the session the request started in, even if the session changed while it was in flight. These are available from version 2.25.0.

import com.coralogix.android.sdk.CoralogixRum
import com.coralogix.android.sdk.internal.features.instrumentations.network.NetworkRequestDetails

val sampling = CoralogixRum.networkRequestSampling()
val traceparent = "00-$traceId-$spanId-${if (sampling.isSampled) "01" else "00"}"
// Send the request with this traceparent header, then report it:
CoralogixRum.reportNetworkRequest(
    NetworkRequestDetails(
        traceId = traceId,
        spanId = spanId,
        method = "GET",
        url = url,
        statusCode = 200,
        traceparentSampled = sampling.isSampled,
        traceparentSessionId = sampling.sessionId,
    )
)

Instrumentation

Used to control which instrumentation modules are active.

Instrumentation	Constant	Description
Error	Instrumentation.Error	Captures handled and unhandled exceptions and native crashes.
Network	Instrumentation.Network	Reports network requests and responses.
Custom	Instrumentation.Custom	Allows sending custom events or metrics.
MobileVitals	Instrumentation.MobileVitals	Tracks CPU, memory, and FPS.
Anr	Instrumentation.Anr	Detects Application Not Responding (ANR) events.
Lifecycle	Instrumentation.Lifecycle	Observes app foreground/background transitions.
UserInteraction	Instrumentation.UserInteraction	Tracks taps, scrolls, and other interactions.

Note

Instrumentations are enabled by default.

Mobile vital options

Used to control which mobile vitals detectors are active.

Instrumentation	Constant	Description
ColdStartTime	MobileVitalType.ColdStartTime	Measures the app's launch time
WarmStartTime	MobileVitalType.WarmStartTime	Measures how long it takes for the app to return from the background.
CpuUsage	MobileVitalType.CpuUsage	Measures cpu usage.
MemoryUsage	MobileVitalType.MemoryUsage	Measures memory usage.
SlowFrozenFrames	MobileVitalType.SlowFrozenFrames	Detects frames that were slow to render or frozen.
Fps	MobileVitalType.Fps	Measures the application screen refresh rate per second.

Note

Mobile vitals detectors are enabled by default.

Network capture configuration

The networkCaptureConfig option lets you capture request/response headers and payloads for matching network requests. Rules are matched in order — the first match wins.

data class NetworkCaptureRule(
    val url: String? = null,                   // Exact URL match
    val urlPattern: Regex? = null,             // Regex pattern match
    val reqHeaders: List<String>? = null,      // Request headers to capture (allowlist)
    val resHeaders: List<String>? = null,      // Response headers to capture (allowlist)
    val collectReqPayload: Boolean = false,    // Capture request body
    val collectResPayload: Boolean = false     // Capture response body
)

Field	Description
url	Exact URL string to match.
urlPattern	Regex pattern to match against the full request URL.
reqHeaders	Allowlist of request header names to capture. Matching is case-insensitive.
resHeaders	Allowlist of response header names to capture. Matching is case-insensitive.
collectReqPayload	When true, captures the request body if it is text-based and ≤ 1024 characters.
collectResPayload	When true, captures the response body if it is text-based and ≤ 1024 characters.

Example

val options = CoralogixOptions(
    // ... other options ...
    networkCaptureConfig = listOf(
        NetworkCaptureRule(
            urlPattern = Regex(".*api\\.example\\.com.*"),
            reqHeaders = listOf("Accept", "Content-Type"),
            resHeaders = listOf("Content-Type", "X-Request-Id"),
            collectReqPayload = true,
            collectResPayload = true
        )
    )
)

URL matching

Each rule requires either url (exact match) or urlPattern (regex). Rules are evaluated in list order and the first matching rule is applied — subsequent rules are ignored.

Header capture

Header names in reqHeaders/resHeaders are matched case-insensitively against the actual headers sent/received. The captured header keys use the casing from your allowlist, not the casing from the network layer.

Payload capture

Payloads are only captured when:

• collectReqPayload / collectResPayload is true in the matching rule.
• The Content-Type is text-based: application/json, text/*, application/javascript, or application/xml.
• The payload is ≤ 1024 characters. If it exceeds this limit, the payload is dropped entirely (not truncated).

Security considerations

Only headers explicitly listed in reqHeaders/resHeaders are captured; nothing is captured by default and there is no wildcard.

Warning

A header you list is captured exactly as it is sent, with no masking, and that includes credential headers such as Authorization and Cookie. Do not list a header that carries a credential.

EditableCxRum

A mutable representation of an event intercepted via beforeSend.

data class EditableCxRum(
    val eventContext: EventContext? = null,
    val labels: Map<String, Any?>? = null,
    val spanId: String? = null,
    val traceId: String? = null,
    val environment: String? = null,
    val viewContext: ViewContext? = null,
    val isSnapshotEvent: Boolean? = null,
    val errorContext: EditableErrorContext? = null,
    val logContext: LogContext? = null,
    val networkRequestContext: NetworkRequestContext? = null,
    val userContext: UserContext? = null,
    val lifecycleContext: LifecycleContext? = null,
    val customMeasurementContext: CustomMeasurementContext? = null,
    val interactionContext: InteractionContext? = null,
    val isSessionSampledIn: Boolean? = null
)

This class is used in beforeSend hooks to inspect or modify event data before it’s sent to Coralogix.

interactionContext carries isMaskedElement (is_masked_element on the wire, always present) — whether the interaction targeted content that session replay masked. See Privacy and masking for ready-made beforeSend recipes built on it.

isSessionSampledIn is read-only: it reports whether the event's session was sampled in by sessionSampleRate. false means the event is being sent only because its category is listed in excludeFromSampling, or because it is an internal SDK event, which a sampled-out session sends whenever excludeFromSampling is non-empty. Changing it in beforeSend has no effect. Use it to filter excluded categories further — for example, with a low sample rate and ExcludableInstrumentation.Errors excluded, keep only ANRs from sampled-out sessions:

beforeSend = { event ->
    val isError = event.errorContext != null
    when {
        !isError -> event                                   // non-error events pass through
        event.isSessionSampledIn == true -> event           // sampled-in sessions keep all errors
        event.errorContext?.type == "ANR" -> event          // sampled-out: keep only ANRs
        else -> null                                        // drop the rest
    }
}

URL masking

Starting with version 2.27.0, the SDK masks secrets in every URL it reports before the URL is stored on an event: network request URLs, including those reported through reportNetworkRequest, the URLs inside an error's message or a failed request's error message, the script URLs in JavaScript stack frames, and view names, both the initial viewContext and those set through setViewContext. A masked value reads [REDACTED]; the parameter name and the rest of the URL are kept as sent.

By default the SDK masks:

• The value of a query or fragment parameter whose name contains token, secret, password, passwd, passphrase, apikey, signature, credential, jwt, session, sessid, oauth, saml, privatekey, accesskey or nonce.
• The value of a parameter named exactly code, state, codeverifier, assertion, clientassertion, devicecode, usercode, bearer, auth, authorization, authcode, authkey, sig, hmac, key, pass, pwd, otp, oobcode, sid or ticket.
• JWTs anywhere in the URL, the path included.
• Credentials in the URL: https://user:password@host is reported as https://[REDACTED]@host.
• Session ids in the path, such as ;jsessionid=.
• The same parameters percent-encoded inside another parameter's value, such as a return URL.

Names are compared in lowercase with every non-alphanumeric character removed, so api_key, apiKey and API-Key are the same name. For example, https://example.com/callback?code=abc&page=2#access_token=xyz is reported as https://example.com/callback?code=[REDACTED]&page=2#access_token=[REDACTED].

Masking cannot be turned off, and a built-in name cannot be removed. Use urlMasking to add to it:

import com.coralogix.android.sdk.model.UrlMaskingMode
import com.coralogix.android.sdk.model.UrlMaskingOptions

val options = CoralogixOptions(
    // ... other options ...
    urlMasking = UrlMaskingOptions(
        additionalParams = listOf("tenant_id"),
        additionalParamPatterns = listOf(Regex("^customer")),
        mode = UrlMaskingMode.MASK
    )
)

Field	Type	Description
additionalParams	List<String>	More parameter names to mask. Each matches a whole name, compared the same way as the built-in names.
additionalParamPatterns	List<Regex>	Patterns tested against each decoded parameter name. A name any pattern finds is masked.
mode	UrlMaskingMode	MASK (default) masks sensitive values only. MASK_ALL masks every parameter value and keeps the names. DROP_QUERY removes the query and the fragment.

In every mode, JWTs in the path, credentials in the URL and path session ids are masked too.

ignoreUrls and the URL matching in networkCaptureConfig use the original URL, so your existing patterns keep matching. beforeSend, beforeSendCallback and tracesExporter only see the masked URL.

ProxyUrl

Used to configure a proxy endpoint for data routing. It is your responsibility to forward the data to the Coralogix ingestion endpoint. The ingestion endpoint would be available under the cxforward query parameter, for example: https://your.proxy.com/?cxforward=ingestion.url.com

Session sampling

The SDK reports a random subset of sessions, based on your sessionSampleRate configuration. Sessions outside that subset still initialize the SDK and still propagate trace context — they just do not send events. See Decoupling session sampling to keep specific categories flowing at 100 %.

// Example: Report 20% of all sessions
val options = CoralogixOptions(sessionSampleRate = 20)