Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions docs/Collecting Metrics/Chart Template Format.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1225,20 +1225,25 @@ All rules below produce semantic validation errors unless noted:
## Programmatic API

> [!NOTE]
> Most collectors ship a static `charts.yaml` and never touch the Go API. This section is for collectors that **build a chart template at runtime** — for example from discovery results or selected profiles — and return it from `CollectorV2.ChartTemplateYAML()`.
> Most collectors ship a static `charts.yaml` and never touch the Go API. This section is for collectors that **build a chart template at runtime** — for example from discovery results or selected profiles — and return it from `StaticChartTemplateProvider.ChartTemplateYAML()`.

For changing active membership, use native `chartengine.NewTemplateSet` and
`collectorapi.ChartTemplateSetProvider`; see [named active sets](https://github.com/netdata/netdata/blob/master/src/go/plugin/framework/chartengine/README.md#named-active-template-sets).
Static document composition remains supported through the API below.

The package exposes a small Go surface for decoding, cloning, and re-emitting templates:

| Function | Purpose |
|----------------------------------------------------|-------------------------------------------------------------------------------------------------|
| `DecodeYAML([]byte) (*Spec, error)` | Strict parse, apply decode-time defaults, then validate. The canonical read path. |
| `DecodeYAMLValidated([]byte) (*Spec, Validation, error)` | Decode plus immutable derived validation artifacts for runtime consumers such as chartengine. |
| `NormalizeGroups([]Group) ([]Group, error)` | Return owned, default-applied, validated native groups without serialization. |
| `Group.Clone() Group` | Typed deep copy of a group and everything nested under it. |
| `Spec.MarshalTemplate() (string, error)` | Validate (only) and serialize a runtime-built template to YAML. |

### Building a template at runtime
### Building a static document at runtime

`CollectorV2.ChartTemplateYAML()` returns a plain `string`, so build the template where the error can be handled — typically once during `Init` — and cache the result; `ChartTemplateYAML()` then returns the cached string. Assemble a `Spec` from `charttpl` types and serialize it with `MarshalTemplate`:
`StaticChartTemplateProvider.ChartTemplateYAML()` returns a plain `string`, so build the template where the error can be handled — typically once during `Init` — and cache the result; `ChartTemplateYAML()` then returns the cached string. Assemble a `Spec` from `charttpl` types and serialize it with `MarshalTemplate`:

```go
func buildChartTemplate(groups []charttpl.Group) (string, error) {
Expand Down
Loading
Loading