blog
Infraestrutura web

Por que a regra de rewrite não casa: use rewrite:trace3

Como ligar o rastreamento no escopo mais estreito, ler o bloco de uma requisição só e distinguir loop por reentrada, padrão com barra inicial e RewriteBase ausente. Inclui o procedimento de desligar com verificação.

JR · · 11 min de leitura · 2 tabelas · 11 blocos de código

Resposta curta: no Apache 2.4 o RewriteLog não existe mais; o rastreamento é `LogLevel warn rewrite:trace3`, com 8 níveis (trace1 a trace8), ligado em `<Directory>` e nunca em .htaccess. A linha `applying pattern 'P' to uri 'U'` mostra o que o motor realmente comparou.

Neste artigo
  1. O que substituiu o RewriteLog no Apache 2.4
  2. Ligue o trace só no diretório que você está depurando
  3. Como isolar as linhas de uma única requisição no error log
  4. O que cada linha do trace prova
  5. Três diagnósticos que o log fecha sozinho
  6. Como ligar o log de rewrite sob LiteSpeed em cPanel
  7. Desligar e provar que desligou
  8. Quando o log não mostra nenhuma linha de rewrite

O que substituiu o RewriteLog no Apache 2.4

As diretivas RewriteLog e RewriteLogLevel foram removidas no Apache 2.4. Se elas ainda aparecem em algum tutorial que você achou, o tutorial é de 2.2. Colocá-las numa configuração 2.4 gera erro de sintaxe no apachectl -t, e dentro de um .htaccess gera 500.

O que existe hoje é o LogLevel por módulo, com os níveis de rastreamento trace1 a trace8:

LogLevel warn rewrite:trace3

Isso significa: mantenha o servidor em warn para todo mundo e suba só o mod_rewrite para trace3. A saída vai para o ErrorLog do virtual host, misturada com o resto, e cada linha carrega o prefixo [rewrite:traceN], onde N é o nível em que aquela linha específica foi emitida, não o nível que você ligou: com trace3 ativo convivem no mesmo bloco linhas [rewrite:trace1], [rewrite:trace2] e [rewrite:trace3]. Por isso o filtro que funciona é grep -F '[rewrite:', sem o número.

Dois detalhes que derrubam a tentativa na primeira vez:

Sob LiteSpeed a história é outra, e ela tem seção própria mais abaixo.

Ligue o trace só no diretório que você está depurando

Rastreamento de rewrite é caro. Uma requisição que hoje escreve zero linha passa a escrever dezenas, no mesmo arquivo em que você vai precisar enxergar alguma coisa. Então não suba o LogLevel do servidor inteiro. Suba do diretório que você está depurando, de preferência de um subdiretório que só o seu teste acessa.

# exemplo: dentro do <VirtualHost> do site
<Directory "/home/exemplo/public_html/produtos">
    AllowOverride All
    LogLevel warn rewrite:trace3
</Directory>

Antes de recarregar, valide e guarde o estado anterior:

# qual LogLevel está valendo hoje, e onde
grep -rn --include='*.conf' -E '^[[:space:]]*LogLevel' /etc/apache2/ /etc/httpd/ 2>/dev/null

apachectl -t && apachectl graceful

Qual nível usar, de trace1 a trace8

A escala vai de trace1 a trace8 e é cumulativa: trace3 inclui o que trace1 e trace2 imprimem. O nível exato em que cada linha é emitida pode variar entre versões do mod_rewrite; use a tabela como ponto de partida e, se a linha que você procura não aparecer, suba um nível.

Nível O que você costuma ganhar Quando usar
trace1 Início do motor, redirecionamento interno, pass through Só para saber se o .htaccess está sendo lido
trace2 A substituição efetiva (rewrite 'a' -> 'b'), recolocação do prefixo per-dir Confirmar o resultado de uma regra que você sabe que casa
trace3 strip per-dir prefix, applying pattern ... to uri ..., split uri Padrão para depurar regra que não casa
trace4 Avaliação de cada RewriteCond (entrada, padrão, casou ou não) Quando o problema está na condição, não no padrão
trace5 a trace8 Detalhes internos: mapas, cache, lookups, estruturas Último recurso, e por poucos segundos

