Prometheus

--prom :9124 hace que el colector sirva el formato de texto de Prometheus (text/plain; version=0.0.4) en GET /metrics en esa dirección. Haz scrape del colector: el agente no sirve exposición propia.

Familias del kernel

Las familias de la capa del kernel en el colector las renderiza el mismo código que ejecuta el agente — sus contadores acumulados, su histograma de ticks ocupados y sus ventanas móviles — alimentado con las muestras que recibió el colector. Un despliegue cuyo colector solo llega al agente por el relay sigue teniendo métricas que no dependen de quién hace scrape ni de cuándo.

Por encima de ellas el colector añade lo que solo tiene él: los gauges de la capa de la API de RouterOS, los valores de la etapa de derivación, sus contadores de detecciones y de huecos, y las familias de datos del equipo que salen de las /capabilities del agente.

El colector dimensiona su histograma mikroscope_cpu_busy_ticks a partir de 10 Hz fijos, no del agente conectado, para que la disposición de los buckets no cambie cuando se reconecta a un agente configurado de otra forma. La misma constante fija más cosas (leído del código, no medido), y frente a un agente por encima de 10 Hz cada una se desvía en la razón de cadencias. El anillo que hay detrás de las ventanas móviles sí sigue al agente: el colector lee la cadencia de su comprobación de salud y dimensiona el anillo a 60 s de ella, así que window="60s" abarca un minuto a cualquier cadencia. La media móvil de softnet que hay detrás de mikroscope_softnet_burst_samples_total no: su peso es 1/600, una memoria de 60 s a 10 Hz y menos por encima, así que la referencia de ráfagas del colector se estrecha cuanto más rápido muestrea el agente; el agente dimensiona la suya a partir de su cadencia real. Una línea de interrupción se poda de las familias top-K tras 36 000 muestras fuera de todo top-K: una hora a 10 Hz, 12 min a 50 Hz, 6 min a 100 Hz.

Trabajo de scrape

El del colector, y solo el del colector:

- job_name: "mikroscope"
  scrape_interval: 5s
  static_configs: [{ targets: ["<equipo del colector>:9124"] }]

Este único trabajo lleva todas las familias que pide el dashboard. Lo que solo un muestreador puede saber llega al colector como dato: el retraso de despertar y la duración de lectura de cada tick viajan en la propia muestra, y GET /sampler responde los contadores que no son por tick. No hay nada que contar dos veces ni lista de keep que mantener. Los intervalos de scrape y las versiones de Prometheus que se han usado están en el estado de las funciones.

Después, el dashboard. Al colector lo consulta Prometheus, así que no puede saber la dirección a la que pregunta Grafana: indícala en --grafana-datasource-url, o nombra en --grafana-datasource-uid una fuente de datos de Prometheus que ya tengas. Cuando Prometheus haya hecho unos cuantos scrapes:

export GRAFANA_TOKEN=…
mikroscope dashboards publish --prom :9124 --grafana http://grafana:3000 \
  --grafana-datasource-url http://prometheus:9090   # Prometheus tal como lo alcanza Grafana

Las mismas opciones --grafana en el colector publican en cada arranque, siempre que --prom sea su único destino con dashboard: junto a --influx u otro, las opciones de la fuente de datos se rechazan, así que publica Prometheus de esta forma. O impórtalo con dashboards import --store prometheus sobre una fuente de datos que ya tengas (Fuente de datos por destino).

Origen de cada familia

