athletic-map-deploy/platform/monitoring/athleticmap-rules-nota-fiscal.yaml

# =============================================================================
# N18 — Alerta de nota fiscal travada.
#
# DESTINO NO GITOPS: platform/monitoring/athleticmap-rules-nota-fiscal.yaml
# (repositorio athletic-map-deploy do servidor). O app `atm-platform` le
# `platform/` com recurse, entao basta o arquivo estar la — nao precisa mexer
# no `athleticmap-rules.yaml` nem no `application.yaml`.
#
# De onde vem: `MetricasDasNotasFiscais` e `ProcessarNotasPendentes`, no
# servico-financeiro (dentro do runtime-operacao nos tenants consolidados). As
# metricas `atm_*` ja estao na lista de keep dos tres ServiceMonitors
# (runtimes, servicos, tenants), entao chegam sem mudar a coleta.
#
# Procedimento manual: docs/runbook-nota-fiscal-travada.md (repo nova-atm).
#
# ── POR QUE ESTES LIMITES ───────────────────────────────────────────────────
#
# 6 HORAS para nota que devia estar andando (PENDENTE_EMISSAO / EMITINDO):
#   - no normal, a varredura roda de hora em hora (:15) e o provedor emite em
#     ate 15 min: uma nota passa menos de 1h30 pendente;
#   - a NFS-e nacional cai e volta sozinha, em geral em minutos ou poucas
#     horas, e o provedor tenta de novo sem ninguem pedir — alertar em 1-2h
#     seria e-mail para algo que se resolve sozinho (e a caixa dos alertas e a
#     mesma dos avisos aos clientes, com cota);
#   - 6h sao seis rodadas da varredura: nao e mais soluco. E ainda da tempo de
#     agir no mesmo dia, bem antes do fim da competencia.
# 24 HORAS vira critical (mesmo nome de alerta: o Alertmanager cala o warning
#   quando o critical dispara — inhibit_rules com equal [namespace, alertname]).
#   Um dia inteiro sem nota e pagante perguntando, e a virada de mes chegando.
#
# ERRO: 1 hora. Nota em ERRO NAO e reenviada sozinha — ninguem mexendo, ela
#   fica la para sempre. O `for` so segura a rajada de uma rodada ruim, para o
#   e-mail sair uma vez com o total, e nao nota a nota.
#
# PENDENTE_DADOS: 72 horas. Nao e instabilidade: e cadastro (configuracao
#   fiscal ou dado do tomador faltando), resolvido pela escolinha ou pelo
#   contador, em dia util. 72h atravessa um fim de semana sem alarme. O "mais
#   brando" esta no PRAZO, e nao na severidade: `info` nao e usado na
#   plataforma (scripts/test_regras_de_alerta.py so aceita warning/critical) e,
#   no desenho do chart, info existe para ser calado pelo InfoInhibitor.
# =============================================================================
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: athleticmap-rules-nota-fiscal
  namespace: monitoring
  labels:
    release: monitoring          # o Prometheus so carrega regras com este label
