trilhalog

O que o trilha-log resolve

Nasceu de uma arquitetura de logging validada rodando em produção (dev e prod, Log4j2, JSON estruturado) e foi generalizada para qualquer projeto Spring Boot 4.x novo: adiciona a dependência, ganha a base pronta, customiza só o necessário.

Cada peça é registrada por autoconfiguração padrão do Spring Boot 4.x — nada de @Import manual ou component-scan. Cada bean é @ConditionalOnMissingBean, então qualquer peça pode ser sobrescrita registrando seu próprio bean do mesmo tipo.

Instalação

O trilha-log é distribuído via GitHub Packages da organização, não Maven Central. O pacote é público, mas o protocolo Maven do GitHub Packages exige um token de qualquer forma.

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/trilha-log/trilha-log</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.github.trilhalog</groupId>
        <artifactId>trilha-log</artifactId>
        <version>0.2.0</version>
    </dependency>
</dependencies>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Credenciais para resolver o pacote

Requer um GitHub PAT (ou gh auth token) com escopo read:packages. Três cenários:

Build local

Adicione um <server> ao ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>SEU_USUARIO_GITHUB</username>
      <password>SEU_TOKEN_COM_READ_PACKAGES</password>
    </server>
  </servers>
</settings>

Docker

Resolva o token via BuildKit secret, nunca via ARG/ENV gravado na imagem:

export GITHUB_ACTOR=seu-usuario-github
export GITHUB_TOKEN=$(gh auth token)

docker build \
  --secret id=github_token,env=GITHUB_TOKEN \
  --build-arg GITHUB_ACTOR=$GITHUB_ACTOR \
  -t sua-app .

CI (GitHub Actions)

actions/setup-java com server-id: github gera o <server> do settings.xml do runner automaticamente, usando o secrets.GITHUB_TOKEN padrão do workflow — nenhum PAT extra precisa ser cadastrado.

Correlação de requisição traceId

RequestCorrelationFilter gera um traceId (por padrão, um UUID completo de 32 caracteres — configurável, veja abaixo) e coloca no MDC/ThreadContext antes de chamar o resto da cadeia de filtros. Roda com @Order(HIGHEST_PRECEDENCE) — antes de qualquer filtro de segurança da aplicação consumidora.

Comprimento do traceId

Por padrão o traceId gerado é um UUID sem hifens (32 chars hex). Para usar um traceId mais curto — compatível com o formato legado de 8 chars — configure:

trilha-log:
  correlation:
    trace-id-length: 8  # 0 = UUID completo (padrão)

Opt-out de IP do cliente

O log de acesso inclui o IP por padrão. Em ambientes com requisitos LGPD/GDPR, desabilite:

trilha-log:
  correlation:
    log-ip: false

Propagação de traceId externo

Quando a requisição chega com um cabeçalho de rastreamento, o filtro reutiliza aquele valor em vez de gerar um novo. Os cabeçalhos são inspecionados na ordem configurada — o primeiro presente e não vazio vence:

Para alterar a lista ou desativar completamente a propagação:

trilha-log:
  correlation:
    incoming-trace-headers:
      - traceparent    # W3C — inspecionado primeiro
      - X-Request-ID   # lista vazia desativa propagação

Logging de corpo HTTP (opt-in)

Desabilitado por padrão para não vazar dados sensíveis sem consentimento explícito. Quando habilitado, o corpo JSON da requisição é mascarado automaticamente pelo mesmo LogMaskingUtil — campos com nome sensível viram "***" antes do log.

trilha-log:
  correlation:
    log-request-body: true    # opt-in — false por padrão
    max-body-log-bytes: 2048  # trunca payloads maiores

Integração com Micrometer Tracing

Quando micrometer-tracing está no classpath e há um span ativo (ex.: Zipkin, OpenTelemetry), o RequestCorrelationFilter usa o traceId do span corrente em vez de gerar um novo, e também coloca o spanId no MDC:

{"timestamp":"...","level":"INFO","traceId":"4bf92f3577b34da6a3ce929d0e0e4736","spanId":"00f067aa0ba902b7","callChain":"...","message":"..."}

A integração usa capability detection: se o Micrometer não estiver no classpath, o código nem é carregado — sem NoClassDefFoundError. Se estiver mas não houver span ativo, gera o traceId normalmente.

Execução via AOP callChain

@LogExecution pode ser aplicada em classe (vale pra todos os métodos) ou em método (sobrescreve a classe). Quatro atributos:

Omitindo retorno para tipos específicos

Em controllers que retornam ResponseEntity, o log de retorno pode ser verboso e redundante com o log de acesso do filtro. Use excludeReturnTypes para suprimir só esses casos:

@LogExecution(excludeReturnTypes = {ResponseEntity.class})
@RestController
public class PedidoController {

    public ResponseEntity<PedidoDto> buscar(long id) {
        // entrada e exceção logados normalmente; retorno omitido
        ...
    }
}

Limite de frames no callChain

Em stacks profundas, o callChain pode crescer indefinidamente. Configure um limite para manter o contexto mais recente — os frames antigos são substituídos por "... >":

trilha-log:
  aspect:
    max-call-chain-frames: 5  # 0 = sem limite (padrão)

Mascaramento de dados sensíveis

LogMaskingUtil.mascarar(nome, valor) é o ponto central, usado pelo aspecto de @LogExecution, pelo AppLog e por qualquer código que precise logar um valor que pode conter dado sensível. A ordem de verificação importa — é avaliada nesta sequência, parando na primeira que casar:

