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.