Flows

Turn stable SDK event pairs into reusable semantic time windows for quality measurement and grouped performance history.

CLI v0.23.1

A flow names a meaningful period in an app session. In simple terms: start a stopwatch when one SDK event arrives and stop it when another arrives. Quality checks can then measure the same window without duplicating event-matching rules.

Examples include app launch, login, search, opening a detail screen, loading a 3D guide, or completing an offline sync.

Create a flow

Flow definitions are JSON files beneath ansight/flows:

{
  "schemaVersion": 1,
  "id": "login",
  "appId": "com.example.app",
  "start": {
    "event": {
      "label": "auth.login.started"
    }
  },
  "end": {
    "event": {
      "label": "auth.login.completed"
    }
  },
  "selection": "lastCompleted",
  "maximumDurationMs": 30000
}

The app must emit stable start and end labels through its Ansight SDK integration. Treat those labels as a versioned instrumentation contract: if a label changes, every flow that refers to it stops matching.

Fields

FieldRequiredMeaning
schemaVersionNoContract version. Omitted definitions use version 1.
idNoStable flow ID. Defaults to the path-derived ID.
appIdYesExact bundle or package ID whose events may match.
startYesEvent anchor that opens the window.
endYesEvent anchor that closes the window.
selectionNoWhich completed instance to use: firstCompleted, lastCompleted, exactlyOne, or all.
maximumDurationMsNoMaximum permitted start-to-end duration, up to 30 minutes.

An event anchor always has a label. It may also narrow matching by eventType or telemetry channelId when the app emits similar labels on different sources.

Multiple flow instances and grouping

A session may contain more than one completed instance of a flow. selection controls whether Ansight chooses the first, last, exactly one, or all completed instances.

Grouping is automatic. When matching start and end events carry the same non-empty details value, Ansight pairs them within that group and carries the value into measurements and trend history. For example, the same guides.load.started and guides.load.completed labels can produce separate series for “Secret Garden” and “Seaside.” Events without details remain in the ungrouped series.

maximumDurationMs prevents a late, unrelated end event from pairing with an old start event. Choose a limit that includes realistic slow runs without allowing unrelated activity to be joined.

Connect a quality check

Quality definitions refer to a flow by ID:

{
  "id": "login-responsiveness",
  "appId": "com.example.app",
  "flow": "login",
  "measurements": []
}

The complete definition needs at least one measurement; see Quality for a working example.

Validate and troubleshoot

ansight test validate .

If a flow is not observed:

  • confirm the app emits both labels with the expected App ID;
  • check spelling, case, optional event type, and channel ID;
  • make sure the end arrives within maximumDurationMs;
  • check that grouped start and end events use the same details value; and
  • inspect the captured session timeline before adjusting the definition.