InfluxDB
Recolección INFLUXDB y Entrega INFLUXDB_WRITE. Una única Conexión Externa atiende las tres
generaciones del producto — 1.8, 2.x y 3.x —, porque no son protocolos distintos: es la misma API
HTTP, con direcciones, autenticación y lenguaje de consulta propios de cada versión.
| Versión | Lenguaje predeterminado | Direccionamiento | Autenticación |
|---|---|---|---|
| 1.8 | InfluxQL | database + retention policy | Token, o usuario y contraseña |
| 2.x | Flux | organización + bucket | Token de API |
| 3.x | SQL | database | Token de API |
Marcar la versión equivocada en la conexión es el error de configuración más común aquí, y aparece como HTTP 404 en todo — no como un mensaje sobre la versión. Probar Conexión lee la versión real del servidor y la muestra en el resultado, así que úselo antes de investigar cualquier otra cosa.
Conexión
| Campo | Para qué sirve |
|---|---|
| URL del servidor | Raíz del servidor, sin ruta (ej.: http://influxdb:8086) |
| Versión | Define las direcciones de la API, la autenticación y el lenguaje predeterminado |
| Organización (org) | Solo en 2.x. El token pertenece a una organización, y un nombre equivocado responde 404 sin decir que el problema es la org |
| Bucket predeterminado (2.x) / Database (1.8 y 3.x) | Destino predeterminado de lectura y escritura. La Recolección y la Entrega pueden sobrescribirlo |
| Retention policy | Solo en 1.8. Vacío usa la política predeterminada del database |
| Token de API | Obligatorio en 2.x y 3.x. En 1.8, solo si el servidor usa autenticación por token |
| Usuario / Contraseña | Solo en 1.8. Van como Basic — el CMS nunca usa los parámetros ?u=&p=, que dejarían la contraseña en el log de acceso del servidor |
| Validar certificado TLS / Certificado de la CA | Misma semántica que las demás conexiones: la CA solo es necesaria cuando el certificado viene de una CA interna |
| Consulta de prueba (Keep Alive) | Opcional. Vacía, el Keep Alive solo verifica que el servidor responda; completada, prueba también que el bucket responde a lecturas |
Probar Conexión corre en tres etapas, y cada una falla por un motivo distinto: /ping valida
URL, TLS y ruta (y devuelve la versión del servidor); el listado de buckets valida la credencial y la
existencia del bucket configurado; la consulta de prueba, si la hay, prueba la lectura.
Un token restringido a un único bucket — la configuración recomendada — no puede listar los demás. El CMS lo trata como normal: la segunda etapa se salta, y el resultado de la prueba indica que el listado no estaba disponible para esa credencial.
Recolección
La Consulta corre en el intervalo agendado y el resultado se vuelve mensajes, con el mismo Modo del Resultado de las Recolecciones SQL (todas las filas en un payload, o un mensaje por fila).
Aquí no existe el par Columna Clave + Comando Post-Recolección de las Recolecciones SQL:
InfluxDB no tiene “marcar fila como leída”. El recorrido incremental se hace por la ventana de
tiempo de la propia consulta — {{ultimaExecucao}} al inicio de la ventana hace que cada ejecución
continúe donde paró la anterior, sin repetir ni saltar muestras.
// Flux (2.x) — {{bucket}} resuelve al bucket de esta Recolección, o al predeterminado de la conexión
from(bucket: "{{bucket}}")
|> range(start: {{ultimaExecucao}})
|> filter(fn: (r) => r._measurement == "producao")
|> filter(fn: (r) => r._field == "temperatura")-- InfluxQL (1.8) — la misma idea, en el dialecto de esa versión
SELECT mean("temperatura") FROM "producao"
WHERE time > '{{ultimaExecucao}}' GROUP BY time(5m), "equipamento"Los placeholders disponibles son los mismos de la Recolección HTTP: {{ultimaExecucao}},
{{dataHoraAtual}}, Variables y Parámetros de Entrada, además de {{bucket}}. No hay bind
variable en ninguno de los tres lenguajes de InfluxDB — el valor se interpola en el texto de la
consulta, así que trate un Parámetro de Entrada aquí como lo que es: contenido que pasará a ser
parte del comando.
Cómo el resultado se vuelve JSON
Cada fila del resultado se vuelve un objeto. En Flux, la respuesta es el CSV anotado del propio
InfluxDB, convertido usando los tipos que él declara — un número vuelve como número, y el timestamp
preserva los nanosegundos (es texto ISO, no Date, justamente para no truncar). Las columnas de
control del protocolo (result, table) se descartan.
{ "_time": "2026-08-22T12:00:00Z", "_value": 900.5, "_field": "temperatura", "equipamento": "forno-1" }Entrega
La Entrega graba puntos en una serie. En InfluxDB el esquema nace de la escritura: measurement, tags y fields pasan a existir en la primera grabación — no hay tabla que crear antes.
Son dos modos:
Mapeado
El CMS arma el line protocol a partir de los campos del payload ya transformado. Para cada campo usted elige si es tag (metadato indexado, siempre texto, es por donde se filtra después) o field (el valor medido), y opcionalmente un nombre distinto en el destino.
Un payload que sea un array de objetos graba un punto por ítem — el camino natural para un lote que viene de una Recolección que emitió varias filas en un solo mensaje.
InfluxDB fija el tipo de un field en la primera escritura. Grabar 10 como entero hoy hace que
10.5 sea rechazado mañana con field type conflict, y corregirlo exige reescribir la serie. Por
eso el tipo Automático graba todo número como float; elija Integer solo cuando tenga la
certeza de que ese field nunca tendrá parte fraccionaria.
Line Protocol
El contenido del Modelo de Contenido (o, si está vacío, el propio payload transformado) se graba tal cual. Es la salida para formatos que el mapeo no expresa — y en él, el escape del line protocol pasa a ser responsabilidad de quien escribió la plantilla.
producao,equipamento=forno-1,linha=L2 temperatura=900.5,pecas=12iTimestamp y precisión
| Origen | Qué graba |
|---|---|
| Ahora | El instante del envío |
| Campo del payload | Un campo del mensaje (ISO 8601 o epoch entero en la precisión configurada) — úselo cuando el dato fue producido antes de llegar al CMS |
| Servidor | Nada: InfluxDB lo sella en la ingesta |
Ahora sella el punto con el reloj del CMS, pero la ventana de una consulta
(range(start: -1h), sin stop) termina en el now() del servidor InfluxDB. Si el reloj del
CMS está adelantado respecto al de InfluxDB, el punto cae en el futuro y desaparece de las
consultas hasta que el servidor lo alcance — el dato está grabado, pero no aparece. Mantenga
ambos relojes sincronizados por NTP; donde no sea posible, use el timestamp del Servidor.
Reducir la precisión no descarta filas, pero redondea el instante — y dos muestras que caigan
en el mismo instante redondeado, con las mismas tags, se vuelven una sola: InfluxDB sobrescribe
por measurement + tags + timestamp. Ante la duda, mantenga ns.
Qué bloquea el CMS en la consulta
La Consulta de la Recolección pasa por un guard propio, al guardar y otra vez antes de ejecutar. Lo que bloquea depende del lenguaje:
| Lenguaje | Bloqueado |
|---|---|
| Flux | to() (graba de vuelta en un bucket) y los paquetes de red, SQL externo y secretos: http, requests, sql, secrets, slack, pagerduty y similares |
| InfluxQL | DELETE, DROP, CREATE, ALTER, GRANT, REVOKE, KILL, SET, SELECT ... INTO y múltiples statements |
| SQL (3.x) | Todo DML, DDL y COPY (que graba archivo en el host del servidor); la consulta debe comenzar por SELECT, WITH, SHOW, EXPLAIN o DESCRIBE |
El texto dentro de comillas y los comentarios no cuentan: un measurement llamado http_requests o
una columna delete_count pasan normalmente.
Como en las bases SQL, esto es defensa en profundidad. La protección que de verdad importa es el permiso del token usado en la conexión: un token de solo lectura, restringido al bucket de la integración, vuelve todo lo demás redundante.
Entorno de prueba
El docker-compose.test.yml del proyecto — el entorno de prueba, separado del stack del producto —
trae un InfluxDB 2.7 listo para ejercitar los dos lados, con datos de ejemplo ya cargados:
docker compose -f docker-compose.test.yml up -d influxdbEn la Conexión Externa use http://host.docker.internal:8086 — dirección que vale tanto con el
cms-api en contenedor como ejecutándose nativo en la máquina —, org cms,
token el valor de INFLUX_TOKEN del .env de la raíz (generado por ./scripts/instalar.sh), bucket cms_leitura para la Recolección y cms_escrita para la Entrega.