RUN_MODE selecciona qué superficies sirve ese binario: api, worker o all. La API y el worker son dos roles del mismo programa, no dos productos. Comparten una compilación, una versión y un release.
Eliges una topología en el momento del despliegue configurando una variable de entorno.
Dos superficies, un binario
all cuando un solo proceso es suficiente, la opción habitual para el desarrollo local y los despliegues pequeños. Separa los roles en dos unidades desplegables cuando la generación de informes necesite escalar por su cuenta. Renderizar un PDF grande cuesta mucho más que aceptar la solicitud que lo pidió. Los despliegues separados permiten dimensionar cada lado según su propia carga.
El recorrido de un informe
1
La API acepta la solicitud
Un
POST a /v1/reports indica una plantilla y sus filtros. Reporter toma primero un bloqueo de idempotencia. La clave del bloqueo es el encabezado X-Idempotency cuando envías uno, y un hash del cuerpo de la solicitud cuando no. Reporter rechaza un duplicado que todavía está en curso. Un duplicado de una solicitud completada repite el informe original y marca la respuesta como una repetición.2
La API valida y persiste
Reporter carga el mapa de campos y el formato de salida de la plantilla. Luego verifica los campos de filtro contra el esquema de cada fuente de datos, y escribe el informe con estado
Processing.3
La API encola el trabajo
Publica un mensaje de comando en la cola interna de RabbitMQ y responde
201 Created con el informe en Processing. Quien hizo la llamada no tiene nada más que hacer. El renderizado aún no empezó.4
El worker renderiza
El worker consume el comando. Omite el comando si el informe ya llegó a un estado terminal. Carga la plantilla desde el almacenamiento de objetos y extrae los datos de cada fuente de datos. Renderiza el documento y lo convierte a PDF cuando el formato lo requiere. Sube el artefacto.
5
El worker resuelve el estado
Escribe
Finished, Partial o Error, o Draft para una presentación regulatoria, y emite el evento correspondiente. La operación de descarga entrega el artefacto de un informe Finished o Final, y de un Draft sin campo obligatorio en blanco.La cola entre ambas
La API y el worker se comunican mediante una cola de RabbitMQ que lleva los comandos de informes en una sola dirección, con una dead-letter queue detrás. Esta cola funciona como plomería interna entre las dos superficies del mismo binario. No es un punto de integración, no lleva ningún contrato sobre el que se recomiende construir, y su exchange, su cola y su routing key son todos configurados por el operador. Los eventos de negocio son un canal separado. Reporter los publica en su propio exchange, que el operador configura y que el valor de referencia del despliegue llama
reporter.events. Cada emisión ocurre después del commit de la base de datos y nunca hace fallar el trabajo que la produjo. Los eventos de alto valor pasan por un outbox duradero en lugar de una publicación directa, de modo que una interrupción del broker los retrasa en lugar de perderlos.
Extracción de datos
El worker accede a tus bases de datos mediante su motor de extracción incorporado, sin consultas escritas a mano y sin ningún salto de red hacia un servicio separado. El motor limita cada extracción de una fuente de datos. Los valores predeterminados permiten 20 tablas por fuente de datos y 50 campos por tabla. Los fallos no terminan la ejecución. Un informe cuyas secciones tienen éxito parcial se renderiza con lo que tiene. Queda resuelto como
Partial y registra qué secciones fallaron.
Almacenes y artefactos
El almacenamiento de objetos es compatible con S3: Reporter habla el protocolo S3 y cualquier servicio que lo responda funciona como destino. Las fuentes de las plantillas quedan bajo el prefijo
templates/, y los artefactos renderizados bajo reports/, indexados por el identificador de la plantilla y del informe, con el formato de salida como extensión. Reporter no aplica ninguna expiración propia, así que la retención es una política de ciclo de vida que defines en el bucket.
Reporter y Midaz
Midaz es una fuente de datos para Reporter, no una dependencia en tiempo de ejecución. Registras una base de datos de Midaz de la misma forma que cualquier otra base de datos PostgreSQL. Las plantillas la dirigen mediante el
configName que eligió el operador.
De esto se siguen dos consecuencias. Reporter arranca y sirve plantillas, plazos y métricas sin ninguna fuente de datos configurada, de modo que una interrupción de Midaz nunca detiene la ejecución de Reporter. Y el mismo despliegue puede generar informes sobre Midaz, sobre tus propias bases de datos, o sobre ambas en una misma plantilla.
Apunta Reporter a una réplica de lectura donde exista una. La vía de extracción solo lee, pero la carga de consultas de un informe pesado es real, y una réplica la mantiene fuera de la vía de escritura del ledger.
Consulta Cómo conectar Reporter con Midaz para conocer las variables, la convención de
configName y cómo confirmar que la fuente es visible.Salud y readiness
Ambas superficies exponen
/health y /readyz antes de la autenticación, así que las sondas las alcanzan sin necesidad de un token. La sonda /health responde 503 hasta que la autosonda de inicio se completa correctamente. Esto permite que un orquestador reinicie un pod que no pudo alcanzar sus dependencias al arrancar. La sonda /readyz informa las dependencias que esa superficie realmente usa, y su respuesta indica en qué modo de despliegue se ejecuta el proceso. La superficie de la API también sirve /version con la procedencia de la compilación.
Consulta la referencia de salud y readiness para conocer el contrato de sondas compartido entre los productos de Lerian.
Próximos pasos
Conceptos centrales
Plantillas, fuentes de datos, informes, plazos y los estados del informe.
Variables de entorno
Todos los ajustes que dan forma a un despliegue de Reporter.