Referencia de plantillas

Una plantilla es un archivo YAML con tres secciones: tasks, agents (o modules de nivel superior) y transfer. El parseo es estricto: un nombre de campo desconocido es un error, así que las erratas fallan rápido.

Ejemplo mínimo completo

tasks:
  - name: disk
    type: local
    local: { command: "df --output=pcent / | tail -1 | tr -d ' %'" }
    variable: disk_pct

agents:
  - name: "myhost"
    group: "Servers"
    interval: 300
    modules:
      - name: "Disk used"
        type: generic_data
        data: "{{ disk_pct }}"
        unit: "%"

transfer:
  mode: tentacle
  tentacle: { address: "pandora.example.com" }

tasks: — lista ordenada de ejecuciones

Las tareas se ejecutan secuencialmente, en el orden declarado. Una tarea puede usar variables producidas por tareas anteriores en cualquiera de sus campos de cadena (encadenamiento: login → token → petición autenticada).

Campo	Obligatorio	Descripción
name	sí	Identificador único de tarea (usado en los logs)
type	sí	request o local
request	si type=request	Especificación de petición HTTP (abajo)
local	si type=local	Especificación de comando (abajo)
filter	no	Filtro de extracción (abajo). Sin él, se almacena la salida bruta recortada
variable	no	Nombre bajo el que almacenar el resultado. Debe coincidir con [A-Za-z_][A-Za-z0-9_]*

request: (HTTP)

Campo	Obligatorio	Por defecto	Descripción
url	sí	—	URL de destino. Admite {{ }}
method	no	GET	GET, POST, PUT, DELETE, PATCH, HEAD
headers	no	—	Mapa de cabecera → valor. Los valores admiten {{ }}
body	no	—	Cuerpo de la petición. Admite {{ }}
timeout	no	30	Segundos
skip_tls_verify	no	false	Acepta certificados TLS inválidos

Una respuesta con estado fuera de 2xx es un fallo de tarea. Los cuerpos de respuesta están limitados a 10 MiB.

local: (comando)

Campo	Obligatorio	Por defecto	Descripción
command	sí	—	Se ejecuta con /bin/sh -c. Admite {{ }}. El $ de shell no se toca (awk '{print $5}' funciona tal cual)
timeout	no	30	Segundos; el proceso se mata al expirar

Un código de salida distinto de cero es un fallo de tarea (stderr se incluye en el log).

filter: — extracción de valores

Campo	Obligatorio	Descripción
type	sí	jq o regexp
expression	sí	La expresión del filtro

Cardinalidad del resultado (ambos tipos de filtro): 0 coincidencias → variable sin definir (semántica de fallo de tarea) · 1 coincidencia → escalar · N coincidencias → array.

jq — la salida de la tarea debe ser JSON válido. La expresión se ejecuta con un motor jq incorporado (no se necesita el binario jq). Cada valor que emite la expresión es un elemento: .token → escalar, .items[].name → array, .items[] → array de objetos.

regexp — sintaxis RE2 de Go (sin backtracking, sin lookahead) aplicada a la salida bruta. Por coincidencia:

Forma del patrón	Cada coincidencia se convierte en
Sin grupo de captura (cpu\d)	La coincidencia completa (cadena)
Un grupo sin nombre ((\d+)%)	El grupo de captura 1 (cadena)
2+ grupos sin nombre ((a)(b)(c))	Array posicional: [[a, b, c], ...]
Grupos con nombre ((?P<mount>...))	Un objeto: nombre del grupo → texto capturado

Usa (?m) para patrones multilínea anclados por línea y (?i) para coincidencia sin distinción de mayúsculas. No mezcles grupos con nombre y sin nombre en la misma regexp si quieres un acceso predecible; la forma con nombre solo expone los campos con nombre.

Coerción de tipos: las cadenas extraídas con aspecto numérico se convierten en números (recursivamente, incluyendo campos de objetos), así que la aritmética funciona con ellas.

Variables y expresiones {{ }}

Cualquier campo de cadena de tareas (después de la tarea que la produce), agentes y módulos puede incluir {{ expresión }}. Las expresiones se evalúan con expr-lang contra el almacén de variables.

Expresión	Resultado
{{ token }}	Valor de la variable
{{ 100 - disk_pct }}	Aritmética
{{ names[0] }}	Indexado de array
{{ value.mount }}	Campo de objeto (dentro de for_each)
{{ names[index] }}	Array paralelo sincronizado (dentro de for_each)

Referenciar una variable no definida es un error → el módulo afectado se omite (o la ejecución aborta bajo --strict).

agents: — un bloque por agente

