| 1 | # go.d Helper Packages |
| 2 | |
| 3 | This directory contains go.d-specific reusable helpers. go.d collectors also use |
| 4 | shared Go helpers from `src/go/pkg/*` and logging helpers from `src/go/logger`. |
| 5 | |
| 6 | For new go.d collectors, start with |
| 7 | `src/go/plugin/go.d/docs/how-to-write-a-collector.md`. For when and why to use |
| 8 | helper packages, read `src/go/plugin/go.d/docs/helper-packages.md`. |
| 9 | |
| 10 | ## V2 Metrics And Charts |
| 11 | |
| 12 | New go.d collectors MUST use framework V2: |
| 13 | |
| 14 | - `src/go/pkg/metrix` for metric instruments and `CollectorStore`. |
| 15 | - `src/go/plugin/framework/charttpl` for `charts.yaml` templates. |
| 16 | - `src/go/plugin/framework/chartengine` for chart-template runtime behavior. |
| 17 | - `src/go/plugin/framework/collectorapi` for `CollectorV2` registration and |
| 18 | lifecycle contracts. |
| 19 | |
| 20 | If an existing V1 collector is being migrated, use |
| 21 | `src/go/plugin/go.d/docs/migrate-v1-to-v2.md`. |
| 22 | |
| 23 | ## Common Collector Helpers |
| 24 | |
| 25 | - `src/go/plugin/go.d/pkg/ndexec` runs external commands. |
| 26 | - `src/go/plugin/go.d/pkg/iprange` parses and checks IP ranges. |
| 27 | - `src/go/plugin/go.d/pkg/logs` helps parse application log files. |
| 28 | - `src/go/pkg/matcher` provides selector/matcher implementations. |
| 29 | - `src/go/pkg/confopt` provides duration and tri-state config option types. |
| 30 | - `src/go/pkg/web` provides HTTP client configuration helpers. |
| 31 | - `src/go/pkg/prometheus` parses Prometheus endpoints; use it with |
| 32 | `src/go/pkg/web`. |
| 33 | - `src/go/pkg/tlscfg` provides TLS support. |
| 34 | - `src/go/plugin/go.d/pkg/sqlquery` provides reusable SQL row/query helpers. |
| 35 | - `src/go/plugin/go.d/pkg/socket` provides TCP/UDP/Unix line-protocol clients. |
| 36 | - `src/go/plugin/go.d/pkg/cloudauth` provides shared cloud authentication |
| 37 | config/credential helpers. |
| 38 | - `src/go/plugin/go.d/pkg/pinger` provides shared ping probing and |
| 39 | latency/jitter calculations. |
| 40 | |
| 41 | ## Legacy V1 Helpers |
| 42 | |
| 43 | - `src/go/pkg/stm` converts structs into `map[string]int64`. This is V1-shaped |
| 44 | and MUST NOT be used as the metric path for new V2 collectors. It MAY be |
| 45 | useful while maintaining legacy V1 collectors or building temporary migration |
| 46 | parity tests that are removed from the final runtime path. |
| 47 | - `src/go/plugin/go.d/pkg/oldmetrix` provides V1 metric vector helper types |
| 48 | used by existing V1 collectors. New V2 collectors SHOULD use |
| 49 | `src/go/pkg/metrix` instead. |