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.0fromhttps://sdk.dep-protocol.com/0.26.0/staging/android, with thecontentfilter shown in Collect Data. The test package, fromhttps://sdk.dep-protocol.com/0.26.0/test/android, works the same way and also logsDEBUG - Where
requireConsentistrue, 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.
Related¶
- Collect Data: DEA's own integration, which sends the captured input to DEA
- Options:
onLoganddebug - User Consent
- Privacy and network