---
title: "OCETS Canonical Metric Catalogue"
version: "1.1"
status: "Architecture Review Candidate"
release: "July 2026"
identifier: "OCETS-METRICS-1.1"
---

# OCETS Canonical Metric Catalogue

**Document:** 3 of 5  
**Type:** Normative Catalogue  
**Version:** 1.1  
**Status:** Architecture Review Candidate  
**Compatibility:** OCETS 1.1

## 1. Purpose

The Canonical Metric Catalogue defines the canonical metrics used by OCETS.

Each metric has one semantic meaning, one canonical unit, one value type, defined aggregation behavior, allowed labels, and lifecycle status.

## 2. Catalogue Rules

Metric names are canonical by themselves. OCETS telemetry SHALL NOT require a redundant label that repeats the metric name.

Generic electrical metrics SHALL be preferred. For example, battery charge or discharge power is represented as `active_power` at a battery Measurement Point with role-based sign semantics, not as a separate `battery_power` metric.

Forecast-generation models are outside OCETS v1.1. An externally generated forecast Observation MAY use an existing canonical Metric with `origin=forecast` only when it carries explicit `issued_at` and `valid_at` timestamps.

## 3. Metric Definition Fields

Each metric definition SHALL include:

| Field | Description |
|---|---|
| Name | Canonical metric identifier |
| Unit | Canonical storage unit |
| Type | Value type |
| Aggregation | Downsampling or rollup behavior |
| Description | Semantic definition |
| Labels | Allowed or expected labels |
| Source | Measured, derived, or operational |
| Status | Active, proposed, deprecated, or removed |
| Definition Version | Immutable semantic version of this definition |
| Introduced In | First OCETS release containing the definition |
| Deprecated In | OCETS release that deprecated it, where applicable |
| Removed In | OCETS release that removed it, where applicable |
| Replaced By | Canonical replacement metric, where applicable |

Every active v1.1 metric has `definition_version=1.0.0` and `introduced_in=1.1` unless its row explicitly states otherwise. Empty lifecycle fields mean not deprecated, not removed, and not replaced. Released definitions SHALL NOT be edited in place.

## 4. Value Types

| Type | Meaning |
|---|---|
| gauge | Instantaneous value |
| counter | Monotonically increasing value |
| state | Discrete state value |
| event | Point-in-time event |
| derived | Calculated value |

## 5. Aggregation Types

| Aggregation | Meaning |
|---|---|
| avg | Average over time window |
| min | Minimum over time window |
| max | Maximum over time window |
| sum | Sum over time window |
| delta | Difference over time window |
| last | Last known value |
| worst | Worst observed state |
| none | No aggregation permitted |

## 6. Common Allowed Labels

Common labels include:

- `plant`;
- `asset`;
- `device`;
- `measurement_point`;
- `role`;
- `energy_form`;
- `phase`;
- `direction`;
- `string`;
- `mppt`;
- `status`.

The Plant Registry Specification defines allowed values and placement rules for these labels.

## 7. Power Sign Convention

Instantaneous power metrics SHALL follow the role-based power sign convention defined in OCETS:

- PV generation/export is positive.
- Consumer/load power is positive.
- Battery charging is positive.
- Battery discharge/export is negative.
- Grid import into the plant is positive.
- Grid export from the plant is negative.

Energy counters SHOULD use direction-specific metric names and SHOULD NOT rely on signed accumulated counter values.

## 8. Electrical Metrics