Familia	De dónde sale
todas las familias del tier de kernel	plegadas desde las muestras, con el mismo código que antes corría el agente
`mikroscope_tick_interval_seconds`, `_wake_latency_`, `_read_`	plegadas desde `dt_ns`, `wake_ns` y `read_ns` de cada muestra
`mikroscope_slipped_total`, `mikroscope_sampler_ticks_total`	el `/sampler` del agente, leído cada minuto
`mikroscope_trigger_fired_total`, `_suppressed_total`	lo mismo, una serie por condición configurada, presente a 0
`mikroscope_captures_held`, `mikroscope_capture_bytes`, `mikroscope_capture_budget_bytes`, `mikroscope_capture_bytes_served_total`, `mikroscope_capture_refused_total{reason}`	lo mismo: lo que el agente retiene, ha servido y ha rechazado
`mikroscope_api_`, `mikroscope_derived_`, `_collector_*`	lo propio del colector: el tier de API, la derivación, sus contadores

Las familias que se leen de /sampler son tan frescas como la cadencia de salud del colector, un minuto, no tan frescas como el scrape. Para contadores de disparos y capturas retenidas esa es la resolución correcta; todo lo que es por tick viaja en las muestras a ritmo completo.

Familias solo del colector

Contadores del colector

Familia	Tipo	Lleva
`mikroscope_collector_gaps_total`	counter	huecos del anillo que vio el colector: muestras perdidas entre extracciones
`mikroscope_collector_triggers_total{cause}`	counter	disparos de captura que lanzó el agente, por causa; presente en cuanto se ha visto uno
`mikroscope_collector_detections_total{rule}`	counter	eventos de detección por regla, cada una de las once reglas a 0 desde el primer scrape
`mikroscope_collector_bursts_total`	counter	muestras que la etapa de derivación marcó como ráfaga por debajo de la muestra

Las detecciones y las ráfagas son contadores para que quien solo usa Prometheus se entere de un evento aunque se pierda un scrape, y cada regla se renderiza a 0 desde el principio porque una familia que solo aparece tras su primer evento no se puede leer como «ninguno hasta ahora».

Familias derivadas

Familia	Tipo	Lleva
`mikroscope_derived_memory_pressure`	gauge	la escalera de escalada del asignador en la muestra más reciente, de 0 a 4
`mikroscope_derived_cycles_per_packet`	gauge	ciclos de PMU por paquete procesado, sumados sobre los núcleos; ausente sin PMU, en una muestra sin paquetes o tras un reinicio de contador
`mikroscope_derived_instructions_per_packet`	gauge	instrucciones de PMU por paquete, mismas condiciones
`mikroscope_derived_cache_misses_per_packet`	gauge	fallos de caché de PMU por paquete, mismas condiciones
`mikroscope_derived_packets_per_interrupt`	gauge	paquetes por interrupción de dispositivo; ausente cuando la fila del temporizador no estaba en el top-K de la muestra
`mikroscope_derived_fastpath_share{interface,direction}`	gauge	proporción por fast path del tráfico que la interfaz entrega a la CPU, entre las dos últimas lecturas de contadores; no es una proporción del cable; solo `rx` mientras `fp-tx-byte` no haya contado nunca

Son los valores de la muestra más reciente, un nivel en el momento del scrape; la serie completa está en los almacenes que guardan cada muestra. Lo que significa cada uno, y cuándo se omite, está en Valores derivados.

Familias de la API

Solo presentes cuando la capa de la API ha entregado una muestra; con --api-mode off o sin credenciales de la API no existe ninguna de estas familias.

Familia	Tipo	Lleva
`mikroscope_api_up`	gauge	1 mientras la capa de la API entrega muestras
`mikroscope_api_cpu_load`	gauge	el `cpu-load` de RouterOS desde `/system/resource`
`mikroscope_api_memory_bytes{kind}`	gauge	`free` y `total` desde `/system/resource`
`mikroscope_api_uptime_seconds`	gauge	uptime de RouterOS
`mikroscope_api_core_percent{cpu,kind}`	gauge	porcentaje `load`, `irq` y `disk` por núcleo desde `/system/resource/cpu`
`mikroscope_api_health{name}`	gauge	cada lectura de `/system/health`
`mikroscope_api_interface{interface,kind}`	gauge	`rx_bps`, `tx_bps`, `rx_pps`, `tx_pps` de `monitor-traffic`, más cada tasa de pérdidas que devolvió el router
`mikroscope_api_interface_info{interface,label,type,role,bridge,default_name}`	gauge	siempre 1; una serie por interfaz salida del inventario de configuración: su comentario, el tipo de RouterOS, sus listas de interfaces, su bridge y su nombre de fábrica
`mikroscope_api_interface_counter_total{interface,counter}`	counter	cada contador acumulado por puerto que devolvió el router, con el nombre de contador del propio RouterOS
`mikroscope_api_conntrack_entries`	gauge	el número de conexiones, cuando `--conntrack-every` lo pide

