Logging & log storage

Cimka records two kinds of logs:

• Automatic logs — captured by the SDK without any code: crashes, network calls, screens, taps, lifecycle events, device audits.
• Trace logs — the messages you send yourself with Cimka.trace.log().

Every log is attached to the session in which it happened, so you can always see it in context.

Log types

Log	How it’s captured	Where to view it
Crash	Automatically, on any uncaught exception	Log Components → Crashes
Network	Automatically, through Cimka.interceptor on your OkHttp client	Log Components → Network
Screen view	Automatically with cimka-xml / cimka-compose, or logScreen()	Log Components → Screen Views
Interaction	Automatically with cimka-xml, or Modifier.cimkaClick in Compose	Log Components → Interactions
Lifecycle	Automatically — app start, foreground, background, Activity/Fragment events	Session → Timeline
Device audit	Automatically, once per launch	Clients → Devices, Analyze → Security Map
Trace	Your code: Cimka.trace.log()	Log Components → Trace Log

Sending trace logs

import com.xhonaldo.cimka.core.Cimka
import com.xhonaldo.cimka.components.trace_logger.CimkaLogLevel

// Simple message (level: info)
Cimka.trace.log("User opened the cart")

// With level, tag and structured data
Cimka.trace.log(
    message = "Payment failed",
    level   = CimkaLogLevel.error,
    tag     = "Checkout",
    extra   = mapOf(
        "orderId" to order.id,
        "provider" to "stripe",
        "httpCode" to 402
    )
)

Levels

Level	Use it for
debug	Detailed information while developing a feature
info	Normal, notable events: “checkout started”, “sync completed”
warn	Something unexpected that the app recovered from: retries, fallbacks, slow responses
error	A failure the user noticed: a payment failed, data couldn’t be loaded

error logs count as problems in a session and towards the Trace Errors card on the Overview.

Best practices

• Use tags for the feature or module (Checkout, Auth, Sync) — you can filter and chart by tag.
• Keep messages constant and put variable values in extra. “Payment failed” + extra["orderId"] groups well in statistics; “Payment 4812 failed” doesn’t.
• Log decisions, not noise. A log per state change is useful; a log per frame or per list item is not.
• Never log secrets or personal data — passwords, tokens, card numbers, full names. Masking is a safety net, not a substitute.
• Identify the user with Cimka.identify(userId) after login, so you can find a user’s logs by their id.

How logs are delivered and stored

1. On the device — the SDK sends each log in the background, without blocking your UI.
2. If the device is offline — with the cimka-offline module, crash, trace, screen and network logs are saved to a private file in your app’s storage (up to 2 MB per log type; the oldest half is dropped when full) and sent on the next app launch.
3. In transit — every request goes over HTTPS and is signed, so it can’t be forged or replayed.
4. On arrival — masked properties are replaced with [MASKED] before the log is stored. Crashes are grouped into issues; everything is linked to its session, device, user and app version.
5. In the dashboard — logs are available immediately to members of your organization whose role allows it.

Tip

Add cimka-offline to every production app. Crashes often happen on bad networks — without the offline queue, a crash report that can’t be sent is lost.

Logs are stored per organization and are only visible to members of that organization. Who can see them is controlled by roles — for example, the Finance role cannot see logs at all.

Protecting sensitive data

Layer	What it does
Masked properties	Header names and JSON keys you list in Settings (plus defaults like password, token, card_number) are replaced with [MASKED] in network logs, trace logs and crash reports
Built-in filters	Authorization headers, cookies and Bearer … / password=… patterns are always masked
Input masking	Text typed into EditText fields is never captured in tap logs
Per-view opt-out	Exclude sensitive views from tap tracking with the cimka_mask tag
Log type switches	Turn any log type off per app in App Config — no app update needed

See Data & privacy for the complete list of collected data.

Viewing and searching logs

• By type — the pages under Log Components.
• By user, platform or text — the filter bar on every log page.
• By time — the time range picker in the header.
• In context — open a session’s Timeline to see every log in order, with network calls and screens around it.
• As statistics — Statistics → Trace Stats shows logs by level, top tags and top messages over time.

Exporting logs

• Reports → Reports → Developer category: crashes, network errors, slow APIs and problematic sessions as Excel.
• Reports → Custom Reports: build your own export over trace logs, crashes, network logs and more, with filters and joins — see Reports.

Turning logs off

Open Operations → App Config, select the app, and switch off any log type — or the whole SDK with SDK Enabled. Devices apply the change on the next foreground or within 2 minutes.