Monitoring and Telemetry in CGSE¶

CGSE can propagate housekeeping and metrics data from control server processes to InfluxDB or QuestDB. Grafana can then be used to visualize these metrics.

This page is developer-focused: it explains how CGSE structures telemetry data and how that data reaches the configured metrics backend.

For stack installation and system configuration, see Monitoring Stack Setup. Alo For day-to-day Grafana usage and dashboard creation, see Using Grafana.

Database Structure¶

Understanding this structure helps when you add new telemetry producers or when you troubleshoot missing fields in Grafana.

Database Name¶

In the current implementation, the name of the database in which all CGSE metrics are stored is taken from the CGSE_INFLUX_DATABASE environment variable. If that environment variable is not set, the PROJECT environment variable is used with cgse as final fallback for the database name. This keeps the database name aligned with the active project context.

To inspect the available database names, execute this in a terminal on the server:

InfluxDBQuestDB

influxdb3 show databases

cgse admin sql --backend questdb 'SELECT current_database() AS database;'

To create a database manually, execute:

InfluxDBQuestDB

influxdb3 create database <database name>

QuestDB typically uses the configured database (default: qdb) and does not require a per-project database creation step in the CGSE workflow.

Table Names¶

Each process writes to a dedicated table. The table name matches the storage mnemonic of the process in lower case.

To list the available tables, execute this in a terminal on the server:

InfluxDBQuestDB

influxdb3 query --database <database name> "SHOW TABLES"

cgse admin sql --backend questdb 'SELECT table_name FROM tables()'

Note that a table is often also called a measurement. They are basically the same thing, just different names for the same concept, depending on context:

When you interact with InfluxDB using line protocol (the native InfluxDB write format), it's called a measurement.
When you query using SQL, that same entity appears as a table.

Content of the Tables¶

For each table, the column names are the names of the corresponding housekeeping and metrics parameters. The timestamp column is named TIME.

To inspect the columns of a table, execute this in a terminal on the server:

InfluxDBQuestDB

influxdb3 query --database <database name> "SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = '<table name>'"

cgse admin sql --backend questdb "SHOW COLUMNS FROM \"<table name>\""

To inspect the stored data in ascending timestamp order, execute:

InfluxDBQuestDB

influxdb3 query --database <database name> "SELECT * FROM <table name> ORDER BY TIME"

cgse admin sql --backend questdb "SELECT * FROM \"<table name>\" ORDER BY time"

Add a time range to restrict the data range:

InfluxDBQuestDB

influxdb3 query --database <database name> "SELECT * FROM <table name> WHERE time >= now() - interval '10 minutes' ORDER BY TIME"

cgse admin sql --backend questdb "SELECT * FROM \"<table name>\" WHERE time >= dateadd('m', -10, now()) ORDER BY time"

Propagating Metrics via Python¶

To populate metrics, CGSE uses the configured backend repository (for example, InfluxDB or QuestDB) through the shared metrics interfaces.

When implementing a new device, no additional propagation code is typically needed. Metrics propagation is handled automatically in the serve method of ControlServer.

When housekeeping information is written to CSV, ControlServer.propagate_metrics(..) is called and writes the corresponding metrics to the configured backend.

Design Notes¶

Open questions are tracked in the roadmap under Monitoring and Telemetry.