Voltimax Platform

Appearance

Metrics Generator Internals ​

This page covers the internal architecture of the metrics generator. For schema format and adding metrics, see Metrics Schema.

Generated Output ​

The generator produces several categories of C# files and Elasticsearch mappings from the registry definitions. All output goes to src/Voltimax.Iot.Contracts/Metrics/Generated/.

Per-domain files:

  • *Metric.g.cs - Static Metric instances for each metric in the domain
  • *Metrics.g.cs - Nullable property classes for deserialization, with ToEnumerable() for iteration
  • *MetricCatalog.g.cs - Lookup dictionaries by metric ID

Cross-domain files:

  • TelemetryFrame.g.cs - The main telemetry container aggregating all domain value collections
  • MetricCatalog.g.cs - Global catalog spanning all domains
  • Enum files - Unit.g.cs, MetricProfile.g.cs, MetricDomain.g.cs

Elasticsearch:

  • JSON component templates for each domain, mapping metric keys to their Elasticsearch types

Expansion Process ​

The generator uses a two-stage process:

  1. Parse: Load CompactRegistryModel from JSON - this matches the registry file structure directly
  2. Expand: Convert to MetricDefinitionModel instances, expanding scopes into individual metrics

A metric with "scopes": ["sum", "l1"] expands into two MetricDefinitionModel instances: ActivePower_Sum (key active_power, scope sum) and ActivePower_L1 (key active_power, scope l1). Metrics without scopes produce a single instance.

Each generator then takes the expanded models and produces its output file. The generators are independent - they can be run individually or all together via GenerateCommand.

Generator Structure ​

The generators live in tools/Voltimax.Iot.Tools/Schema/Metrics/. The key components:

  • Commands/ - CLI command implementations (GenerateCommand, GenerateDocsCommand, ValidateCommand)
  • Generators/ - One generator per output type (definitions, values, catalogs, telemetry frame, enums, domain enum)
  • Models/ - CompactRegistryModel (mirrors JSON) and MetricDefinitionModel (expanded, used by generators)

Configuration ​

The metrics.json root file defines shared enums (units, profiles) and the path to the registries directory. Enum values defined here are generated as C# enums with [JsonConverter] attributes for string serialization.

  • Metrics Schema - schema format, ID conventions, adding metrics
  • Data Model - metric keys, units, asset types, and profiles