mikroscope_api_up nunca se renderiza como 0: antes de la primera muestra de la API, y cuando la capa está apagada, la familia no existe.
El número de conexiones, los contadores de puerto y las proporciones del fast path llegan con cadencias más lentas que el scrape. El colector guarda el último valor de cada uno entre lecturas, así que un scrape que cae entre dos lecturas sigue viendo la familia en vez de una serie que aparece y desaparece.

Inventario de interfaces

La capa de la API lee qué es cada interfaz — su comentario, el tipo de RouterOS, sus listas de interfaces, el bridge del que es puerto, su nombre de fábrica y su MTU — con tres lecturas solo de configuración al arrancar el colector y de nuevo cada --labels-every (5 min por defecto). En /metrics ese inventario es una serie info por interfaz.

Nada de eso es etiqueta de las series de tasas ni de contadores: el comentario lo edita una persona, y una etiqueta cambiada abriría una serie nueva para cada tasa y para cada uno de los sesenta y pico contadores de ese puerto en cada edición. Únelo en la consulta:

mikroscope_api_interface_counter_total * on(interface) group_left(label, type, role) mikroscope_api_interface_info

Toda interfaz del inventario tiene serie, tenga comentario o no. Un valor vacío de label es como Prometheus escribe «ninguno» —su modelo de datos trata una etiqueta con valor vacío como una que no existe—, así que todas las series de la exposición llevan los mismos nombres de etiqueta.
type dice qué significan los contadores de esa interfaz: un puerto ether de un bridge cuenta su cable, incluidas las tramas que el chip de switching reenvió por hardware, mientras que el bridge cuenta su lado de CPU. Ninguno es un subconjunto del otro — la mayor parte de lo que recibe un puerto puede conmutarse por hardware sin llegar nunca a la CPU (medido) —, así que no sumes un puerto y su bridge.
mikroscope_api_interface_counter_total tiene una serie por puerto y contador que el router informa: un puerto Ethernet informa varias veces más contadores que una interfaz bridge, VLAN, PPPoE, WireGuard, veth o loopback (contado). Un contador que un puerto no informa no tiene serie.
Una tasa de pérdidas que el router no devolvió no tiene kind, y monitor-traffic puede devolver las tasas de descarte sin ninguna clave de errores (verificado).
Las claves que se leen como enteros pero no cuentan nada — mtu, actual-mtu, l2mtu, max-l2mtu, sfp-shutdown-temperature — son tamaños y configuración y no tienen serie de contador; el MTU forma parte del inventario.

Familias de datos del equipo

La exposición del colector lleva las familias de datos del equipo a partir de lo que obtuvo de /capabilities: mikroscope_device_info, los techos que publica la placa (mikroscope_thermal_critical_celsius, mikroscope_thermal_polling_seconds, mikroscope_cpu_frequency_limit_hertz, mikroscope_cpu_frequency_step_hertz, mikroscope_cpu_frequency_governor_info, mikroscope_cpu_frequency_cluster, mikroscope_self_cgroup_memory_max_bytes) y mikroscope_source_cadence_hz{source,reason}. Consulta Datos del equipo.

Escrito y mantenido por José Manuel Requena Plens (jmrplens)jmrp.ioGitHub