# 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.

> 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.

João Rizzon · 2026-10-01 · Infraestrutura web

---

## 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`:

```apache
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:

- `LogLevel` tem contexto de configuração de servidor, virtual host e diretório. **Não é permitido em `.htaccess`**. Se o seu acesso ao servidor termina no `.htaccess`, não existe truque: ou alguém com acesso à configuração liga para você, ou você reproduz o caso fora da produção.
- O `LogLevel` dentro de `<Directory>` só vale depois que a requisição foi mapeada para aquele diretório. Para o rewrite em contexto per-dir (que é o caso do `.htaccess`) isso é suficiente, porque o per-dir acontece justamente depois do mapeamento.

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.

```apache
# 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:

```bash
# 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:

```bash
# 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`.

```bash
# 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.

## 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:

- Trocar `[L]` por `[END]` (disponível a partir do 2.3.9, portanto em todo 2.4), que encerra o processamento de rewrite para a requisição inteira e não reentra.
- Excluir o alvo por condição, o clássico `RewriteCond %{REQUEST_FILENAME} !-f` e `!-d`, ou uma condição explícita sobre a URI de destino.
- Testar `%{ENV:REDIRECT_STATUS}` vazio para só agir no primeiro passe.

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:

```apache
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](https://docs.litespeedtech.com/lsws/cp/cpanel/rewrite-logs/), consultada em 18/09/2026, descreve o seguinte:

- **Onde se liga:** no WebAdmin Console do LSWS (por padrão em `https://IP:7080`), em Configuration > Server > Log, elevando o Log Level do Server Log para `DEBUG` e habilitando o Debug Level. O registro de reescrita é parte do log de depuração do servidor; sem ele ligado, não há linhas de rewrite. Atribuição: a página citada.
- **Para onde vai a saída:** para o error log do servidor, o mesmo arquivo configurado em File Name no bloco Server Log. Em instalação cPanel o LSWS reaproveita o error log do Apache, então é lá que o trace aparece. Atribuição: a mesma página.
- **Escopo:** o Debug Level do Server Log é ajuste de servidor, e o quanto dele é possível restringir por vhost depende da versão do LSWS e da configuração em uso. Na prática, assuma que ligar afeta todos os sites daquela instância enquanto estiver ativo, e só quem tem root no WHM chega nesse console.

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:

- Em hospedagem compartilhada, você não liga isso sozinho. Peça uma janela curta ao suporte, com a URL exata e o horário em que vai disparar o teste, ou reproduza o caso localmente.
- Como o efeito vale para a instância inteira, a janela precisa ser curta e combinada: tenha a URL exata e o comando `curl` prontos antes de pedir.
- A informação é equivalente (qual padrão foi aplicado contra qual URI, qual substituição saiu), então todo o raciocínio das seções anteriores vale. O que muda é o formato e o botão que liga.

## 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

- 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.
- `apachectl -t` para validar a sintaxe.
- `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.

```bash
# 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:

- **O `.htaccess` está sendo lido?** Teste destrutivo: uma linha de lixo (`asdf`) no topo do arquivo faz o Apache responder 500. Se não vier 500, o arquivo não está sendo processado. Risco: enquanto a linha existir, **toda** requisição àquele diretório e aos subdiretórios responde 500, inclusive de visitantes e crawlers, e o 500 pode ser cacheado por proxy ou CDN na frente. Faça o teste em contêiner, em staging ou num subdiretório que só o seu teste acessa; em produção, só em janela combinada. Reversão: copie o arquivo antes (`cp .htaccess /tmp/htaccess.bak`), apague a linha imediatamente após o teste e confirme com uma requisição que volte 200 (`curl -s -o /dev/null -w '%{http_code}\n' URL`). Causas típicas de o arquivo não ser lido: `AllowOverride None` no diretório, caminho errado (arquivo fora do docroot efetivo), nome do arquivo com extensão escondida pelo editor, permissão que impede a leitura pelo usuário do servidor.
- **O `mod_rewrite` está carregado?** `apachectl -M | grep rewrite` precisa mostrar `rewrite_module`. Sem ele, `RewriteEngine On` em `.htaccess` costuma dar 500 por comando desconhecido, mas em algumas configurações a diretiva é simplesmente ignorada.
- **`RewriteEngine On` está presente no escopo certo?** Ele não é herdado de um `.htaccess` de diretório pai da forma que a maioria espera, e conjuntos de regras do pai não se aplicam ao filho quando o filho tem o próprio `RewriteEngine On` sem `RewriteOptions Inherit`.
- **A resposta está vindo de antes do rewrite?** Cache de página no CMS, proxy ou CDN na frente, ou um 301 já memorizado pelo navegador. Teste com `curl -I` e cabeçalhos de no-cache, nunca com a aba normal do navegador.
- **O escopo do `LogLevel` é o do `.htaccess` que você quer?** `<Directory>` com caminho que não corresponde ao diretório real (link simbólico, por exemplo) não cobre o arquivo que está rodando.

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.

