Skip to content

Telemetry ​

The app reports what its user does to Instagram as telemetry events. The Simulator logs them where the app does and sends them the way the app does: you do nothing. This page explains where the events wait, when they go out, and how a program sends them itself.

Where the events wait ​

The events wait in the phone's own queue, part of the session you save: the snapshot and every checkpoint carry what has not been sent yet, the way the app keeps it on disk. A process restored from them sends that tail when it starts, and the numbering of the events continues.

When they are sent ​

One sender per process sends them on the app's own reasons, on the process's clock:

  • an event that asks to go out at once goes out at once (a screen change does);
  • other events go out when the time they allow has passed (one minute, two and a half, five);
  • the app going to the background, coming back, starting and closing send what is waiting, and so does logging out (AccountLogout sends what is waiting before it asks to log out, as the app does, so those events leave under the account that is leaving);
  • the app's health counters go out on their own rhythm.

When the process closes, whatever is still waiting is sent; what does not get through stays in the phone's queue and goes out next time. An aborted call is the app being killed: nothing is sent and the queue is kept.

Sending now: FlushTelemetry ​

FlushTelemetry is "send now, inside the program": it sends everything waiting and reports { events }, and leftOut when it took events it could not send (see below).

ts
import { AndroidIgpapi, FeedTimelineScreen, FlushTelemetry } from '@igpapi/android';
import { Effect } from 'effect';
import { readFile } from 'node:fs/promises';

const saved = JSON.parse(await readFile('session.json', 'utf8'));

const sent = await AndroidIgpapi.launch({
  checkpoint: saved,
  screen: FeedTimelineScreen,
  main: feed =>
    Effect.gen(function* () {
      // ...the screen actions that log events...
      yield* feed.swipeToNext();
      // Send what is waiting now, instead of on the app's own schedule.
      return yield* FlushTelemetry(); // { events }
    }),
});
console.log(sent.events);

It sends only into the delivery session the process began at start-up. A process that never began one gets TelemetryDeliverySessionError (reason: 'session') and keeps its events. A program that composes the app layer itself begins the session with emitPigeonInfraBatches (@igpapi/pigeon-nest), which only begins it and logs the start-up events: like every telemetry building block it sends nothing itself, and the process's own sender (or FlushTelemetry) delivers what was logged.

When a delivery fails ​

An empty queue sends nothing ({ events: 0 }). If a channel's upload is rejected (the transport fails, or the server answers a non-2xx), FlushTelemetry fails with TelemetryDeliveryError, and that channel's events stay in the queue unchanged, so running it again sends the same events. An event leaves the queue only when its upload is confirmed: a saved session taken while an upload is on the wire still holds it. The error names the channel and why it failed: reason: 'transport' carries the request layer's cause, reason: 'http' carries the response status. A channel that delivered before the failing one keeps its events sent.

There is one exception to "an event leaves the queue only when its upload is confirmed": an event logged under an account the session no longer holds (the program replaced the session's account or tokens without logging out first) is never sent under another account's tokens, so it cannot be delivered at all. It is left out of the upload and leaves the queue with it; the flush reports it as leftOut (never in events), and it is not counted as uploaded in the app's health counters. AccountLogout avoids the case by sending what is waiting before the account leaves.

The pages of this site are the README files of the repository. The API reference is generated from the source.