| Name | Unit | Type | Aggregation | Labels | Source | Status | Description |
|---|---:|---|---|---|---|---|---|
| `active_power` | kW | gauge | avg,min,max | role, energy_form, phase, direction | measured or derived | active | Instantaneous active power with OCETS sign convention. |
| `reactive_power` | kvar | gauge | avg,min,max | role, energy_form, phase, direction | measured or derived | active | Instantaneous reactive power. |
| `apparent_power` | kVA | gauge | avg,min,max | role, energy_form, phase, direction | measured or derived | active | Instantaneous apparent power. |
| `power_factor` | percent | gauge | avg,min,max | role, energy_form, phase | measured or derived | active | Ratio of active power to apparent power. |
| `frequency` | Hz | gauge | avg,min,max | role, energy_form | measured | active | Electrical frequency. |
| `voltage` | V | gauge | avg,min,max | role, energy_form, phase, string, mppt | measured | active | Electrical voltage. |
| `current` | A | gauge | avg,min,max | role, energy_form, phase, string, mppt, direction | measured | active | Electrical current. |

## 9. Energy Metrics

| Name | Unit | Type | Aggregation | Labels | Source | Status | Description |
|---|---:|---|---|---|---|---|---|
| `energy_import` | kWh | counter | delta,sum | role, energy_form, direction | measured or derived | active | Electrical energy imported into a Measurement Point. |
| `energy_export` | kWh | counter | delta,sum | role, energy_form, direction | measured or derived | active | Electrical energy exported from a Measurement Point. |
| `energy_generated` | kWh | counter | delta,sum | role, energy_form | measured or derived | active | Electrical energy generated by a source. |
| `energy_consumed` | kWh | counter | delta,sum | role, energy_form | measured or derived | active | Electrical energy consumed by a load. |
| `energy_charged` | kWh | counter | delta,sum | role=battery, energy_form | measured or derived | active | Energy charged into storage. |
| `energy_discharged` | kWh | counter | delta,sum | role=battery, energy_form | measured or derived | active | Energy discharged from storage. |

## 10. Battery State Metrics

| Name | Unit | Type | Aggregation | Labels | Source | Status | Description |
|---|---:|---|---|---|---|---|---|
| `state_of_charge` | percent | gauge | avg,min,max,last | role=battery | measured or derived | active | Battery state of charge from 0 to 100 percent. |
| `state_of_health` | percent | gauge | avg,min,max,last | role=battery | measured or derived | active | Battery state of health from 0 to 100 percent. |
| `charge_limit` | kW | gauge | min,last | role=battery | measured or derived | active | Current maximum charging power limit. |
| `discharge_limit` | kW | gauge | min,last | role=battery | measured or derived | active | Current maximum discharging power limit. |

Battery voltage, current, temperature, and power SHALL use the generic metrics `voltage`, `current`, `temperature`, and `active_power` with battery Measurement Points and labels.

## 11. Environmental Metrics

| Name | Unit | Type | Aggregation | Labels | Source | Status | Description |
|---|---:|---|---|---|---|---|---|
| `temperature` | degC | gauge | avg,min,max | role, measurement_point | measured | active | Generic temperature measurement. |
| `ambient_temperature` | degC | gauge | avg,min,max | role=environment | measured | active | Ambient air temperature. |
| `irradiance` | W_per_m2 | gauge | avg,min,max | role=environment, plane | measured | active | Solar irradiance. |
| `wind_speed` | m_per_s | gauge | avg,min,max | role=environment | measured | active | Wind speed. |

## 12. Telemetry Health Metrics

