O Systemplane permite que você visualize e modifique a configuração do Matcher em tempo de execução — sem reiniciar o serviço. Em ambientes financeiros regulados, interrupções não planejadas para aplicar mudanças de configuração representam um risco de conformidade e uma disrupção operacional. O Systemplane elimina isso: parâmetros operacionais podem ser ajustados enquanto o serviço permanece em execução, mantendo os processos de reconciliação ininterruptos.Documentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
Por que usar o Systemplane
Em um deploy tradicional, alterar um valor de configuração significa atualizar variáveis de ambiente e reiniciar o serviço. O Systemplane elimina esse downtime para muitas configurações:
- Ajustar rate limits durante picos de tráfego sem redeploy — evitando interrupções do serviço em momentos de alto volume de transações
- Ajustar intervalos de workers com base nos padrões de carga observados — otimizando o throughput de reconciliação sem mexer na infraestrutura
- Atualizar tamanhos de connection pool conforme os padrões de tráfego mudam
- Inspecionar valores atuais em tempo de execução para diagnosticar problemas em produção sem mergulhar nos logs
Como funciona
O Systemplane fornece uma API de gerenciamento de chave-valor flat. Todas as chaves de configuração estão em um único namespace sob
/system/matcher.
Endpoints
| Endpoint | Método | O que faz |
|---|---|---|
/system/matcher | GET | Listar todas as chaves e seus valores atuais |
/system/matcher/:key | GET | Obter o valor atual de uma chave específica |
/system/matcher/:key | PUT | Atualizar o valor de uma chave específica |
Esses endpoints são servidos diretamente pela instância do Matcher em execução. Eles não são versionados sob
/v1 — use os caminhos acima exatamente como mostrado.Permissões
Os endpoints do Systemplane são protegidos pela mesma autenticação usada por todas as rotas da API do Matcher. Quando a autenticação está habilitada, todos os endpoints
/system requerem a permissão RBAC system:admin.
Quando a autenticação está desabilitada, todos os endpoints são acessíveis sem restrição.
Comportamentos de aplicação
Nem todo valor de configuração pode ser alterado em tempo de execução. Cada chave tem um comportamento de aplicação que indica quando as mudanças entram em vigor:
| Comportamento | O que acontece |
|---|---|
| Somente bootstrap | O valor é lido uma vez na inicialização. Você deve reiniciar o serviço para que as alterações entrem em vigor. |
| Leitura ao vivo | As alterações entram em vigor imediatamente na próxima requisição. |
| Reconstrução de bundle | As alterações disparam uma atualização de estado interno. Entra em vigor em segundos. |
| Reconciliação de worker | Workers em background captam o novo valor no próximo ciclo. |
Chaves de configuração comuns
Abaixo estão as chaves mais comumente ajustadas, organizadas por categoria. Para uma lista completa, chame
GET /system/matcher.
Chaves ajustáveis em tempo de execução
Essas chaves podem ser alteradas sem reiniciar o Matcher:| Chave | Variável de ambiente | Descrição |
|---|---|---|
app.env_name | ENV_NAME | Nome do ambiente da aplicação |
server.body_limit_bytes | HTTP_BODY_LIMIT_BYTES | Tamanho máximo do corpo da requisição HTTP |
cors.allowed_origins | CORS_ALLOWED_ORIGINS | Origens CORS permitidas |
cors.allowed_methods | CORS_ALLOWED_METHODS | Métodos CORS permitidos |
cors.allowed_headers | CORS_ALLOWED_HEADERS | Headers CORS permitidos |
swagger.enabled | SWAGGER_ENABLED | Habilitar ou desabilitar o Swagger UI |
swagger.host | SWAGGER_HOST | Override do host do Swagger |
swagger.schemes | SWAGGER_SCHEMES | Esquemas de URL do Swagger |
rate_limit.enabled | RATE_LIMIT_ENABLED | Habilitar ou desabilitar o rate limiting global |
rate_limit.max | RATE_LIMIT_MAX | Máximo de requisições por janela de rate limit |
rate_limit.expiry_sec | RATE_LIMIT_EXPIRY_SEC | Duração da janela de rate limit (segundos) |
rate_limit.export_max | EXPORT_RATE_LIMIT_MAX | Rate limit do endpoint de exportação |
rate_limit.dispatch_max | DISPATCH_RATE_LIMIT_MAX | Rate limit do endpoint de dispatch |
rate_limit.admin_max | ADMIN_RATE_LIMIT_MAX | Rate limit do plano admin (/system) |
idempotency.retry_window_sec | IDEMPOTENCY_RETRY_WINDOW_SEC | Janela para tentar novamente requisições idempotentes com falha |
idempotency.success_ttl_hours | IDEMPOTENCY_SUCCESS_TTL_HOURS | Por quanto tempo as chaves de idempotência concluídas ficam em cache |
fetcher.enabled | FETCHER_ENABLED | Habilitar ou desabilitar o módulo Fetcher |
fetcher.url | FETCHER_URL | URL do serviço Fetcher |
fetcher.discovery_interval_sec | FETCHER_DISCOVERY_INTERVAL_SEC | Com que frequência o Matcher consulta o Fetcher por novas fontes de dados |
export_worker.enabled | EXPORT_WORKER_ENABLED | Habilitar ou desabilitar o worker de exportação |
export_worker.poll_interval_sec | EXPORT_WORKER_POLL_INTERVAL_SEC | Com que frequência o worker de exportação verifica novos jobs |
cleanup_worker.enabled | CLEANUP_WORKER_ENABLED | Habilitar ou desabilitar o worker de limpeza |
cleanup_worker.interval_sec | CLEANUP_WORKER_INTERVAL_SEC | Intervalo do worker de limpeza |
scheduler.interval_sec | SCHEDULER_INTERVAL_SEC | Intervalo de polling do scheduler |
archival.enabled | ARCHIVAL_WORKER_ENABLED | Habilitar ou desabilitar o worker de arquivamento |
webhook.timeout_sec | WEBHOOK_TIMEOUT_SEC | Timeout para dispatch de webhooks/callbacks |
callback_rate_limit.per_minute | CALLBACK_RATE_LIMIT_PER_MIN | Máximo de callbacks por sistema externo por minuto |
telemetry.enabled | ENABLE_TELEMETRY | Habilitar OpenTelemetry |
deduplication.ttl_sec | DEDUPE_TTL_SEC | TTL de deduplicação em segundos |
Chaves multi-tenant (ajustáveis em tempo de execução)
Essas chaves controlam o comportamento multi-tenant e podem ser ajustadas sem reinício. Consulte Modo Multi-Tenant para mais detalhes.| Chave | Variável de ambiente | Descrição |
|---|---|---|
tenancy.multi_tenant_enabled | MULTI_TENANT_ENABLED | Habilitar infraestrutura multi-tenant |
tenancy.multi_tenant_url | MULTI_TENANT_URL | URL do serviço Tenant Manager |
tenancy.multi_tenant_max_tenant_pools | MULTI_TENANT_MAX_TENANT_POOLS | Máximo de pools de tenant simultâneos |
tenancy.multi_tenant_idle_timeout_sec | MULTI_TENANT_IDLE_TIMEOUT_SEC | Timeout de ociosidade para eviction de pool de tenant |
tenancy.multi_tenant_cache_ttl_sec | MULTI_TENANT_CACHE_TTL_SEC | TTL do cache de configuração de tenant |
Chaves somente bootstrap (requerem reinício)
Essas chaves não estão registradas na API do systemplane. Altere-as por variáveis de ambiente e reinicie:| Chave | Variável de ambiente | Descrição |
|---|---|---|
app.log_level | LOG_LEVEL | Nível de log da aplicação (debug, info, warn, error) |
server.address | SERVER_ADDRESS | Endereço de escuta do servidor HTTP |
postgres.primary_host | POSTGRES_HOST | Host do banco de dados primário |
postgres.primary_port | POSTGRES_PORT | Porta do banco de dados primário |
postgres.primary_db | POSTGRES_DB | Nome do banco de dados primário |
redis.host | REDIS_HOST | Host do Redis |
rabbitmq.host | RABBITMQ_HOST | Host do RabbitMQ |
auth.enabled | PLUGIN_AUTH_ENABLED | Habilitar middleware de autenticação |
auth.host | PLUGIN_AUTH_ADDRESS | Endereço do serviço de autenticação |
Boas práticas
Inspecione os valores atuais antes de alterar
Inspecione os valores atuais antes de alterar
Chame
GET /system/matcher para ver todos os valores atuais em tempo de execução antes de fazer qualquer alteração. Isso confirma o que o processo está realmente usando, que pode diferir das variáveis de ambiente se chamadas PUT anteriores foram feitas.Teste mudanças em staging primeiro
Teste mudanças em staging primeiro
Mesmo que as alterações em tempo de execução não requeiram reinício, elas entram em vigor imediatamente. Teste em um ambiente de staging antes de aplicar em produção.
Reinicie para chaves somente bootstrap
Reinicie para chaves somente bootstrap
Se uma chave não estiver visível em
GET /system/matcher, ela é somente bootstrap. Atualize a variável de ambiente e reinicie o serviço — não há caminho em tempo de execução para esses valores.Próximos passos
Modo multi-tenant
Habilitar e configurar o isolamento de tenant.
Roteamento de exceções
Configurar como as exceções são despachadas para sistemas externos.
Regras de match
Configurar regras de correspondência de transações.
Segurança
Autenticação, autorização e proteção de dados.