chartengine

chartengine compiles chart templates and builds deterministic chart plans (create, update, remove) from metrix.Reader snapshots.

Audience: ModuleV2 collector authors and framework contributors.

See also: charttpl (template DSL), metrix (metrics storage and read API).

Purpose

Collector-Facing Contract

For ModuleV2 collectors, the runtime integration expects:

Public API Surface

End-to-End Example (Single Flow)

// 1) Collector writes metrics.
store := metrix.NewCollectorStore()
meter := store.Write().SnapshotMeter("app")
meter.Counter("requests_total").ObserveTotal(100)

// 2) Engine loads chart template.
engine, err := chartengine.New(
	chartengine.WithEnginePolicy(chartengine.EnginePolicy{
		Autogen: &chartengine.AutogenPolicy{Enabled: false},
	}),
)
// handle err

err = engine.LoadYAML([]byte(`
version: v1
groups:
  - family: App
    metrics: [app.requests_total]
    charts:
      - id: requests
        title: Requests
        context: requests
        units: requests/s
        dimensions:
          - selector: app.requests_total
            name: requests
`), 1)
// handle err

// 3) Prepare plan from flattened+raw reader, emit it, then commit.
// ReadFlatten() is included even for templates with static dimensions
// because it is required for inferred dimensions, structured-family autogen,
// and is the standard pattern.
attempt, err := engine.PreparePlan(store.Read(metrix.ReadRaw(), metrix.ReadFlatten()))
// handle err
plan := attempt.Plan()
defer attempt.Abort()

err = chartemit.ApplyPlan(api, plan, chartemit.EmitEnv{
TypeID:      "plugin.job",
UpdateEvery: 1,
Plugin:      "example",
Module:      "example",
JobName:     "example",
})
// handle err
err = attempt.Commit()
// handle err

PreparePlan Lifecycle

PreparePlan executes a deterministic phase pipeline. Terms like "materialized state" and "route cache" are defined in the Engine State section below.

Reader Requirements

If inferred dimensions are present without flattened reader metadata, PreparePlan returns an explicit error.

Action Semantics

chartemit normalizes emitted action order by phase:

1. create chart/dimensions
2. update values
3. remove dimensions/charts

Routing and Collision Rules

Each metric series is routed to a chart and dimension based on template selectors. The following rules apply when routing conflicts arise:

[!WARNING] Cross-template chart ID collisions cause silent data loss — conflicting series are dropped with no error and no log entry. If metrics are missing, check for duplicate rendered chart IDs across template groups.

Lifecycle Defaults and Policy

Default lifecycle policy when template omits lifecycle:

Autogen Notes

MeasureSet autogen specifics:

• chartengine treats MeasureSet as a structured family, similar to StateSet, not as grouped scalar coincidence
• flattened MeasureSet inputs are expected to carry:
  • SourceKind = MetricKindMeasureSet
  • FlattenRole = FlattenRoleMeasureSetField
  • per-field metric names like <name>_<field>
  • a synthetic reserved field label (measure_field=<field>)
• the synthetic measure_field label is the authoritative field-identity channel; the per-field metric-name suffix remains for MetricMeta(name) compatibility
• gauge-like MeasureSet fields autogen with absolute algorithm behavior; counter-like MeasureSet fields autogen with incremental algorithm behavior

Reserved Flattened Label Keys

These label keys are treated specially by chartengine when consuming flattened structured-family or distribution inputs:

Notes:

• le, quantile, and measure_field are static reserved flattened-label keys in chartengine.
• StateSet is different: it does not use a global static key; it uses the base metric name itself as the synthetic flattened label key.
• These keys are part of the flatten contract between metrix and chartengine. Reusing them as ordinary user labels on those flattened inputs is not supported.

Runtime Metrics

chartengine self-instruments to a runtime store by default (disable with WithRuntimeStore(nil)).

Engine State