Updating Metric Values

After registering a metric, the metric does not yet have a value.
The value of a metric can be updated at any time and as frequently as needed by the plugin.

tip

If metrics are obtained from a sensor or an external API, determining the update frequency often requires balancing the need for up-to-date values with the performance cost of frequent sensor or API access.
It's good practice to expose these update frequencies as plugin settings, allowing users to configure them according to their preferences.

---

Updating Values

Metric values are passed to the IMoBroService, which provides several overloads to pass either simple values or MetricValues:

// Update the metric 'cpu_usage' with a new percentage value
_mobro.UpdateMetricValue("cpu_usage", 42.69);

// Update the metric 'cpu_usage' and include the DateTime when the value was measured
_mobro.UpdateMetricValue("cpu_usage", 42.69, DateTime.UtcNow);

// Update the metric 'cpu_usage' using a MetricValue struct
_mobro.UpdateMetricValue(new MetricValue("cpu_usage", DateTime.UtcNow, 42.69));

// Pass multiple metric values at once
IEnumerable<MetricValue> metricValues = ReadAllSensors();
_mobro.UpdateMetricValues(metricValues);

Updates are queued and sent to MoBro asynchronously in batches, so these calls return immediately and can be made from any thread.

note

• Metrics must be registered before their values can be updated. Updates for unregistered or unknown metrics are ignored by MoBro.
• null is a valid value for every metric and indicates that no value is currently available.

---

Value Restrictions

When updating metric values, the values must comply with the restrictions defined by the metric's MetricValueType (as specified in the MetricType). For example:

MetricValueType	Valid values
Numeric	42, 42.69, "42.69"
String	"Hello World" (HTML tags are removed, and values are truncated to 128 characters)
DateTime	DateTime.UtcNow, DateTimeOffset.Now, "2026-09-13T10:15:00Z"
Duration	TimeSpan.FromMinutes(5), "PT5M"
Boolean	true, "false"
Resource	"weather_icon_sunny" (the ID of a registered resource)

Refer to Reference: MetricType for the complete list.

caution

Passing a value that does not match the metric's MetricValueType throws a MetricValueValidationException. If this exception is not caught, the plugin is stopped. See Error Handling.

---

Numerical Values

For numerical metrics, the value must be provided in the base unit defined by the metric's MetricType. MoBro handles all unit conversions.

For example:

• CoreMetricType.Data expects bytes. Pass 8_000_000_000 for 8 GB, not 8.
• CoreMetricType.Usage expects a percentage between 0 and 100, not a fraction between 0 and 1.
• CoreMetricType.Temperature expects degrees Celsius.