Obligatorio a menos que uses modules: de nivel superior (ver el modo agent_plugin). Cada agente se convierte en un documento XML <agent_data>.

Campo	Obligatorio	Descripción
name	sí	Nombre del agente
modules	sí	Lista de bloques de módulo (al menos uno)
alias	no	Alias del agente
parent_agent_name	no	Agente padre
description	no	Descripción
version	no	Cadena de versión del agente
os_name, os_version	no	Identificación del SO
timestamp	no	Sobrescribe la marca de tiempo de los datos
address	no	IP/nombre de host
group	no	Grupo de destino
interval	no	Segundos (entero)
agent_mode	no	Modo del agente

Todos los campos de cadena admiten {{ }}.

modules: — bloques de módulo

Los bloques de módulo viven dentro de un agente, o a nivel superior (solo con transfer.mode: agent_plugin).

Campos de control (semántica del ejecutor, no se envían a Pandora):

Campo	Descripción
for_each	Nombre de variable array. El bloque se expande a un módulo por elemento; {{ value }} e {{ index }} quedan disponibles. Una variable escalar itera como array de 1 elemento. Para grupos de captura sin nombre con 2+ grupos, cada value es un array, así que puedes usar {{ value[0] }}. ¿Varios módulos por elemento? Escribe varios bloques con el mismo for_each
when	Expresión booleana expr-lang en bruto (sin {{ }}). Falso → módulo (o elemento) omitido. Dentro de for_each se evalúa por elemento y ve value/index. Ejemplo: when: 'not (value.mount matches "^/DB")'

Campos de datos — los dos obligatorios más el conjunto completo aceptado por el servidor de datos. Los valores pueden ser números o cadenas en YAML; todos admiten {{ }}:

Campo	Obligatorio	Descripción
name	sí	Nombre del módulo
type	sí	Tipo de módulo (generic_data, generic_proc, generic_data_string, async_data, ...)
data	no	Valor del módulo
description	no	Descripción
unit	no	Etiqueta de unidad
interval	no	Intervalo del módulo
tags	no	Etiquetas
module_group	no	Grupo de módulo
module_parent, module_parent_unlink	no	Relación de módulo padre
min_warning, max_warning, min_critical, max_critical	no	Umbrales numéricos
min_warning_forced, max_warning_forced, min_critical_forced, max_critical_forced	no	Variantes de umbral forzado
str_warning, str_critical	no	Umbrales por coincidencia de cadena
str_warning_forced, str_critical_forced	no	Umbrales de cadena forzados
warning_inverse, critical_inverse	no	Invertir la lógica del umbral
min, max	no	Rango de datos válido
post_process	no	Multiplicador aplicado por el servidor
disabled	no	Crear deshabilitado
status	no	Forzar estado
timestamp	no	Sobrescribe la marca de tiempo de los datos
custom_id	no	Identificador personalizado
critical_instructions, warning_instructions, unknown_instructions	no	Instrucciones del operador
quiet	no	Modo silencioso
min_ff_event, min_ff_event_normal, min_ff_event_warning, min_ff_event_critical	no	Umbrales FlipFlop
module_ff_interval, ff_type, ff_timeout, each_ff	no	Comportamiento FlipFlop
crontab	no	Planificación de módulo estilo cron
extra_data	no	Carga extra
alert_templates	no	Lista de nombres de plantillas de alerta a vincular

transfer: — entrega

Campo	Obligatorio	Descripción
mode	sí	tentacle, local o agent_plugin
tentacle.address	para tentacle	Dirección del servidor Pandora
tentacle.port	no (por defecto 41121)	Puerto tentacle
tentacle.binary	no	Ruta a tentacle_client si no está en $PATH
tentacle.extra_args	no	Argumentos extra del cliente tentacle (lista)
local.directory	para local	Directorio donde se escribe el archivo XML .data
module_prefix_separator	no (por defecto " - ")	Separador para el prefijado multi-agente en modo agent_plugin

Modo	Salida	Caso de uso
tentacle	XML <agent_data> completo enviado vía cliente tentacle	Ejecución remota (cron, Discovery)
local	XML <agent_data> completo escrito en un directorio	Ejecutarse en el propio servidor Pandora (apuntando al directorio de entrada), o depuración
agent_plugin	Solo fragmentos <module> impresos en stdout — el agente real añade la cabecera	Ejecutarse como module_plugin de un agente de software

Particularidades de agent_plugin:

• Se permite modules: de nivel superior sin ningún bloque agents: (y solo se permite en este modo).
• Con varios agentes definidos, cada nombre de módulo se prefija con <nombre_agente> - <nombre_módulo> para que los módulos no colisionen bajo el único agente real.

---