Reference

operations: machine queries

Package Trax.Api.GraphQL·Surface GraphQL schema·Source OperationsQueries.MachineInstances.cs, OperationsQueries.Machines.cs

Fields of OperationsQueries that read persisted state machines: the machines a host registers, and their instances.

machines

Every machine the host registers, ordered by name, whether or not it has any instances, with its graph. It reads through IOperationsService.GetMachinesAsync, which reads each machine's IR by the same reading trax machine show draws it from, so the two list the same states and edges in the same order.

query {
  operations {
    machines {
      name
      version
      systemOwned
      initialState
      states { name isInitial isFinal isCommitted invokesTrain spawnsMachine }
      transitions { from command to kind guard effect after }
      timers { state command target after field min max }
    }
  }
}

Returns: [MachineDefinition!]!.

It carries what a machine declares and nothing about any instance: the counts and the instances are the fields below.

machineInstances

The instances of every persisted state machine on the host, system-owned and users' drafts alike, newest first by when each was last written. It reads through IOperationsService.GetMachineInstancesAsync and CountMachineInstancesAsync, which the operations console's Machines pages make.

query {
  operations {
    machineInstances(machine: "fulfilment", state: "AwaitingPayment", ownerKind: SYSTEM, take: 25) {
      items {
        rowId
        machine
        ownerKind
        id
        state
        version
        createdAt
        updatedAt
        hasLiveInvokedRun
      }
      totalCount
      isCountCapped
    }
  }
}

Returns: PagedResultOfMachineInstance!. There is no keyset cursor (nextCursor is always null), because the list is ordered by a time that moves as instances advance: page with skip. The total counts at most 10,000 instances; past that it reads 10,000 with isCountCapped true, and machineInstanceCounts has the exact numbers. At two million instances each page, filtered or not, reads in a few milliseconds.

MachineInstance fields

Needing attention

An instance is stuck when its timer is overdue, or when the run it waits on failed or was cancelled and its outcome was never applied: a run that ended more than one timer poll ago, or an entry cancelled while still queued. The poll is the host's StateMachineOptions.InvokeOutcomeSweepInterval (5 seconds by default), the pace at which the reconciler fires timers and applies outcomes, so an instance is never stuck only because a sweep has not come round yet. How long an instance has sat in its state is shown (inStateSince) and never counted: a state some instances wait in for days is not a fault.

No field carries an instance's context, and none names the user who owns a draft. The context is an untyped JSON object, so nothing could mask the sensitive parts of it; an operator sees where an instance is, when it got there and which kind of owner holds it, never what it holds (ADR 0046). A user reaches their own drafts only through the stateMachine mutations, never through this list.

machineInstance

One instance, or null when none matches. The owner kind is always named, because a user can hold a draft under the same id as a system instance. A system instance is unique by machine and id. A user's draft also needs its rowId, because several users can each hold a draft under one id and an operator is not shown whose a draft is.

query {
  operations {
    system: machineInstance(machine: "fulfilment", ownerKind: SYSTEM, id: "6f9619ff-8b86-d011-b42d-00c04fc964ff") {
      state
      hasLiveInvokedRun
    }
    draft: machineInstance(machine: "checkout", ownerKind: USER, id: "6f9619ff-8b86-d011-b42d-00c04fc964ff", rowId: 42) {
      state
      updatedAt
    }
  }
}

Returns: MachineInstanceDetail, with the fields of MachineInstance and the train runs the instance invoked, which only this lookup reads:

A system instance lists every run it invoked. A user's draft lists only its live run: a run records the machine, instance id and owner kind that queued it, not the user, and several users can each hold a draft under one id, so listing every run under the id could show another user's.

query {
  operations {
    machineInstance(machine: "fulfilment", ownerKind: SYSTEM, id: "6f9619ff-8b86-d011-b42d-00c04fc964ff") {
      state
      invokedRuns { id name trainState startTime endTime failureClass isLive }
      queuedInvokedRunEntryId
    }
  }
}

The one operator action on an instance is cancelMachineInstance.

transitions

The instance's history, newest first: one MachineInstanceTransition for every write of its snapshot Trax recorded, its creation, each command, save, timer and run outcome. It reads through IOperationsService.GetMachineInstanceTransitionsAsync, the history the console's instance page shows, and only when selected. The history is the row's (rowId), so a user's draft shows only its own, and it starts with the first write after the upgrade that added it (089).

query {
  operations {
    machineInstance(machine: "fulfilment", ownerKind: SYSTEM, id: "6f9619ff-8b86-d011-b42d-00c04fc964ff") {
      transitions(first: 25) {
        items {
          revision kind trigger actor fromState toState at previousAt
          startedRun { executionId trainState workQueueEntryId }
          startedChild { machine ownerKind id rowId }
        }
        nextCursor
      }
    }
  }
}

Returns: MachineInstanceTransitions!: items, the transitions on this page, and nextCursor, the revision to pass as after for the next page, or null on the last. Each MachineInstanceTransition has:

No transition carries the instance's context or its owner's key. The history is deleted with the instance.

machineInstanceCounts

How many instances each machine has in each state, for each owner kind, ordered by machine, state and owner kind. Exact. It reads through IOperationsService.GetMachineInstanceStateCountsAsync, the counts the dashboard's State Machines page shows.

query {
  operations {
    machineInstanceCounts(machine: "fulfilment") { machine state ownerKind count }
  }
}

Returns: [MachineInstanceCount!]!, each with machine: String!, state: String!, ownerKind: SnapshotOwnerKind!, count: Long! and stuck: Long!, how many of them are stuck. On Postgres the counts are read from the listing's index alone: about 120 ms over two million instances. Each host keeps the counts it read for 5 seconds, per machine filter, and callers asking meanwhile share that read, so every dashboard and API client polling them costs one read, not one each; a count can be that old.

See also

• Queries
• operations: machine instance mutations
• Invoking trains