spec:
  groups:
    - name: athleticmap.nota-fiscal
      rules:
        # `max by (namespace, situacao)`: com duas replicas do runtime, as duas
        # publicam o mesmo numero (a conta vem do banco do tenant). O max junta.
        - alert: AthleticMapNotaFiscalTravada
          expr: |
            max by (namespace, situacao) (
              atm_nota_fiscal_pendente_mais_antiga_segundos{situacao=~"PENDENTE_EMISSAO|EMITINDO"}
            ) > 6 * 3600
          for: 15m
          labels:
            severity: warning
          annotations:
            summary: "{{ $labels.namespace }}: nota fiscal parada em {{ $labels.situacao }} ha mais de 6h"
            description: >-
              A nota mais antiga em {{ $labels.situacao }} esta parada ha
              {{ $value | humanizeDuration }}. EMITINDO = ja esta no provedor (Asaas)
              esperando a prefeitura: quase sempre e a NFS-e nacional instavel —
              confira o status da NFS-e nacional e o painel do Asaas (Notas fiscais)
              antes de mexer; o provedor tenta de novo sozinho. PENDENTE_EMISSAO = a
              varredura de hora em hora nao levou a nota: veja o CronJob
              financeiro-notas (kubectl -n {{ $labels.namespace }} get jobs
              -l job-name --sort-by=.metadata.creationTimestamp). NAO emita a nota
              por fora sem cancelar a do provedor: sai em dobro. Procedimento:
              docs/runbook-nota-fiscal-travada.md.

        - alert: AthleticMapNotaFiscalTravada
          expr: |
            max by (namespace, situacao) (
              atm_nota_fiscal_pendente_mais_antiga_segundos{situacao=~"PENDENTE_EMISSAO|EMITINDO"}
            ) > 24 * 3600
          for: 15m
          labels:
            severity: critical
          annotations:
            summary: "{{ $labels.namespace }}: nota fiscal parada em {{ $labels.situacao }} ha mais de 24h"
            description: >-
              Um dia inteiro sem a nota sair ({{ $value | humanizeDuration }}). Se a
              NFS-e nacional continua fora, avise a escolinha (a nota sai atrasada,
              com a data do servico) e acompanhe; se voltou e a nota nao andou, use
              "sincronizar" em cada nota e, se o provedor disser erro, "reabrir".
              Emissao manual so seguindo o runbook, na ordem, para nao duplicar:
              docs/runbook-nota-fiscal-travada.md.

        - alert: AthleticMapNotaFiscalEmErro
          expr: max by (namespace) (atm_nota_fiscal_pendentes{situacao="ERRO"}) > 0
          for: 1h
          labels:
            severity: warning
          annotations:
            summary: "{{ $labels.namespace }}: {{ $value }} nota(s) fiscal(is) em ERRO"
            description: >-
              O provedor ou a prefeitura recusou, e nota em ERRO NAO e reenviada
              sozinha. Veja o motivo de cada uma (GET /api/financeiro/notas?situacao=ERRO,
              campo erroMensagem). Se foi a NFS-e nacional fora, espere ela voltar
              e use POST /api/financeiro/notas/{id}/reabrir — a proxima varredura
              manda de novo. Se foi dado errado, corrija antes de reabrir.
              Procedimento: docs/runbook-nota-fiscal-travada.md.

        - alert: AthleticMapNotaFiscalSemDadosFiscais
          expr: |
            max by (namespace) (
              atm_nota_fiscal_pendente_mais_antiga_segundos{situacao="PENDENTE_DADOS"}
            ) > 72 * 3600
          for: 1h
          labels:
            severity: warning
          annotations:
            summary: "{{ $labels.namespace }}: notas sem emitir por falta de dado fiscal ha mais de 3 dias"
            description: >-
              Nao e instabilidade: falta configuracao fiscal da escolinha (codigo de
              servico municipal, aliquotas, emissao desligada) ou dado do tomador
              (CPF/CNPJ, endereco). O motivo esta em erroMensagem ("faltam: ...") em
              GET /api/financeiro/notas?situacao=PENDENTE_DADOS. Fale com a escolinha
              ou o contador; depois de corrigir, "reabrir" cada nota.

        # Silencio nao e "nenhuma nota parada": se a conta nao roda, as metricas
        # acima ficam no ultimo valor (ou em zero, se nunca mediram). Com a
        # validade de 2 min, ~30 tentativas por hora por replica.
        - alert: AthleticMapNotaFiscalSemMedicao
          expr: max by (namespace) (increase(atm_nota_fiscal_medicao_falhou_total[30m])) > 5
          for: 30m
          labels:
            severity: warning
          annotations:
            summary: "{{ $labels.namespace }}: ha 1h nao se consegue contar as notas fiscais paradas"
            description: >-
              O alerta de nota travada esta cego neste tenant. Quase sempre e o banco
              do financeiro fora ou sem conexao. Log: kubectl -n {{ $labels.namespace }}
              logs deploy/runtime-operacao | grep 'nao consegui contar as pendentes'
              (no escolinha-prod e no plataforma-prod o deploy e o servico-financeiro).