Reference

operations.metrics queries

Package Trax.Api.GraphQL·Surface GraphQL schema·Source MetricsQueries.cs, ProcessCpuSampler.cs

MetricsQueries, the type behind operations { metrics { ... } }.

The operations.metrics namespace returns the data behind the dashboard's KPI cards, charts, and server health panel. Every field comes from the shared IOperationsService, so the GraphQL response and the dashboard render exactly the same numbers.

These are the dashboard's reads, behind the operations gate. A monitor that only needs to know whether the host is healthy reads /trax/health (AddTraxHealthCheck), not GraphQL.

dashboard

query {
  operations {
    metrics {
      dashboard(range: LAST24_HOURS, hideAdminTrains: true) {
        kpis { executionsToday successRate currentlyRunning unresolvedDeadLetters }
        executionsOverTime { timestamp completed failed cancelled }
        topFailures { trainName count }
        topAverageDurations { trainName averageMilliseconds }
        throughputSeries {
          trainName
          buckets { timestamp count }
        }
      }
    }
  }
}

Returns: DashboardMetrics.

DashboardMetrics fields

DashboardKpis fields

ExecutionsBucket fields

TrainFailureCount fields

TrainAverageDuration fields

ThroughputSeries fields

ThroughputBucket fields

dashboard runs several aggregations over the last-24h and last-7-day windows on every call, and those windows hold hundreds of thousands to millions of rows at scale. The metadata table carries two covering indexes for them (ix_metadata_metrics_state_time and ix_metadata_metrics_window) so every aggregation is a heap-free index-only scan. The aggregations run at once, each on a connection of its own, so the block takes as long as the slowest of them, the 7-day throughput aggregation, rather than their sum; a call holds up to seven pooled connections while it runs. At 3,000,000 metadata rows the whole block returns in ~290-345ms, with or without hideAdminTrains, against ~460-700ms when they ran one after another. It is the heaviest operations read, so poll it on an interval (a few seconds) rather than on every dashboard interaction.

series

Runs over time for one train, manifest or group: for each bucket of the range, how many runs that started in it completed, failed or were cancelled, and the median and 95th percentile duration of the completed ones.

query {
  operations {
    metrics {
      series(scope: TRAIN, name: "MyApp.Trains.IImportTrain", range: LAST7_DAYS) {
        from
        to
        bucketSeconds
        buckets { start completed failed cancelled p50DurationMs p95DurationMs }
      }
    }
  }
}

A TRAIN scope without name, or a MANIFEST or GROUP scope without id, is refused with the error code TRAX_METRICS_SERIES_ARGUMENT (MetricsQueries.SeriesArgumentCode), before anything is read. So is a range no scope can serve inside the dashboard's metrics budget on the existing indexes, as OperationsService.MetricSeriesRefusal decides: today that is LAST30_DAYS, for every scope. A 30-day series reads every run of the 30 days, and over a million runs in one train, manifest or group it took 560 to 660 ms on the stress fixture, against a 450 ms budget; the 7-day series of the same scope (about 230,000 runs) took 170 to 340 ms. The value stays in the enum so a later index can serve it without a schema change.

Returns: MetricSeries, read through IOperationsService.GetMetricSeriesAsync.

MetricSeries fields

MetricSeriesBucket fields

The percentiles are read from a histogram the database builds, with bins about 13% wide, so each is within one bin of the exact value and never outside the durations recorded; a bucket whose completed runs share one bin reads them exactly when they are equal. They are computed the same way on Postgres, Sqlite and InMemory.

server

Process-level snapshot. CPU% is not on ServerMetrics because it can only be measured as a delta between two samples; use the sibling serverCpuPercent field for that.

query {
  operations {
    metrics {
      server { processStartTimeUtc uptimeSeconds workingSetBytes gcHeapBytes }
    }
  }
}

Returns: ServerMetrics.

serverCpuPercent

This API process's CPU utilisation since the previous poll, as a percentage of total capacity (normalised by core count, so 100 means every core fully busy). CPU% is a delta measurement, so the sampler holds the previous sample: the first poll after startup returns null while the baseline primes, and each subsequent poll reports usage since the last. Poll it on the same interval as the rest of the dashboard's server panel. It reads ProcessCpuSampler.SamplePercent() (Trax.Api.Services.Metrics), a singleton that holds the previous sample.

It is a sibling of server rather than a field on ServerMetrics because the sampling state is per-process and stateful, which is exactly why it is not part of the shared IOperationsService snapshot the scheduler and dashboard also read.

query {
  operations {
    metrics {
      serverCpuPercent
    }
  }
}

Returns: Float (nullable; null on the first poll or if no measurable time has elapsed since the last).

See also

• Queries
• Dashboard