fn_registry/functions/infra/format_prom_exposition.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
format_prom_exposition	function	go	infra	1.0.0	pure	func FormatPromExposition(samples []PromSample, timestampMs int64) string	Convierte un slice de PromSample en texto con formato Prometheus exposition (una linea por sample: name{k="v"} value timestampMs). Ordena labels por clave (salida determinista), escapa backslash/comilla/newline en valores de label, sanitiza el nombre de metrica a [a-zA-Z0-9_:], formatea el valor con FormatFloat 'g'. Si timestampMs<=0 omite el timestamp; sin labels omite las llaves. Funcion pura.	prometheus exposition metrics format fleet-metrics infra monitoring		PromSample_go_infra		false		sort strconv strings	name desc samples slice de PromSample a serializar; cada uno aporta una linea de exposition name desc timestampMs timestamp en milisegundos epoch a adjuntar a cada linea; si es <=0 se omite el campo timestamp	string con el texto exposition Prometheus, una linea por sample terminada en \n. String vacio si samples esta vacio.	true	TestFormatPromExposition	functions/infra/format_prom_exposition_test.go	functions/infra/format_prom_exposition.go

Ejemplo

samples := []PromSample{
    {Name: "node_load1", Value: 0.42},
    {Name: "node_cpu_core_percent", Labels: map[string]string{"core": "0"}, Value: 12.5},
    {Name: "node_disk_used_bytes", Labels: map[string]string{"mount": "/"}, Value: 1024},
}
text := FormatPromExposition(samples, 1700000000000)
// node_load1 0.42 1700000000000
// node_cpu_core_percent{core="0"} 12.5 1700000000000
// node_disk_used_bytes{mount="/"} 1024 1700000000000

Cuando usarla

Cuando tengas un slice de PromSample (tipicamente de collect_host_metrics) y necesites serializarlo al formato de texto que entienden los endpoints de ingestion Prometheus (/api/v1/import/prometheus de VictoriaMetrics, pushgateway, etc.). Es el paso intermedio del capability group fleet-metrics: colecta -> formatea -> empuja. Al ser pura y determinista, tambien sirve para snapshots reproducibles y golden tests.

Gotchas

• El timestamp es milisegundos epoch (Prometheus exposition usa ms), no segundos. Pasa time.Now().UnixMilli().
• timestampMs <= 0 (incluido 0) omite el campo timestamp por completo.
• La label instance NO se gestiona aqui: si esta en Labels se serializa tal cual, pero la convencion del grupo es dejarla fuera y añadirla en el push via extra_label.
• No agrupa por nombre ni emite lineas # HELP / # TYPE: salida cruda de series, suficiente para ingestion pero no para un endpoint /metrics canonico.
• El nombre de metrica se sanitiza de forma destructiva: node.cpu-percent! se convierte en node_cpu_percent_. Nombra bien los samples en origen.