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 page 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 refuses every integration, so nothing on this page reaches a page you release.
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 — see Verify your setup. The
test package works the same way and also logs
DEBUG - Where you set
requireConsent, your testers agreed — see User Consent. Nothing is captured before they do
Usage¶
Receive the log¶
Pass onLog to init. The SDK calls it with every entry, and still writes each entry to the
console.
import { init } from '@dea/sdk';
init({
appId: 'YOUR_APP_ID',
appKey: 'YOUR_APP_KEY',
onLog: (entry) => myLogger.log(entry.severityText, entry.eventName, entry.attributes),
});
myLogger stands for your own code. Each entry uses OpenTelemetry field names:
| Field | Description |
|---|---|
timestamp |
When the step happened, ISO 8601 |
severityText |
DEBUG, INFO, WARN or ERROR |
severityNumber |
The OpenTelemetry number of that level |
eventName |
The step, for example sdk.ready or proof.not_signed |
body |
One sentence that describes the step |
attributes |
The step's values, for example session.id |
resource |
The SDK release and the platform |
formatLine(entry), exported by the package, renders an entry as its console line. logLevel
raises the level entries are written from, for the console and onLog alike: 'warn' drops
INFO, and 'off' stops both. See Logging options.
Receive the captured input¶
An integration is an object with a name and a setup function. The SDK calls setup once, during
init, with attach. Each transporter you attach receives every object the SDK captures, through
its transport method.
import { init, type SchemaObject } from '@dea/sdk';
const captured: SchemaObject[] = [];
init({
appId: 'YOUR_APP_ID',
appKey: 'YOUR_APP_KEY',
integrations: [
{
name: 'my-capture',
setup(attach) {
attach({ transport: (object) => captured.push(object) });
},
},
],
});
attach returns a function that detaches the transporter. setup also receives the session as
its second argument: session.getSessionInfo() answers the same as getSessionInfo() on the
instance init returns.
How the objects reach your transporter:
| Rule | Description |
|---|---|
| Order | In capture order, a moment after capture. Each transporter has its own queue, so a slow transport delays only itself |
| Queue limit | 4096 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 |
dispose() |
Nothing more arrives |
Keep transport short: copy the object into your own buffer, and send from your own timer.
What an object holds¶
Every object carries schema, the version of its shape; session, the session id; and device:
the runtime, the operating system, the surface size, the pixel ratio, the rotation, the number of
touch points and the motion sensor rate. It also holds exactly one of these records:
| Key | When | Fields |
|---|---|---|
event |
A pointer, wheel or key event | ts, kind (Kind), tool (PointerTool), buttons, position (x, y, logical pixels on device.surface), and when they apply pointer_id, scroll, force, contact, stylus, target, key (the KeyClass and modifiers, never the character) |
motion |
One motion sensor sample, on phones and tablets | ts, acceleration (m/s², three axes), rotation_rate (rad/s, three axes) |
lifecycle |
The page goes to the background or returns | ts, state (LifecycleState) |
custom |
Your app records a custom event | ts, name, data |
tick |
A fixed heartbeat while the session runs, on desktop only | ts |
ts is in microseconds since the session began. Kind, PointerTool, KeyClass and
LifecycleState are exported by the package, with the other types of the object.
Examples¶
Send test sessions to your own service¶
import { init, type SchemaObject } from '@dea/sdk';
const buffer: SchemaObject[] = [];
setInterval(() => {
if (buffer.length === 0) return;
const batch = buffer.splice(0);
void fetch('https://qa.example.com/dea-sessions', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(batch),
});
}, 5000);
const dea = init({
appId: 'YOUR_APP_ID',
appKey: 'YOUR_APP_KEY',
requireConsent: true,
onLog: (entry) => console.debug('[dea]', entry.eventName, entry.attributes),
integrations: [
{
name: 'qa-forwarder',
setup(attach) {
attach({ transport: (object) => buffer.push(object) });
},
},
],
});
// When the tester agrees:
dea.setConsent(true);
https://qa.example.com stands for your own service; allow it in connect-src of your
Content Security Policy. 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
- Logging options
- Privacy and network