README
¶
mod/telemetry
mod/telemetry collects runtime metrics snapshots and optionally pushes them to VictoriaMetrics. The server exposes
selected metric groups as JSON and, when enabled, a full Prometheus/OpenMetrics text view.
Place in the Runtime
flowchart LR
producers["cache, server, rescan, errors"] --> telemetry["mod/telemetry"]
telemetry --> json["/metrics/* JSON"]
telemetry --> prom["Prometheus text"]
telemetry --> push["VictoriaMetrics push"]
Responsibilities
- Register metric producers from runtime packages.
- Build stable metric snapshots for HTTP handlers.
- Format selected data as JSON metric groups.
- Format the internal Prometheus text exposition.
- Push metrics to VictoriaMetrics when configured.
Contracts
- Metric labels must stay low-cardinality. Do not label by arbitrary key, version, URL, or request id.
- Snapshot collection must be bounded and must not block hot serving paths for long.
- Push failures are non-fatal. They should be visible in logs and error metrics, not crash the process.
- Public JSON metric groups should remain understandable to an operator without Prometheus tooling.
Important Files
obj.go: telemetry object and producer registry.snapshot.go: collection flow.prometheus.go: text exposition.push.go: VictoriaMetrics import path.
Operational Notes
Use /metrics/{core,cache,errors,rescan} for human-readable diagnostics. Enable /metrics/internal only when a
scraper or trusted internal network needs the full exposition.
Documentation
¶
Index ¶
- type Group
- type Obj
- func (obj *Obj) Close(ctx context.Context) error
- func (obj *Obj) Enabled() bool
- func (obj *Obj) GroupValues(group Group) (map[string]float64, bool)
- func (obj *Obj) InternalOM() ([]byte, bool)
- func (obj *Obj) Meter(group Group) metric.Meter
- func (obj *Obj) MeterProvider() metric.MeterProvider
- func (obj *Obj) Start(ctx context.Context)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group string
Group defines the metric groups; public values match the JSON routes /metrics/<group>.
const ( GroupCore Group = "core" GroupCache Group = "cache" GroupRescan Group = "rescan" GroupErrors Group = "errors" GroupInternal Group = "internal" )
Groups separate public series from the internal exposition. Core collects ogen and unknown scopes, internal holds push and Go runtime self-metrics.
type Obj ¶
type Obj struct {
// contains filtered or unexported fields
}
Obj owns the SDK state, prebuilt Prometheus snapshots and the optional push to VictoriaMetrics.
func New ¶
New builds telemetry from validated config. When no exposure method is enabled, it returns a disabled noop provider without SDK allocation or loops.
func (*Obj) Close ¶
Close stops the loops and shuts down the SDK provider. The final push is skipped: snapshots are cumulative, losing one tick does not change the counter total.
func (*Obj) GroupValues ¶
GroupValues returns the prebuilt map of metric name -> aggregated value for a public group. ok=false when telemetry is disabled or the group is unknown; before the first build the map is empty.
func (*Obj) InternalOM ¶
InternalOM returns the prebuilt full Prometheus text document across all groups. ok=false when telemetry is disabled; before the first build an empty document is returned.
func (*Obj) Meter ¶
Meter returns a group meter for producers such as cache, rescan and errors. Metric names and attributes must stay low-cardinality: key, version and raw path are never recorded.
func (*Obj) MeterProvider ¶
func (obj *Obj) MeterProvider() metric.MeterProvider
MeterProvider returns the provider to pass into ogen via api.WithMeterProvider.
Source Files