Skip to content

Telemetry

Telemetry is what the SDK reports while it runs: its log, one entry per step it takes, and the input it captures. On the staging and test packages your app receives both: the log through onLog, and the captured input through an integration of your own. Your code decides where they go; the SDK sends neither to DEA.

Staging and test packages only. The production package writes no log and sets up none of your integrations, so nothing on this page reaches an app you release. The one integration that production sets up is the stream delivery of DEA's collection transporter — see Collect Data.

When to use it

  • Watch what the SDK does while you integrate, in your own log screen or logging service
  • Record the raw input of test sessions for your own QA or analysis

Prerequisites

  • The staging package is installed: ai.dea:dea-sdk:0.26.0 from https://sdk.dep-protocol.com/0.26.0/staging/android, with the content filter shown in Collect Data. The test package, from https://sdk.dep-protocol.com/0.26.0/test/android, works the same way and also logs DEBUG
  • Where requireConsent is true, the default, your testers agreed — see User Consent. Nothing is captured before they do

Usage

Receive the log

Pass onLog in the DeaConfig. The SDK calls it with every entry, and still writes each entry to Logcat under the tag dea.

import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk

DeaSdk.init(
    this,
    DeaConfig(
        appId = "YOUR_APP_ID",
        appKey = "YOUR_APP_KEY",
        onLog = { entry -> myLogger.log(entry.levelText, entry.spec.name, entry.attributes) },
    ),
)

myLogger stands for your own code. The SDK can call onLog on any thread, and ignores an exception it throws. Each entry is a LogEntry, from ai.dea.base.log:

Member Type Description
timestamp Long When the step happened, in milliseconds since the epoch
levelText String DEBUG, INFO, WARN or ERROR
severityNumber Int The OpenTelemetry number of that level: 5, 9, 13 or 17
spec.name String The step, for example sdk.ready or proof.not_signed
outcome String ok, refused or failed
body String One sentence that describes the step
session String The session id when the step happened, none before a session exists
attributes Map<String, Any?> The step's values, for example dea.reason
resource LogResource? The SDK release (serviceVersion), the platform (osType, android) and the package (flavor, staging or test)
line String The entry as Logcat shows it

entry.toJson() returns the entry as a map with OpenTelemetry field names: timestamp in ISO 8601, severityText, severityNumber, eventName, body, attributes (with session.id and dea.outcome first) and resource.

Android has no option to change the level. The staging package logs INFO, WARN and ERROR; the test package also logs DEBUG. To show less, filter on levelText in onLog; Logcat still receives every entry. On the test package, debug also logs a capture.input entry for every captured object. See onLog in Options.

Receive the captured input

An integration is a class that implements Integration, from ai.dea.base: a name and a setup function. The SDK calls setup once, during DeaSdk.init, with attach. Each Transporter you attach receives every object the SDK captures, through its transport method.

import ai.dea.base.Detach
import ai.dea.base.Integration
import ai.dea.base.SchemaObject
import ai.dea.base.SessionInfoProvider
import ai.dea.base.Transporter
import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk

class MyCapture : Integration {
    override val name = "my-capture"
    val captured = mutableListOf<SchemaObject>()

    override fun setup(attach: (Transporter) -> Detach, session: SessionInfoProvider) {
        attach(Transporter { obj -> captured.add(obj) })
    }
}

DeaSdk.init(
    this,
    DeaConfig(appId = "YOUR_APP_ID", appKey = "YOUR_APP_KEY", integrations = listOf(MyCapture())),
)

attach returns a Detach: call its detach() to detach the transporter. setup also receives the session as its second argument: session.sessionInfo answers the same as sessionInfo on the instance DeaSdk.init returns.

How the objects reach your transporter:

Rule Description
Order In capture order, a moment after capture, on the main thread. Each transporter has its own queue, but all queues drain on the main thread, so a slow transport delays your app's drawing and the other transporters
Background When the app goes to the background, every queued object is handed over at once
Queue limit 8192 objects. Past that, new objects are dropped until the queue drains. The test package logs pipeline.queue_full at the first drop
Errors A transporter whose transport throws 5 times in a row is detached. The test package logs pipeline.transporter_failed for each throw and pipeline.transporter_detached at the end
setup throws That integration is skipped. The other integrations and init go on
Consent When the user withdraws consent, the objects still queued are discarded. Your transporter stays attached and receives again once the user agrees
Stop With automationDetection = true, a stop discards the queued objects and detaches every transporter. A reset() that lifts the stop calls setup again
dispose() The queued objects are discarded, and nothing more arrives

