Reference

operations: system queries

Package Trax.Api.GraphQL·Surface GraphQL schema·Source OperationsQueries.cs

Fields of OperationsQueries, the type behind query { operations { ... } }, that describe the host and its registered trains. The namespace exists only when the host calls ExposeOperationQueries(), and every field answers to the operations gate.

health

Returns the current health status of the Trax scheduler system. This is the same data reported by the ASP.NET IHealthCheck at /trax/health, exposed as a structured GraphQL type.

It is the dashboard's home page read, behind the operations gate like every field here. A monitor, load balancer or scraper reads /trax/health instead (AddTraxHealthCheck and MapHealthChecks), which needs no GraphQL document and no operator credential.

query {
  operations {
    health {
      status
      description
      queueDepth
      inProgress
      failedLastHour
      deadLetters
    }
  }
}

Returns: HealthStatus!

HealthStatus fields

Status is Degraded when deadLetters > 0 or failedLastHour > 10.

trains

Returns every train registered in the DI container, including a runtime-generated input schema describing each property on the input type. Pass hideAdminTrains: true to exclude the framework's internal scheduler trains (manifest manager, job dispatcher, dead letter cleanup, etc.) from the result; the dashboard uses this flag when its "Hide admin trains" toggle is on.

query {
  operations {
    trains {
      fullName
      serviceTypeName
      implementationTypeName
      inputTypeName
      outputTypeName
      lifetime
      inputSchema {
        name
        typeName
        isNullable
        enumValues
      }
    }
  }
}

Returns: [TrainInfo!]!

TrainInfo fields

InputPropertySchema fields

The names and enum spellings come from the same options queueTrain and runTrain deserialize input with, so a client that builds its JSON from this schema writes what the reader accepts.

adminTrainNames

Returns the canonical FullNames of the framework's internal scheduler trains (job dispatcher, manifest manager, job runner, cleanup). This is the same list hideAdminTrains filters against on the trains, manifests and executions queries and the metrics.dashboard query.

query {
  operations {
    adminTrainNames
  }
}

The subscription feed streams every train on an admin host, so the dashboard reads this list once and filters the live onTrainStateChanged events client-side by the same rule the server applies to the grid, keeping the feed and grid consistent when "Hide admin trains" is on.

Returns: [String!]!

hosts

The host processes that have beaten in the last day, from trax.host_heartbeat. Every host with a data provider rewrites its row every 15 seconds whether or not it has work (Host Tracking), so the list shows an idle host as online and a dead one as offline. Online hosts come first, then by name.

query {
  operations {
    hosts {
      instanceId
      name
      environment
      traxVersion
      startedAt
      lastHeartbeat
      online
      runsDispatcher
      runsManifestManager
      workerSlots
      workerSlotsInUse
      currentlyRunning
    }
  }
}

It reads the small heartbeat table and counts each listed host's runs in progress, so it is cheap at any history size. A host on a version from before the heartbeat writes no row and is not listed.

Returns: [HostInfo!]!

HostInfo fields

trainStats

Execution roll-up for a single train, keyed by its interface FullName (the value stored in metadata.Name). Backs the summary cards on the dashboard's per-train detail page. The state grouping and ix_metadata_* indexes keep it cheap against a large metadata table.

query {
  operations {
    trainStats(trainName: "MyApp.Trains.Reports.IBuildDailyReportTrain") {
      total
      completed
      failed
      inProgress
      averageMilliseconds
      lastRun
      lastSuccessfulRun
    }
  }
}

Returns: TrainExecutionStats!

TrainExecutionStats fields

effects

Lists the observational effects registered in the API process, with their enabled and toggleable state and, for an effect whose factory exposes runtime settings, those settings: as JSON, and as fields a settings editor can be built from. It reads through IEffectSettingsService in Trax.Scheduler, the service the dashboard's effects page calls, so both show the same values. Empty when the host registers no effect registry.

The effect registry and each settings object are in-memory, per-process singletons with no persistence or cross-process broadcast, so this reflects the API host only, not the scheduler/worker processes where effects actually run. setEffectEnabled toggles an effect and configureEffect changes its settings in this same process. Changing effect state across a distributed deployment would need a shared store plus a change broadcast, which is not built.

query {
  operations {
    effects {
      name
      fullName
      enabled
      toggleable
      isConfigurable
      configurationTypeName
      configuration
      fields {
        name
        typeName
        kind
        nullable
        enumValues
        sensitive
        hasValue
        value
        hint
      }
    }
  }
}

Returns: [EffectInfo!]!, ordered by fullName.

EffectInfo fields

EffectSettingInfo fields

Settings can hold credentials. Like an execution's input, they are reachable only under the operations namespace, so the gate you put on it (GateOperations or RequireAuthorization) decides who reads them. See Train inputs and the operations gate.

lookup

Finds what an id, key or name names when you do not know its kind, the read behind the console's search. It calls IOperationsService.LookupAsync.

query {
  operations {
    lookup(text: "7f3c0e2a9b1d4c5e8f6a7b8c9d0e1f2a") {
      kind
      id
      label
      matchedOn
      machine
      ownerKind
      rowId
    }
  }
}

Returns: [LookupMatch!]!, empty when nothing matches.

Matches are exact, after trimming: runs by id and external id, manifests by id, external id and name, work queue entries by id, external id and subject key (those still queued or dispatched), dead letters by id, state-machine instances by id, and registered trains by full or friendly name. Each is one read of an indexed column, at most 10 matches of each kind. An instance is named the way machineInstances names it, never by its context or whose a user's draft is. Like every field here it answers to the operations gate.

attention

What needs an operator's attention, the read behind the console's Overview. It calls IOperationsService.GetAttentionAsync.

query {
  operations {
    attention {
      asOf
      scheduler { manifestManagerEnabled jobDispatcherEnabled paused link }
      deadLetters { trainName reason count oldestDeadLetteredAt link }
      failingTrains { trainName failedLastHour finishedLastHour lastHourFailureRate baselineFailureRate link }
      stuckInstances { machine state count link }
      queue { queued oldestQueuedAt oldestAgeSeconds link }
      offlineHosts { instanceId hostName lastHeartbeatAt runsDispatcher link }
    }
  }
}

Returns: Attention!.

Each list holds at most 50 entries. Every entry has a link: the console path and query that lists what it counts, such as /runs?state=FAILED&train=Shop.ICheckoutTrain or /machines/order?state=Waiting&stuck=true. A stuck-instance group names a machine and a state, never an instance's owner or context. Like every field here it answers to the operations gate.

See also

• Queries
• operations: execution queries
• operations: effect mutations