Sending Metrics

See also

The basic concepts behind metrics and telemetry in Constellation are described in the Telemetry chapter of the operator guide.

C++

Metrics have to be registered before use. For satellites this can be done via:

register_metric("NAME", "unit", "description");

This metric can then be sent using the STAT macros:

STAT("NAME", get_metric_value());

See also

There are also macros available to only send metrics every nth iteration or at most every t seconds. These macros are described in detail in the framework reference.

Metrics that are evaluated regularly from a lambda can also be registered:

register_timed_metric("NAME", "unit", "description", 10s,
                      [this]() -> std::optional<double> {
    return allowed_to_get_metric() ? std::optional(get_metric_value()) : std::nullopt;
});

The lambda can return either the value directly, or an optional, where the empty value means that the metric can currently not be sent. To check if the satellite is in a given state the getState() method can be used, or the following helper:

register_timed_metric("NAME", "unit", "description", 10s,
                      {CSCP::State::ORBIT, CSCP::State::RUN},
                      [this]() { return get_metric_value(); }
);

Note that timed metrics can still be triggered manually if desired.

Python

Metrics have to be registered before use. For satellites this can be done via:

self.register_metric("NAME", "unit", "description")

This metric can then be sent using the stat method:

self.stat("NAME", self.get_metric_value());

Metrics that are evaluated regularly from a function can also be registered:

self.register_scheduled_metric("NAME", "unit", "description", interval, self.get_metric_value)

The registered callback returns None the metric is not sent.

Alternative, a metric can also be registered via the schedule_metric function decorator:

@schedule_metric("A", 10)
def current(self) -> float | None:
    """The current as measured by the power supply."""
    if self.device.can_read_current():
        return self.device.get_current()
    return None

In case of the decorator, the name of the metric is taken from the function name and the description from the doc string. Also in this case if the function returns None the metric is not sent.

Attention

Note that any scheduled metrics are by default retrieved in all states except the NEW, initializing, reconfiguring and ERROR state. In both the decorator and the registration function an optional allowed_states parameter can be passed to change this.