Keep transport short: copy the object into your own buffer, and send from your own thread.

What an object holds

Every object is a SchemaObject, from ai.dea.base. It carries schema, the version of its shape (2 when events includes a key kind, 1 otherwise); session, the session id; and device: the runtime, the operating system, the screen size in dp (surface), the screen density (pixelRatio), the rotation in degrees, the number of touch points and the motion sensor rate in Hz (sensorRate, 0 until motion arrives). It is one of four classes, each with one record:

Class Record When Fields
PointerObject event A touch, stylus, mouse, hover or scroll event, or a key your app reports with captureKey ts, kind (a Kind code), tool (a PointerTool code), buttons, position (x, y, in dp on device.surface), and when they apply pointerId, scroll (deltaX, deltaY, a ScrollUnit code), force, contact, stylus, target (a TargetBucket code and an id), key (the KeyClass, the modifiers and whether it repeats, never the character)
MotionObject motion One motion sensor sample: at the full rate within 200 ms of a touch, and one every 3 seconds otherwise. idleMotionMs = 0 keeps every sample ts, acceleration (m/s², three axes, gravity included), rotationRate (rad/s, three axes)
LifecycleObject lifecycle The app goes to the background or returns ts, state (a LifecycleState code)
CustomObject custom Your app records a custom event. The SDK also writes its own markers here, with names that start with dea. ts, name, data

ts is in microseconds since the session began. kind, tool, state and the scroll unit are Int codes: compare them with the code of the enum, for example obj.event.kind == Kind.DOWN.code. Kind, PointerTool, ScrollUnit, LifecycleState, TargetBucket and KeyClass are in ai.dea.base. obj.wireJson() renders an object as JSON with the schema's own key names, such as pointer_id and rotation_rate.

Examples

Send test sessions to your own service

import ai.dea.base.Detach
import ai.dea.base.Integration
import ai.dea.base.SessionInfoProvider
import ai.dea.base.Transporter
import ai.dea.base.wireJson
import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk
import android.app.Application
import android.util.Log
import java.net.HttpURLConnection
import java.net.URL
import java.util.concurrent.ConcurrentLinkedQueue
import java.util.concurrent.Executors
import java.util.concurrent.TimeUnit

class QaForwarder : Integration {
    override val name = "qa-forwarder"
    private val buffer = ConcurrentLinkedQueue<String>()

    init {
        Executors.newSingleThreadScheduledExecutor()
            .scheduleWithFixedDelay(::send, 5, 5, TimeUnit.SECONDS)
    }

    override fun setup(attach: (Transporter) -> Detach, session: SessionInfoProvider) {
        attach(Transporter { obj -> buffer.add(obj.wireJson()) })
    }

    private fun send() {
        val batch = generateSequence { buffer.poll() }.toList()
        if (batch.isEmpty()) return
        runCatching {
            val connection = URL("https://qa.example.com/dea-sessions").openConnection() as HttpURLConnection
            connection.requestMethod = "POST"
            connection.doOutput = true
            connection.setRequestProperty("content-type", "application/json")
            connection.outputStream.use { it.write(batch.joinToString(",", "[", "]").toByteArray()) }
            connection.responseCode
            connection.disconnect()
        }
    }
}

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        val dea = DeaSdk.init(
            this,
            DeaConfig(
                appId = "YOUR_APP_ID",
                appKey = "YOUR_APP_KEY",
                requireConsent = true,
                onLog = { entry -> Log.d("MyApp", "${entry.spec.name} ${entry.attributes}") },
                integrations = listOf(QaForwarder()),
            ),
        )

        // When the tester agrees:
        dea.setConsent(true)
    }
}

https://qa.example.com stands for your own service. The forwarder sends from its own thread: Android refuses network calls on the main thread. What you send there is yours to protect: it holds your testers' raw input.