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 text view.
Place in the runtime
flowchart TB
producers["cache, server, source, rescan, mesh, 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.
- Source outbound limiter metrics must not expose raw upstream hosts.
- 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.render.go: Prometheus text exposition.values.go: low-cardinality snapshot value accumulation.spec.go: shared observable metric registration.push.go: VictoriaMetrics import path.
Operational notes
Use /metrics/{core,cache,errors,rescan,ygg} for human-readable diagnostics. The Yggdrasil group is available only
while the mesh is running; it stays aggregate-only unless internal metrics are also enabled for the listener. Rescan
snapshots include source outbound request and limiter-wait signals, plus version failure phase counters. Enable
/metrics/internal only when a scraper or trusted internal network needs the full exposition.
Documentation
¶
Index ¶
- func RegisterSpecs(meterObj metric.Meter, specArr []SpecObj, observeFunc func() ([]int64, bool)) (metric.Registration, error)
- 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)
- type SpecObj
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterSpecs ¶ added in v0.4.0
func RegisterSpecs( meterObj metric.Meter, specArr []SpecObj, observeFunc func() ([]int64, bool), ) (metric.Registration, error)
RegisterSpecs creates instruments from the table and registers the shared callback.
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" GroupYgg Group = "ygg" 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. A nil receiver yields a noop provider, matching the nil tolerance of Enabled.
Source Files