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 skips every integration of your own, so nothing on this page reaches an app you release. DEA's collection transporter with stream delivery is the one integration it still sets up: see Collect Data.
When to use it¶
- Watch what the SDK does while you integrate, in your own log panel or logging service
- Record the raw input of test sessions for your own QA or analysis
Prerequisites¶
- The staging package is installed, as below. The test package works the same way and also logs
DEBUG - Where
requireConsentistrue, the default, your testers agreed — see User Consent. Nothing is captured before they do
The staging package comes from the staging channel. From your app's root folder:
mkdir -p vendor/dea && cd vendor/dea
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/base/dea-base-0.26.0.zip
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/automation-detection/dea-automation-detection-0.26.0.zip
curl -sSO https://sdk.dep-protocol.com/0.26.0/staging/flutter/sdk/dea-sdk-0.26.0.zip
for zip in *.zip; do unzip -qo "$zip"; done
A test app downloads the same three zips from /test/flutter/ instead of /staging/flutter/.
pubspec.yaml stays as in the Quick Start.
Usage¶
Receive the log¶
Pass onLog to DeaOptions. The SDK calls it with every entry, and still writes each entry to the
developer log (dart:developer) under the name dea, which Flutter DevTools shows in its Logging
view.
import 'package:dea_sdk/dea_sdk.dart';
void main() {
DeaSdk.init(
DeaOptions(
appId: 'YOUR_APP_ID',
onLog: (entry) => myLogger.log(entry.levelText, entry.spec.name, entry.toJson()),
),
appKey: 'YOUR_APP_KEY',
);
runApp(const MyApp());
}
myLogger stands for your own code. The entry is a LogEntry. dea_sdk does not export that
type, so take entry as the callback receives it. entry.toJson() uses OpenTelemetry field names:
| Field | Dart member | Description |
|---|---|---|
timestamp |
timestamp |
When the step happened. In toJson(), UTC ISO 8601 with milliseconds |
severityText |
levelText |
DEBUG, INFO, WARN or ERROR |
severityNumber |
severityNumber |
The OpenTelemetry number of that level: 5, 9, 13 or 17 |
eventName |
spec.name |
The step, for example sdk.ready or proof.not_signed |
body |
body |
One sentence that describes the step |
attributes |
session, outcome, attributes |
session.id and dea.outcome (ok, refused or failed), then the step's own values |
resource |
resource |
service.name (dea-sdk), service.version, os.type and dea.flavor (staging or test) |
entry.line renders the entry as its developer log line. There is no option to change the level:
the staging package logs INFO, WARN and ERROR, and the test package adds DEBUG. An error
your onLog throws is ignored, and does not stop the developer log.
On the test package, debug: true also logs a capture.input entry for every captured object,
with its record's key, and writes each object as JSON to the developer log. On the staging package
it does nothing.
Receive the captured input¶
An integration is a class that implements Integration: a name and a setup method. The SDK
calls setup once, during DeaSdk.init, before capture starts, with attach. Each Transporter
you attach receives every object the SDK captures, through its transport method.
import 'package:dea_sdk/dea_sdk.dart';
final captured = <SchemaObject>[];
final class MyCapture implements Integration {
@override
String get name => 'my-capture';
@override
void setup(Detach Function(Transporter) attach, SessionInfoProvider session, _) {
attach(ListTransporter(captured));
}
}
final class ListTransporter implements Transporter {
ListTransporter(this.buffer);
final List<SchemaObject> buffer;
@override
void transport(SchemaObject obj) => buffer.add(obj);
}
void main() {
DeaSdk.init(
DeaOptions(appId: 'YOUR_APP_ID', integrations: [MyCapture()]),
appKey: 'YOUR_APP_KEY',
);
runApp(const MyApp());
}
attach returns a Detach function that detaches the transporter. session answers
getSessionInfo() the same as DeaSdk.instance!.getSessionInfo(). The third argument is the SDK's
own log, which your code does not use. Pass integrations to the first DeaSdk.init: a later call
returns the running instance and keeps its options.
How the objects reach your transporter:
| Rule | Description |
|---|---|
| Order | In capture order, a moment after capture, on your app's main isolate. Each transporter has its own queue |
| Queue limit | 8192 objects. Past that, new objects are dropped until the queue drains |
| Errors | A transporter whose transport throws 5 times in a row is detached |
| Consent | When the user withdraws consent, the objects still queued are discarded. The transporter stays attached, and objects arrive again after a new yes |
| Automation stop | With automationDetection: true, when the SDK stops, the objects still queued are discarded and nothing arrives until reset() |
dispose() |
The objects still queued are discarded, and nothing more arrives |
Keep transport short and synchronous: it runs on the same isolate as your UI, so slow work there
costs frames. Copy the object into your own buffer, and send from your own timer. The SDK does not
wait for a Future, so an error thrown after an await does not count toward the 5.
What an object holds¶
Each object is a SchemaObject. It carries schema, the version of its shape; session, the id
of the session it was captured in; and device: runtime, os, surface (width and height in
logical pixels), pixelRatio, rotation (degrees), maxTouchPoints (always 0 on Flutter: not
known) and sensorRate (Hz, 0 until motion data arrives). Its body is exactly one of these
records:
| Record | JSON key | When | Fields |
|---|---|---|---|
EventBody |
event |
A touch, mouse, stylus, trackpad or scroll event, or a key press your app reports with captureKey |
ts, kind (EventKind), tool (Tool), buttons, position (x, y, logical pixels on device.surface), and when they apply pointerId, scroll (deltaX, deltaY in logical pixels), force, contact, stylus, target, keyPress (the KeyClass and modifiers, never the character) |
MotionBody |
motion |
One motion sensor sample, on phones and tablets | ts, acceleration (m/s², three axes, gravity included), rotationRate (rad/s, three axes) |
LifecycleBody |
lifecycle |
The app goes to the background or returns | ts, state (LifecycleState) |
CustomBody |
custom |
Your app records a custom event, or the SDK writes a marker whose name starts with dea. |
ts, name, data |
ts is in microseconds since the session began; getSessionInfo().startedAt is that moment in
Unix milliseconds, for the current session. obj.toJson() gives the object as DEA's schema writes
it: snake_case keys, and enums as numbers. A switch on obj.body with the four record types
covers every case. dea_sdk exports these types, with the other types of the object.
Group objects by obj.session, not by the current session: an object still queued at reset()
belongs to the session before it.
Examples¶
Send test sessions to your own service¶
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';
final _buffer = <SchemaObject>[];
final class QaForwarder implements Integration {
@override
String get name => 'qa-forwarder';
@override
void setup(Detach Function(Transporter) attach, SessionInfoProvider session, _) {
attach(_BufferTransporter());
}
}
final class _BufferTransporter implements Transporter {
@override
void transport(SchemaObject obj) => _buffer.add(obj);
}
Future<void> _send() async {
if (_buffer.isEmpty) return;
final batch = [for (final obj in _buffer) obj.toJson()];
_buffer.clear();
final client = HttpClient();
try {
final request = await client.postUrl(Uri.parse('https://qa.example.com/dea-sessions'));
request.headers.contentType = ContentType.json;
request.write(jsonEncode(batch));
await (await request.close()).drain<void>();
} on Object catch (error) {
debugPrint('QA upload failed: $error');
} finally {
client.close();
}
}
void main() {
DeaSdk.init(
DeaOptions(
appId: 'YOUR_APP_ID',
onLog: (entry) => debugPrint(entry.line),
integrations: [QaForwarder()],
),
appKey: 'YOUR_APP_KEY',
);
Timer.periodic(const Duration(seconds: 5), (_) => _send());
runApp(const MyApp());
}
Then ask for consent, as in User Consent: nothing is captured
until the tester agrees. https://qa.example.com stands for your own service. 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
- Privacy and network