RUN_MODE seleciona quais superfícies esse binário serve: api, worker, ou all. A API e o worker são dois papéis do mesmo programa, não dois produtos. Eles compartilham um build, uma versão, e um release.
Você escolhe uma topologia no momento do deploy, definindo uma variável de ambiente.
Duas superfícies, um binário
all quando um processo é suficiente, o que é a escolha usual para desenvolvimento local e deployments pequenos. Divida os papéis em dois deployables quando a geração de relatórios precisar escalar por conta própria. Renderizar um PDF grande custa muito mais do que aceitar a requisição que o pediu. Deployments separados permitem dimensionar cada lado para a própria carga.
O caminho que um relatório percorre
1
A API aceita a requisição
Um
POST para /v1/reports nomeia um template e os filtros dele. O Reporter obtém um lock de idempotência primeiro. A chave do lock é o header X-Idempotency quando você envia um, e um hash do corpo da requisição quando você não envia. O Reporter rejeita uma duplicata que ainda está em andamento. Uma duplicata de uma requisição concluída repete o relatório original e marca a resposta como uma repetição.2
A API valida e persiste
O Reporter carrega o mapa de campos e o formato de saída do template. Em seguida, ele verifica os campos de filtro contra o schema ativo de cada fonte de dados, e grava o relatório com status
Processing.3
A API enfileira o trabalho
Ela publica uma mensagem de comando na fila interna do RabbitMQ e responde
201 Created com o relatório Processing. Quem chamou não precisa fazer mais nada. A renderização ainda não começou.4
O worker renderiza
O worker consome o comando. Ele pula o comando se o relatório já se consolidou como
Finished ou Error. Ele carrega o template do armazenamento de objetos e extrai os dados de cada fonte de dados. Ele renderiza o documento e o converte para PDF quando o formato exige. Ele envia o artefato.5
O worker consolida o estado
Ele grava
Finished, Partial, ou Error e emite o evento correspondente. A operação de download entrega o artefato assim que o relatório está Finished.A fila entre elas
A API e o worker se comunicam por uma fila do RabbitMQ que carrega comandos de relatório em uma direção, com uma dead-letter queue atrás dela. Essa fila funciona como infraestrutura interna entre as duas superfícies do mesmo binário. Ela não é um ponto de integração, não carrega nenhum contrato sobre o qual você deveria construir, e a exchange, a fila, e a routing key dela são todas configuradas pelo operador. Eventos de negócio são um canal separado. O Reporter os publica na própria exchange deles, que o operador configura e que o valor de referência do deployment nomeia como
reporter.events. Toda emissão acontece depois do commit no banco de dados e nunca falha o trabalho que a produziu. Eventos de alto valor passam por um outbox durável em vez de uma publicação direta, então uma indisponibilidade do broker os atrasa em vez de perdê-los.
Extração de dados
O worker não conversa com os seus bancos de dados por meio de consultas escritas à mão. Ele executa o motor de extração embarcado dele, sem um salto de rede para um serviço separado. O motor limita cada execução. Os padrões permitem 10 fontes de dados por relatório, 50 tabelas por fonte de dados, e 200 campos por tabela. Eles também permitem quatro fontes de dados extraídas em paralelo, e um prazo de cinco minutos para a extração inteira. Falhas não encerram a execução. Um relatório cujas seções têm sucesso parcial renderiza a partir do que tem. Ele se consolida como
Partial e registra quais seções falharam.
Armazenamentos e artefatos
O armazenamento de objetos é compatível com S3: o Reporter fala o protocolo S3 e qualquer serviço que o responda funciona como destino. As fontes de template chegam sob o prefixo
templates/, e os artefatos renderizados sob reports/, indexados pelo identificador do template e do relatório com o formato de saída como extensão. O Reporter não aplica nenhuma expiração própria, então a retenção é uma política de ciclo de vida que você define no bucket.
Reporter e Midaz
O Midaz é uma fonte de dados para o Reporter, não uma dependência em tempo de execução. O Reporter não carrega nenhum código específico do Midaz. Você registra um banco de dados Midaz com as mesmas variáveis
DATASOURCE_* de qualquer outro banco de dados PostgreSQL. Templates o endereçam pelo configName que o operador escolheu.
Duas consequências decorrem disso. O Reporter inicia e serve templates, prazos, e métricas sem nenhuma fonte de dados configurada, então uma indisponibilidade do Midaz nunca impede o Reporter de rodar. E o mesmo deployment pode gerar relatórios sobre o Midaz, sobre os seus próprios bancos de dados, e sobre ambos em um único template.
Aponte o Reporter para uma read replica onde uma existir. O caminho de extração apenas lê, mas a carga de consultas de um relatório pesado é real, e uma replica mantém essa carga fora do caminho de escrita do ledger.
Veja Conectando o Reporter ao Midaz para as variáveis, a convenção do
configName, e como confirmar que a fonte está visível.Saúde e readiness
Ambas as superfícies expõem
/health e /readyz antes da autenticação, para que os probes as alcancem sem um token. O probe /health responde 503 até que a auto-verificação de inicialização seja bem-sucedida. Isso permite que um orquestrador reinicie um pod que não conseguiu alcançar suas dependências na inicialização. O probe /readyz reporta as dependências que essa superfície realmente usa, e a resposta dele indica em qual modo de deployment o processo está rodando. A superfície da API também serve /version com a proveniência do build.
Leia a referência de saúde e readiness para o contrato de probe compartilhado entre os produtos Lerian.
Próximos passos
Conceitos essenciais
Templates, fontes de dados, relatórios, prazos, e os quatro estados de relatório.
Variáveis de ambiente
Toda configuração que molda um deployment do Reporter.