| Name | Unit | Type | Aggregation | Labels | Source | Status | Description |
|---|---:|---|---|---|---|---|---|
| `device_available` | bool | state | worst,last | status | operational | active | Whether the device is available for telemetry. |
| `communication_status` | enum | state | worst,last | status | operational | active | Communication state for a device or path. |
| `collector_status` | enum | state | worst,last | status | operational | active | Collector process or service state. |
| `data_freshness` | s | gauge | max,last | role | operational | active | Age of the latest successful telemetry sample. |
| `timestamp_skew` | s | gauge | avg,max | role | operational | active | Difference between acquisition clock and reference time. |
| `mapping_error_count` | count | counter | delta,sum | role | operational | active | Count of mapping errors. |
| `validation_error_count` | count | counter | delta,sum | role | operational | active | Count of validation errors. |
| `pipeline_status` | enum | state | worst,last | role=collector, status | operational | active | End-to-end acquisition, mapping, buffering, and forwarding state. |
| `time_sync_status` | enum | state | worst,last | role=collector, status | operational | active | Whether the acquisition clock is synchronized to an approved reference. |
| `buffer_utilization` | percent | gauge | avg,max,last | role=collector | operational | active | Used capacity of the telemetry buffer from 0 to 100 percent. |
| `buffer_oldest_age` | s | gauge | max,last | role=collector | operational | Age of the oldest telemetry sample awaiting successful forwarding. |
| `storage_utilization` | percent | gauge | avg,max,last | role=collector, measurement_point | operational | active | Used capacity of storage required by the telemetry pipeline. |
| `storage_status` | enum | state | worst,last | role=collector, measurement_point, status | operational | active | Health of storage required by the telemetry pipeline. |
| `transport_error_count` | count | counter | delta,sum | role=collector | operational | active | Count of failures while forwarding telemetry upstream. |
| `collector_restart_count` | count | counter | delta,sum | role=collector | operational | Count of collector process restarts. Counter resets SHALL be handled as counter resets, not negative deltas. |
| `cpu_utilization` | percent | gauge | avg,max | role=collector | operational | active | Optional aggregate CPU utilization from 0 to 100 percent. |
| `memory_utilization` | percent | gauge | avg,max | role=collector | operational | active | Optional non-reclaimable memory utilization from 0 to 100 percent. |
| `host_temperature` | degC | gauge | avg,max | role=collector, measurement_point | operational | active | Optional edge-host component temperature; not an environmental measurement. |
| `external_power_available` | bool | state | worst,last | role=collector, measurement_point | operational | active | Optional indication that the edge collector's external power source is available. |
| `backup_power_status` | enum | state | worst,last | role=collector, measurement_point, status | operational | active | Optional backup-power operating state. |
| `backup_power_runtime` | s | gauge | min,last | role=collector, measurement_point | operational | active | Optional estimated remaining backup-power runtime. |

### 12.1 Operational State Values

State metrics SHALL use the following values:

| Metric | Allowed values |
|---|---|
| `collector_status`, `pipeline_status`, `storage_status` | `healthy`, `degraded`, `failed`, `unknown` |
| `communication_status` | `connected`, `degraded`, `disconnected`, `unknown` |
| `time_sync_status` | `synchronized`, `unsynchronized`, `unknown` |
| `backup_power_status` | `charging`, `charged`, `discharging`, `low`, `failed`, `unknown` |

`unknown` means that state cannot currently be determined. It SHALL NOT be treated as healthy. For worst-state aggregation, the order from best to worst is the order shown in each row, except that `unknown` is always worse than a known healthy or connected state and better than a known failed or disconnected state. Backup-power states SHALL use `last`; `worst` refers to `failed`, then `low`, for alert rollups.

## 13. Status Lifecycle

| Status | Meaning |
|---|---|
| active | Metric is part of OCETS v1.1. |
| proposed | Metric is under review and not required for conformance. |
| deprecated | Metric remains documented for migration but should not be used for new telemetry. |
| removed | Metric is no longer part of the catalogue. |

Changing a metric's meaning, canonical unit, or aggregation behavior is a breaking change unless a new metric name is introduced.

Deprecated metrics SHOULD remain documented until retained data and reference implementations have migrated.

## 14. Observation Metadata

Quality and provenance are properties of an Observation, not additional Metrics and not part of the Metric name. Every catalogue Metric SHALL be usable with the OCETS quality values `GOOD`, `BAD`, `UNCERTAIN`, `ESTIMATED`, `SUBSTITUTED`, `MISSING`, and `SIMULATED` and origins `device`, `calculated`, `forecast`, `estimated`, `manual`, and `simulated`.

Aggregation SHALL propagate Observation quality according to the OCETS Quality Model. Aggregating a Metric SHALL NOT erase provenance needed to distinguish measured, calculated, estimated, manual, forecast, or simulated data.