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 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 requireConsent is true, 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.