Skip to content

Dashboards and Metrics

Three feeds can drive a dashboard, and each one answers a different question. Prometheus carries platform and equipment metrics. The historian carries process data with history behind it. The gateway JSON API carries the value a tag holds right now. This page picks between them and hands off. Queries, schemas and payloads stay in the document that owns each feed.

Grafana is the usual client and it works against all three. The choice is therefore a question about the data.

Which feed answers which question

The panel shows Feed Owning document
Platform and equipment health: reconcile rates, runtime connectivity, scan-cycle behaviour, alarm counts, batch outcomes Prometheus, over the dcs_* metrics Monitoring and Metrics
A trend over process values, with history behind it The historian, over SQL or its REST query API Historian
The value a tag holds at this moment The gateway JSON API SCADA Integration

Most people asking about dashboards want the second row. A trend of a temperature over a shift, a week or a batch is historian data, and the other two feeds cannot draw it.

Prometheus carries platform and equipment metrics

The dcs_* family covers the control system itself: equipment and procedural states, batch outcomes and durations, runtime connectivity and scan-cycle behaviour, driver reconnects, active alarm counts, reconcile rates and gateway request latency. Operators, the historian and the runtimes each expose it on /metrics, and the Helm chart configures ServiceMonitors for a Prometheus Operator to scrape.

One line decides most cases. No metric carries a process value. Prometheus can tell you a unit runtime is connected and how far its scan cycle drifted, and it holds nothing about what the fermenter's temperature was at 03:00. Retention here belongs to your Prometheus and has no relationship to the historian's.

Reference dashboards for this feed ship in grafana/dashboards/ and are meant to be copied into your own Grafana and adapted. The catalogue, the alert rules and the import workflow are in Monitoring and Metrics.

The historian carries process data

The historian subscribes to the telemetry bus, stores the tag values the unit runtimes publish in PostgreSQL with TimescaleDB, and keeps them for a configured retention period that defaults to a year. Alarm events, state transitions and Control Module health land in the same database beside them.

There are two ways in, and both are documented in Historian:

  • Direct SQL. The tables are ordinary PostgreSQL tables and the account that writes them is an ordinary database user. A dashboard host with network access to the database queries them with no adapter, no connector and no export step.
  • The gateway's historian query API. GET /api/v1/historian/tags and its siblings answer the same data over HTTP, with bucketed aggregates, and every request is authorized as a DCS user. Choose this when the dashboard should sit inside the gateway's permission model, or when it has no route to the database.

The built-in Trends view uses the second path and holds no privileged position. A chart drawn elsewhere from the same rows is the same chart.

Grafana on the historian's PostgreSQL, beside the built-in Trends view, over the same week of one fermenter's temperature.

The gateway JSON API carries live values

Point a dashboard here when the panel needs current values and no history: a mimic, a status wall, a numeric readout that refreshes. The routes are the tag read surface in SCADA Integration, which is a different part of the same gateway from the historian query API above. Two of its constraints decide whether the dashboard is viable.

Request shape. Reads are rate limited per source address, and a panel built on one request per tag exhausts the allowance long before a plant-sized dashboard finishes refreshing. A bulk unit read returns every live value a unit holds in a single request, which is the shape a polling dashboard should use. See Rate Limits for the tiers and Connection Limits for the ceiling on concurrent WebSocket and SSE streams.

Credentials. Every request carries a bearer token belonging to a user session, and that session expires on the lifetime the deployment sets. The one long-lived machine credential the gateway mints is the MES integration key, which is fenced to /api/v1/mes/ and reaches neither the tag routes nor the historian API. An unattended dashboard on this feed therefore needs a service identity in your own identity provider, carrying a group that maps to the read permission. It refreshes its token like any other OIDC client.

MQTT is an ingest path

The telemetry bus is how values reach the historian, and it is a publish stream with no query surface. Tag value topics are not retained, so a client that subscribes sees values as they arrive and has nothing behind them to draw. A dashboard built on MQTT is really a dashboard on whatever stored the stream, and in this product that store is the historian. Point it there. A plant running its own time-series database off the same broker points the dashboard at that database, and MQTT Telemetry documents the topics and payloads such a consumer subscribes to.