Na prática, trace3 responde "por que esse padrão não casou" e trace4 responde "por que essa regra foi pulada mesmo com o padrão certo". Comece por trace3.

Como reproduzir em contêiner quando não há acesso ao VirtualHost

Reproduza em contêiner, com o mesmo .htaccess, e depure à vontade:

# 1) extrai a conf padrão da imagem oficial para editar
docker run --rm httpd:2.4 cat /usr/local/apache2/conf/httpd.conf > httpd.conf

# 2) em httpd.conf: descomente LoadModule rewrite_module,
#    troque AllowOverride None por AllowOverride All no
#    <Directory "/usr/local/apache2/htdocs"> e acrescente,
#    dentro desse mesmo bloco: LogLevel warn rewrite:trace3

# 3) sobe com o seu site montado
docker run --rm -p 8080:80 \
  -v "$PWD/httpd.conf":/usr/local/apache2/conf/httpd.conf:ro \
  -v "$PWD/site":/usr/local/apache2/htdocs:ro \
  httpd:2.4

Na imagem oficial o ErrorLog sai no stderr do contêiner, então docker logs -f já mostra o trace. Duas diferenças em relação à produção que você precisa ter em mente ao concluir qualquer coisa: o caminho absoluto do diretório muda (e caminho absoluto aparece nas linhas de per-dir), e a hospedagem pode estar rodando LiteSpeed, não Apache.

Como isolar as linhas de uma única requisição no error log

Com o trace ligado, o error log vira uma torrente. O objetivo é extrair o bloco de uma requisição só, inteiro, na ordem.

