Saltar al contenido principal
Reporter se distribuye como un solo binario con dos superficies, y RUN_MODE selecciona qué superficies sirve un proceso. La misma imagen se ejecuta como la API, como el worker de informes o como ambas. Detrás de ellas hay cuatro dependencias. Reporter lee tus bases de datos mediante un motor de extracción que se ejecuta dentro del proceso worker. No hay un servicio de extracción separado que desplegar.

Qué despliegas

Modos de ejecución

RUN_MODE=api sirve operaciones REST, /health y /version en SERVER_ADDRESS. RUN_MODE=worker consume la cola de comandos de informes y no tiene superficie REST. RUN_MODE=all ejecuta ambas superficies en un solo proceso. Un proceso sirve /health, /readyz y /metrics en HEALTH_PORT cuando la defines. Un worker sin HEALTH_PORT no tiene listener y termina al iniciar, y la imagen del worker define 8099. Usa all para el desarrollo local. En producción, despliega las dos superficies por separado, de modo que la generación de informes escale por su cuenta. El siguiente ejemplo define el puerto de health en los dos despliegues.

MongoDB

Ambas superficies usan el mismo despliegue de MongoDB. La superficie de la API escribe plantillas, informes y plazos. El worker actualiza un informe a medida que se completa. MONGO_HOST y MONGO_NAME son obligatorias al iniciar. En modo multi-tenant no son obligatorias cuando LICENSE_FILE_PATH está definida y STREAMING_ENABLED no es true.

RabbitMQ

Dos responsabilidades separadas comparten un broker.

La cola de comandos de informes

Esta cola lleva el trabajo desde la superficie de la API hasta el worker. RABBITMQ_EXCHANGE, RABBITMQ_GENERATE_REPORT_QUEUE y RABBITMQ_GENERATE_REPORT_KEY nombran el exchange, la cola y la routing key. La superficie de la API publica, así que necesita las tres, además de su conexión al broker: RABBITMQ_HOST, RABBITMQ_PORT_AMQP, RABBITMQ_DEFAULT_USER y RABBITMQ_DEFAULT_PASS. El worker consume de la cola y necesita esa misma conexión, además de RABBITMQ_GENERATE_REPORT_QUEUE. Los objetos del broker deben existir antes de que cualquiera de los dos servicios inicie. El canal es interno de Reporter. Para saber que un informe terminó, suscríbete a los eventos de negocio de más abajo, o consulta el informe periódicamente. Un worker que falla al procesar un mensaje lo reintenta hasta cinco veces con backoff, y luego lo rechaza sin volver a encolarlo. Vincula un dead-letter exchange a la cola de comandos, de modo que un informe rechazado llegue a un lugar donde puedas inspeccionarlo. Cuando el broker no responde, el worker sigue reintentando su suscripción, con backoff. Se suscribe de nuevo después de que el broker cierra el canal.

El exchange de eventos

Los eventos de negocio (template.*, report.*, deadline.*, regulatory.*) van a un exchange que nombras en RABBITMQ_REPORT_EVENTS_EXCHANGE. El valor lo configura el operador. El valor de referencia es reporter.events. Configura ese exchange, STREAMING_BROKERS y STREAMING_CLOUDEVENTS_SOURCE siempre que STREAMING_ENABLED=true. Con el streaming apagado, ambas superficies inician con normalidad y no publican nada.

Almacenamiento de objetos

Reporter usa un bucket compatible con S3, nombrado en OBJECT_STORAGE_BUCKET. Contiene dos tipos de objeto, cada uno bajo su propio prefijo:
  • la fuente de la plantilla, como templates/<templateId>.tpl
  • el informe renderizado, como reports/<templateId>/<reportId>.<format>
AWS S3, MinIO y SeaweedFS funcionan todos. En AWS S3, concede a la identidad con la que se ejecuta Reporter s3:ListBucket en el bucket, y s3:PutObject, s3:GetObject y s3:DeleteObject en sus objetos. Accede a SeaweedFS mediante su gateway S3. OBJECT_STORAGE_USE_PATH_STYLE=true es lo que esperan MinIO y SeaweedFS, y OBJECT_STORAGE_DISABLE_SSL permanece en false fuera del desarrollo local.

Retención de informes

Reporter conserva para siempre los archivos de informes y las presentaciones regulatorias. No tiene un endpoint de eliminación ni una configuración de retención, así que el bucket crece con tu volumen de informes. La única forma de que un archivo expire es una regla de ciclo de vida del almacén de objetos que tú configuras. Esa regla también elimina las presentaciones regulatorias aprobadas, que son el registro regulatorio de la institución. Las filas guardadas a partir de las cuales una corrección regulatoria vuelve a generar el borrador también se almacenan en reports/, así que una regla de expiración puede impedir que se corrija un borrador más antiguo.
Deja templates/ fuera del alcance: una regla que cubre todo el bucket también elimina las plantillas a partir de las cuales se renderizan tus informes.