1. Valor nulo → retorna null.
2. Nome bate uma palavra-chave sensível (case-insensitive, contains) → "***", sem olhar o valor.
3. Tipo simples (primitivo, CharSequence, Number, Boolean, enum, UUID) → passa direto.
4. Entidade JPA (anotada @Entity) → vira só "NomeDaClasse(entidade)", nunca reflete os campos.
5. Collection, Map ou array → vira só o nome do tipo.
6. Qualquer outro objeto (DTO, record) → reflection rasa: campo @Sensitive ou com nome sensível vira "***"; o resto é formatado como NomeDaClasse{campo=valor}.

@Sensitive em parâmetros de método

Além de campos de DTO, @Sensitive pode ser aplicada diretamente em parâmetros de método anotados com @LogExecution — o aspecto mascara o argumento inteiro, independente do nome ou tipo:

@LogExecution
public boolean autenticar(String usuario, @Sensitive String senha) {
    // log de entrada: autenticar(usuario=kevin, senha=***)
    ...
}

Palavras-chave padrão

senha, password, token, secret, apikey, api-key, authorization, chave — configuráveis via application.yml:

trilha-log:
  masking:
    extra-keywords:
      - cpf
      - rg

Eventos de negócio com AppLog

Para logar um evento de negócio no meio de um método — onde o AOP de @LogExecution não alcança, já que ele só intercepta borda de entrada/saída, não uma condição no meio da lógica:

@LogExecution
@Service
public class AutenticacaoService {

    private final AppLog appLog;

    public AutenticacaoService(AppLog appLog) {
        this.appLog = appLog;
    }

    public boolean autenticar(LoginRequest request) {
        boolean autenticado = !request.senha().isBlank();
        if (autenticado) {
            appLog.info("login bem-sucedido", request);
        } else {
            appLog.warn("tentativa de login com senha vazia", request);
        }
        return autenticado;
    }
}

AppLog usa StackWalker para atribuir o log à classe que de fato chamou — não a própria AppLog — chamado diretamente dentro de cada método público (nunca via helper privado extra, senão o frame conta errado).

Campos MDC estruturados

Para emitir campos indexáveis independentes no JSON (pesquisáveis no Elasticsearch/OpenSearch/Loki), use as sobrecargas com Map<String, ?>. Os campos são adicionados ao MDC antes do log e removidos no finally:

// campos simples no MDC — aparecem como propriedades no JSON
appLog.info("pagamento confirmado", Map.of(
    "pedidoId", pedido.getId(),
    "valor",    pedido.getValor()
));

// contexto de objeto + campos MDC combinados
appLog.warn("estoque baixo", produto, Map.of("estoqueAtual", qtd));

{"timestamp":"...","level":"INFO","traceId":"...","callChain":"PedidoService.confirmar",
 "pedidoId":"42","valor":"199.90","message":"pagamento confirmado"}

Configuração

Qualquer peça pode ser trocada por implementação própria: registre um bean do mesmo tipo (AppLog, LogExecutionAspect, RequestCorrelationFilter) — a autoconfiguração recua automaticamente (@ConditionalOnMissingBean).

Testando com CapturaLogAppender

Anexa um appender em memória ao root logger para asserir eventos de log sem depender de captura de stdout:

class LoginServiceTest {

    private final CapturaLogAppender appender = new CapturaLogAppender();

    @BeforeEach
    void setUp() {
        appender.anexar();
    }

    @AfterEach
    void tearDown() {
        appender.desanexar();
    }

    @Test
    void logaTentativaComSenhaVazia() {
        // ...

        assertThat(appender.contemMensagem("tentativa de login com senha vazia")).isTrue();
    }
}

anexar() força Level.ALL no root logger (não dá pra confiar no nível ambiente quando os testes rodam no mesmo processo Surefire) e desanexar() restaura o nível original salvo.

Perguntas & armadilhas

traceId aparece em logs de bibliotecas de terceiro?

Sim. Ele vive no MDC/ThreadContext, não em um wrapper de logger — qualquer coisa que logue durante aquela requisição (Hibernate, Spring Security, etc.) carrega o mesmo traceId.

@LogExecution pode embrulhar a exceção?

Nunca. Sempre relança o Throwable original capturado — nunca um new RuntimeException(e.getMessage()) — para que a stack trace completa chegue a quem trata.

Qual convenção de nível de log usar no meu projeto?

Sugestão validada em produção: WARN para violação de regra de negócio / uso indevido esperado, DEBUG para ruído comum, ERROR só para falha real de sistema — sempre com stack trace completa no log do servidor, nunca na resposta ao cliente.

E se meu projeto não tiver Servlet API no classpath?

RequestCorrelationFilter é @ConditionalOnClass(Filter.class) — em uma aplicação sem Servlet API (um worker, por exemplo), o bean simplesmente não é criado, sem erro.

O log de corpo HTTP funciona com qualquer Content-Type?

Não. O log-request-body só processa corpos application/json. Para outros tipos o corpo é ignorado silenciosamente — sem erro, sem log parcial.

Micrometer Tracing e propagação de cabeçalhos se sobrepõem?

Sim, com precedência bem definida: se Micrometer Tracing estiver ativo e houver span corrente, ele vence. Caso contrário, os cabeçalhos de entrada (traceparent, etc.) são inspecionados. Se nenhum estiver presente, um traceId é gerado localmente.

excludeReturnTypes afeta o log de exceção?

Não. A lista só suprime o log de retorno normal (returning). Exceções continuam sendo logadas em ERROR independentemente.

Contribuindo

trilha-log é open source sob licença MIT. Issues e PRs são bem-vindos.

• mvn test roda a suíte completa antes de qualquer PR.
• sample-app/ é a aplicação de referência para validar mudanças de ponta a ponta.
• Discussões de arquitetura maiores (ex.: split em módulos core/web/test-support) ficam registradas como issues antes de virar código.