O identificador que amarra as linhas é o rid, que aparece no prefixo de cada linha junto com um marcador de passe: [rid#55a1c0/initial] na primeira passada e [rid#.../initial/redir#1], redir#2 e assim por diante a cada redirecionamento interno. Sub-requisições aparecem como /subreq. O detalhe que atrapalha: a cada redirecionamento interno o rid muda, então filtrar só por rid perde os saltos seguintes. Filtre por IP de origem e reconstrua a cadeia pelo contador redir#N.

# dispara de um IP conhecido, com marcador na query string
curl -s -o /dev/null "https://exemplo.com.br/produtos/123?trace=abc123"

# extrai só o que é rewrite, vindo daquele IP
grep -F '203.0.113.10' /var/log/apache2/error.log | grep -F '[rewrite:'

# só os saltos, para ver de cara se virou loop
grep -F '203.0.113.10' /var/log/apache2/error.log | grep -F 'redir#'

Se o site tem tráfego e o seu IP não é único, o jeito limpo é ligar o trace apenas num <Directory> que só o teste acessa, ou num vhost de staging com o mesmo .htaccess.

O que cada linha do trace prova

Abaixo, um exemplo ilustrativo (não é saída capturada de um servidor real, e o prefixo de data, pid e cliente foi abreviado a partir da segunda linha para caber na tela):

[Wed Sep 17 14:02:11.884210 2025] [rewrite:trace3] [pid 2841:tid 139] mod_rewrite.c: [client 203.0.113.10:51734] [perdir /home/exemplo/public_html/] strip per-dir prefix: /home/exemplo/public_html/produtos/123 -> produtos/123
... [rewrite:trace3] ... [perdir /home/exemplo/public_html/] applying pattern '^produtos/([0-9]+)$' to uri 'produtos/123'
... [rewrite:trace2] ... [perdir /home/exemplo/public_html/] rewrite 'produtos/123' -> 'index.php?id=123'
... [rewrite:trace3] ... split uri=index.php?id=123 -> uri=index.php, args=id=123
... [rewrite:trace2] ... [perdir /home/exemplo/public_html/] add per-dir prefix: index.php -> /home/exemplo/public_html/index.php
... [rewrite:trace1] ... [perdir /home/exemplo/public_html/] internal redirect with /index.php [INTERNAL REDIRECT]

Leia na ordem, e cada linha responde uma pergunta:

Linha O que ela prova
strip per-dir prefix: /caminho/abs/x -> x O .htaccess foi lido e a URI que as regras vão ver não tem barra inicial
applying pattern 'P' to uri 'U' O par exato que o motor comparou. Se não vier uma linha rewrite depois, P não casou com U
RewriteCond: input='I' pattern='P' => matched (trace4) A condição foi avaliada, com o valor expandido de verdade
rewrite 'A' -> 'B' A substituição ocorreu e B é o novo valor
add per-dir prefix: B -> /caminho/abs/B A substituição relativa foi remontada em caminho de sistema de arquivos
strip document_root prefix: /caminho/abs/B -> /B O caminho foi remapeado de volta para URL. Se essa linha falta, o mapeamento não é um prefixo simples
internal redirect with /B [INTERNAL REDIRECT] Nova rodada do motor: o .htaccess será processado de novo
pass through /B Nenhuma regra alterou nada nesta rodada, a requisição seguiu
[rid#.../initial/redir#N] Contador de passes. N crescendo é o sintoma de loop

A linha mais útil de todas é applying pattern. Ela mata o debate sobre "a regra está certa": mostra literalmente a string que o motor recebeu e o padrão que ele usou. É onde a maior parte dos casos de "não funciona" se resolve, quando você vê que a URI comparada não é a que você imaginava.

Sequência das linhas de um passe per-dirstrip per-dir prefixURI perde a barra inicialapplying patternPadrão comparado com a URI realrewrite 'a' -> 'b'Substituição ocorreu nesta rodadaadd per-dir prefixVolta a caminho de arquivointernal redirecthtaccess é processado de novo
Ordem das linhas de um passe per-dir com rewrite:trace3. A ausência de uma linha é o diagnóstico: sem rewrite após applying pattern, o padrão não casou.

Três diagnósticos que o log fecha sozinho

Loop por reentrada no per-dir, e por que [L] não resolve

No contexto per-dir, uma substituição não encerra o processamento: ela dispara um redirecionamento interno, o servidor refaz a resolução de diretório e o mesmo .htaccess é processado outra vez. Se a nova URI ainda casa com a mesma regra, o ciclo se repete até o limite de recursão interna, que por padrão é 10 (LimitInternalRecursion).

No log (exemplo ilustrativo):

... [rid#5a10/initial]            applying pattern '^(.*)$' to uri 'produtos/123'
... [rid#5a10/initial]            rewrite 'produtos/123' -> 'index.php?rota=produtos/123'
... [rid#5b20/initial/redir#1]     applying pattern '^(.*)$' to uri 'index.php'
... [rid#5b20/initial/redir#1]     rewrite 'index.php' -> 'index.php?rota=index.php'
... [rid#5c30/initial/redir#2]     applying pattern '^(.*)$' to uri 'index.php'
[core:error] [client 203.0.113.10] Request exceeded the limit of 10 internal redirects due to probable configuration error.

O padrão é inequívoco: o mesmo applying pattern repetido com redir# crescente e o erro de recursão do core no fim. O [L] não resolve, porque ele só encerra a rodada atual, e é exatamente uma nova rodada que começou.

Saídas, em ordem de preferência:

Se o servidor for LiteSpeed, confirme o suporte ao END na versão em uso antes de depender dele.

Padrão com barra inicial que nunca casa em .htaccess

Este caso aparece inteiro em duas linhas:

... strip per-dir prefix: /home/exemplo/public_html/produtos/123 -> produtos/123
... applying pattern '^/produtos/([0-9]+)$' to uri 'produtos/123'
... pass through /home/exemplo/public_html/produtos/123

O padrão começa com /, a URI comparada não começa com /, nada casa, e a requisição passa direto. É a mesma regra que funcionaria sem alteração dentro de <VirtualHost>, porque lá a URI chega com a barra. Em .htaccess o prefixo do diretório é removido antes da comparação.

Correção: tire a barra inicial (^produtos/([0-9]+)$) ou torne-a opcional (^/?produtos/), que é o que salva a regra se o mesmo arquivo for incluído nos dois contextos.

RewriteBase ausente e o caminho do servidor vazando no Location

Substituição relativa em per-dir é remontada sobre o caminho de sistema de arquivos do diretório e depois precisa ser reconvertida em URL. Quando o diretório não é um prefixo simples da raiz de documentos (alias, link simbólico, subdomínio apontando para fora do docroot), essa reconversão falha e o caminho do servidor vaza.

... [perdir /home/exemplo/aplicacoes/loja/] rewrite 'carrinho' -> 'index.php?p=carrinho'
... [perdir /home/exemplo/aplicacoes/loja/] add per-dir prefix: index.php -> /home/exemplo/aplicacoes/loja/index.php
... escaping /home/exemplo/aplicacoes/loja/index.php for redirect
... redirect to http://exemplo.com.br/home/exemplo/aplicacoes/loja/index.php [REDIRECT/302]

O sinal é a ausência da linha strip document_root prefix e a presença do caminho do sistema de arquivos dentro do Location. O RewriteBase existe para informar manualmente qual prefixo de URL corresponde àquele diretório:

RewriteBase /loja/

Com ele, index.php vira /loja/index.php em vez de passear pelo sistema de arquivos. A alternativa é escrever substituições absolutas em URL, começando com /, que dispensam o RewriteBase.

Como ligar o log de rewrite sob LiteSpeed em cPanel

LiteSpeed lê o mesmo .htaccess e implementa as diretivas do mod_rewrite, mas não é o Apache: o LogLevel ... rewrite:traceN do Apache não é o que controla o log de reescrita do LSWS, e a saída não tem obrigação de sair no mesmo formato linha a linha.

A documentação oficial da LiteSpeed sobre rewrite logs em cPanel, consultada em 18/09/2026, descreve o seguinte:

Os nomes de campo e o caminho do arquivo mudam entre versões do LSWS e do plugin de cPanel, então confira a página antes de aplicar e confirme o caminho real em File Name em vez de assumir o padrão.

Consequências práticas que valem para qualquer provedor com LSWS:

Desligar e provar que desligou

Trace não é configuração permanente. Ele cresce o error log rápido, polui o diagnóstico de qualquer outro problema e consome CPU e I/O em cada requisição.

Reverter o LogLevel ao estado anterior

  1. Volte a linha ao valor anterior, aquele que você capturou com grep -rn ... LogLevel antes de começar. Se não havia nenhuma linha no bloco, remova a linha inteira em vez de escrever LogLevel warn: assim o bloco volta a herdar o nível do pai, que é o estado original.
  2. apachectl -t para validar a sintaxe.
  3. apachectl graceful para aplicar sem derrubar conexões em curso.

Confirmar pelo comportamento que o trace parou

Não confie no arquivo de configuração: confirme pelo comportamento.

# marca o tamanho atual do log
before=$(wc -c < /var/log/apache2/error.log)

# dispara a mesma URL que antes gerava trace
curl -s -o /dev/null "https://exemplo.com.br/produtos/123?trace=verifica"

# nenhuma linha de rewrite deve ter sido acrescentada
tail -c +$((before + 1)) /var/log/apache2/error.log | grep -c '\[rewrite:'

O resultado esperado é 0. Se vier diferente de zero, sobrou um LogLevel em outro escopo (um Include, um vhost de SSL duplicado, um arquivo em conf.d), e o grep -rn do passo 1 precisa ser refeito em todos os diretórios de configuração.

Sob LiteSpeed, a verificação é a mesma em espírito: desative o log de depuração pelo mesmo lugar em que foi ativado, repita a requisição e confirme que nenhuma linha nova de reescrita apareceu no error log.

Quando o log não mostra nenhuma linha de rewrite

Se depois de ligar o trace3 o error log segue sem nenhuma linha [rewrite:, o problema não é a regra. É mais cedo no caminho. Cheque nesta ordem:

Seguindo essa ordem, ou você encontra a causa antes do rewrite, ou você chega ao par applying pattern com a URI real na mão. Nos dois casos, a fase de tentativa e erro acabou.

Checagem quando não aparece linha de rewriteO .htaccess é lidoLinha inválida deve gerar 500mod_rewrite carregadoapachectl -M | grep rewriteRewriteEngine On no escopoNão é herdado do diretório paiResposta não vem de cacheTeste com curl -I, sem navegadorLogLevel no Directory certoCuidado com link simbólicoServidor é LiteSpeedTrace liga pelo WebAdmin, não LogLevel
Ordem de verificação quando o error log não traz nenhuma linha [rewrite: depois de ligar trace3.

Referências

  1. Documentação oficial (litespeed) — Rewrite Logs (LiteSpeed em cPanel). Consultado em 2026-09-18.
Leia também