Redis o Valkey

REDIS_HOST es obligatoria en la superficie de la API. Redis respalda el bloqueo de idempotencia en la creación de informes y la caché de esquemas de las fuentes de datos. El estado de idempotencia vive en Redis, no en la memoria del proceso, así que las réplicas de la API lo comparten.

Fuentes de datos

Reporter lee los datos de generación de informes desde fuentes de datos de PostgreSQL y MongoDB en su registro persistido. Créalas y adminístralas mediante la API de fuentes de datos. Un bloque opcional DATASOURCE_{NAME}_* siembra una entrada de registro administrada por el usuario al iniciar el Manager. Siembra la entrada solo cuando ese configName está ausente. Las ediciones y eliminaciones posteriores por la API tienen precedencia sobre el entorno. Tanto el Manager como el worker requieren la misma DATASOURCE_CRED_ENC_KEY persistente para proteger las credenciales del registro. Mantenla sin cambios a través de reinicios y despliegues, para que puedan seguir descifrando las credenciales almacenadas. Reporter también inicia sin ninguna configurada, y sirve plantillas, plazos y métricas.

Dimensionamiento del worker

RABBITMQ_NUMBERS_OF_WORKERS establece cuántos trabajos de informes ejecuta en paralelo un proceso worker. Para escalar horizontalmente, agrega réplicas de worker y dirígelas según la profundidad de la cola de comandos. La salida en PDF se renderiza mediante un pool de navegadores headless: PDF_POOL_WORKERS renderizados concurrentes, que por defecto es 2, cada uno acotado por PDF_TIMEOUT_SECONDS, que por defecto es 90. Dimensiona la memoria del worker según ese pool, no solo según las filas que lee un informe. Los demás formatos de salida no lo usan. Cada extracción de una fuente de datos también lleva límites. Son 20 tablas por fuente de datos y 50 campos por tabla. También cubren un plazo de 300 segundos y un tope de 256 MiB en los datos extraídos. Las variables ENGINE_* los cambian. Cada tabla también devuelve como máximo 150.000 filas y cada consulta agota su tiempo tras 300 segundos, salvo que la fuente de datos defina sus propios valores.

Modo de despliegue y TLS

DEPLOYMENT_MODE declara el tipo de despliegue: local, byoc o saas. En saas, exige TLS.
El modo SaaS exige TLS en cada dependencia. Si configuras DEPLOYMENT_MODE=saas, una URL en texto plano de MongoDB, RabbitMQ, Redis, o almacenamiento de objetos detiene el proceso. Se detiene antes de abrir una conexión en texto plano.
Deja ALLOW_INSECURE_TLS sin configurar en producción. Omite esas verificaciones, y el stack de desarrollo local es el único lugar donde corresponde usarla.

Verificaciones de inicio

Reporter valida su configuración al iniciar. Cada verificación de abajo detiene el proceso.
/readyz devuelve 503 hasta que se acepte una licencia y cada verificación de inicio pase. Mientras Reporter espera una respuesta del servicio de licencia, sigue intentando, permanece no listo y mantiene cerrado el puerto de la API.La API verifica Redis y, en modo single-tenant, MongoDB y RabbitMQ. El worker verifica MongoDB. En modo multi-tenant, la API y el worker verifican Tenant Manager en lugar de MongoDB y RabbitMQ. Después de la primera vez, una falla de dependencia compartida informa readiness degradada con HTTP 200. El consumidor, los dispatchers del outbox, el disparador de plazos y el reaper de informes solo empiezan después de que las verificaciones de inicio pasan.

Actualizaciones continuas

SIGTERM no cambia la readiness. Los listeners siguen atendiendo durante el drain, y el worker deja de recibir mensajes nuevos. La detención ocurre después del drain. Reserva tiempo suficiente para el renderizado de informe más largo. Consulta la referencia de salud y readiness para el contrato de sondas y la referencia de configuración BYOC para el ciclo de vida compartido de detención, incluidos SHUTDOWN_DRAIN_DELAY y SHUTDOWN_TIMEOUT.

Próximos pasos

Variables de entorno

Todas las variables de Reporter, por categoría.

Configuración de BYOC

Los bloques de configuración que comparten todos los productos de Lerian.

Salud y readiness

El contrato de las sondas y qué significa cada respuesta.

Conectar Reporter con Midaz

Apunta Reporter a una base de datos de Midaz y renderiza tu primer informe.