Heritrix: análise prática sobre fidelidade WARC e o custo operacional do crawling de arquivos

Heritrix é o crawler de arquivamento open source do Internet Archive — a linhagem de software por trás do Wayback Machine, em produção há duas décadas. A função dele é registrar com fidelidade o que um site entregou, salvando tudo em arquivos WARC que podem ser reproduzidos anos depois. Por baixo dos panos, é um motor Java em que cada execução vira um grafo de Spring beans descrito em XML, e todo o ciclo do job é controlado por uma API REST. Não é um scraper: não existe sintaxe de seleção, não existe mapeamento de campos e não existe linha de dados no fim.

Testei a versão 3.16.0 em um ambiente local controlado e conferi o que ela realmente gravou, registro por registro. O que mais chama atenção é a completude: vinte URIs obtidas geraram sessenta e um registros WARC, com digest de payload e IP de captura em toda resposta, além de cada requisição vinculada à resposta correspondente, sem precisar mexer em nenhuma configuração. Já operar a ferramenta é uma experiência totalmente diferente: 41 MB, 114 jars (lib/ contém 142 arquivos; os outros 28 são textos LICENSE e NOTICE empacotados) e cerca de 750 linhas de configuração de job antes da primeira coleta — embora, neste teste, tudo tenha rodado sem interface gráfica, só via curl, sem um único clique na UI.

O resultado de armazenamento mostrou um padrão menos óbvio. Duas URLs do fixture devolveram conteúdo idêntico byte a byte, e o perfil padrão buscou e arquivou as duas por inteiro: dois registros de response e zero registros de revisit, mesmo atribuindo o mesmo digest às duas respostas. A deduplicação por content-digest funciona depois que os processadores de histórico são adicionados; ela não vem ligada no perfil padrão e economiza armazenamento, não banda.

O que o Heritrix realmente é

Arquivamento não é scraping, e essa é a confusão de categoria que vale a pena desfazer logo de cara. O Heritrix não entrega linhas de dados. Não existe CSV no fim. O resultado é a própria conversa HTTP — cabeçalhos, corpos e metadados de captura — guardada em um formato pensado para preservação, e ele é a implementação de referência dessa categoria de trabalho. Pedir a ele uma lista de preços de produtos é como pedir a um estenógrafo um resumo.

Números atuais em 27 de julho de 2026: o repositório está com 3.285 estrelas e 36 issues abertas, e a versão 3.16.0 é o release mais recente, publicado em 2026-07-03. Foi exatamente essa build que testei, então nada aqui é reclamação de versão velha. Há uma nuance no licenciamento: o arquivo LICENSE é um Apache-2.0 puro, mas o detector do próprio GitHub mostra "Other" porque alguns arquivos de terceiros incluídos trazem seus próprios termos. Se o Heritrix for entrar em um produto comercial, isso merece cinco minutos de atenção jurídica, não só uma olhada no selo lateral.

Um fato estrutural molda todo o resto: o Heritrix não usa navegador. Ele faz requisições HTTP e extrai links dos bytes retornados. Seu equivalente moderno em arquivamento, o Browsertrix Crawler, faz o oposto — usa Chromium de verdade e registra o que o navegador realmente fez. Ambos geram WARC, mas esta análise mediu só o caminho não baseado em navegador do Heritrix; não houve benchmark de escala ou throughput em nenhum dos sistemas.

Cadeias, beans e SURT: como um crawling é montado de verdade

Por baixo dos panos, um job do Heritrix é um contexto de aplicação Spring. Não é "configurado com Spring" — ele é um grafo de Spring beans escrito em XML, e cada parte do crawl é um bean que pode ser trocado.

A frontier guarda a fila de URIs, particionada por host. É essa partição que faz a polidez funcionar do jeito que funciona, e isso importa mais adiante.

As cadeias de processadores fazem o trabalho em três etapas: uma candidate chain (essa URI descoberta deve ser agendada?), uma fetch chain (DNS, robots, fetch HTTP, extração de links) e uma disposition chain (gravação em WARC, atualização de estado). Adicionar uma capacidade ao Heritrix normalmente significa inserir um bean processador no ponto certo da cadeia certa, e foi exatamente assim que ativei a deduplicação.

Scope é uma pilha de DecideRules operando sobre SURT — Sort-friendly URI Reordering Transform, que reescreve http://www.example.com/a em http://(com,example,www,)/a para que prefixos de hostname fiquem organizados em hierarquias. O escopo padrão é gerado a partir dos prefixes SURT das seeds. As regras aceitam ou rejeitam em sequência, e a última correspondência vence.

O gravador WARC fica na cadeia de disposição, e a polidez vive na frontier em três números: delayFactor, minDelayMs, maxDelayMs. O cumprimento de robots é uma string de política no fetcher.

E tudo isso pode ser controlado por uma API REST, o que acabou sendo mais importante do que eu esperava.

A configuração é a parte mais pesada de toda a experiência

O que você precisa implantar antes da primeira requisição:

A maior parte dessa configuração você nunca vai tocar. Mas também não dá para ignorá-la, e dois campos são obrigatórios antes que o crawler faça qualquer coisa: sua seed e metadata.operatorContactUrl. O valor padrão é um placeholder, e o crawl não começa até você trocar por uma URL real que identifique quem está executando a coleta.

Esse requisito cria um ponto de responsabilização: o operador precisa informar uma URL de contato antes da execução. Isso não prova que a identidade está correta, que o crawl foi autorizado ou que ele cumpre as regras aplicáveis, mas coloca as informações de contato como parte do job, e não como uma convenção opcional.

Dois achados de setup realmente me surpreenderam.

Ele rodou em um JDK mais novo do que o mínimo da documentação. A documentação de primeiros passos pede Java 17 ou superior. O Heritrix 3.16.0 iniciou, expôs sua API REST e concluiu todos os crawls deste fixture em OpenJDK 26.0.1, sem --add-opens, --enable-preview ou gambiarras com Security Manager. Esse é um resultado em macOS arm64, não uma matriz de compatibilidade, mas confirma que a build testada não ficou presa ao JDK 17 neste host.

Você nunca precisa tocar na interface web. Todo o ciclo do job é via REST, e eu automatizei tudo com curl: criar o job, fazer PUT do arquivo de beans, build, launch, unpause, consultar até o estado do controller virar FINISHED, encerrar e limpar. Essa é a resposta real para "dá para operar o Heritrix em pipeline?" — sim, sem interface, sem clique em navegador. Muitos textos mostram screenshots da UI do Jetty e dão a entender que ela é a interface. Ela é comodidade, não requisito.

Uma observação de implantação específica do host: este Mac usa um proxy HTTP em todo o sistema via Surge. O cliente Java do Heritrix herdou esse proxy e enviou até o tráfego de fixture em 127.0.0.1 por ele, produzindo respostas 503 apesar da lista de exceções do sistema e do NO_PROXY. Iniciar a JVM com -Djava.net.useSystemProxies=false mudou o resultado de 2×503 para 18×200. Isso foi uma interação de ambiente, não um defeito do Heritrix; a flag só importa quando herdar proxies do sistema é indesejável.

O que realmente entra no arquivo

Executei o perfil padrão stock contra um fixture controlado — um servidor local com um conjunto conhecido de endpoints, incluindo páginas HTML, uma cadeia de profundidade de três níveis, robots.txt e sitemap, além de rotas de propósito 404 e 500 — e depois analisei o WARC registro por registro, em vez de confiar em uma linha-resumo.

Vinte URIs obtidas geraram sessenta e um registros:

Uma proporção limpa de 1:1:1 entre response, request e metadata por URI, fora da caixa, sem qualquer configuração da minha parte. E a completude por registro resistiu à inspeção:

E o status HTTP foi preservado literalmente, inclusive os feios: 200 OK, 404 Not Found e 500 Internal Server Error aparecem como linhas de status reais nas responses armazenadas, em vez de serem descartados como falhas.

Esse último ponto separa arquivamento de scraping de forma mais nítida do que qualquer outro. Um scraper trata um 500 como erro a ser repetido ou ignorado. Um arquivador trata isso como o que o servidor disse naquele momento, e isso é um fato que vale preservar. A wiki Heritrix Output descreve essa estrutura de registros; o que eu não tinha visto em lugar nenhum era a multiplicidade medida e o vínculo 20/20 em um conjunto de endpoints conhecido. Ela se confirma.

O resultado da deduplicação, medido nos dois modos

Meu fixture serviu /dup/one e /dup/two com corpos byte a byte idênticos. URLs diferentes, mesmo conteúdo — exatamente o caso que a deduplicação por content-digest existe para colapsar. Rodei duas vezes: uma com o perfil padrão, outra depois de inserir a cadeia de histórico de digest (BdbContentDigestHistory, além de um ContentDigestHistoryLoader na fetch chain e um ContentDigestHistoryStorer depois do gravador WARC).

Pronto para uso, as duas responses receberam o mesmo digest, mas nenhum processador de histórico agiu sobre isso e ambos os payloads foram gravados integralmente. Ao adicionar a cadeia, a segunda captura virou um registro WARC revisit apontando para o digest idêntico, exatamente o comportamento definido pela especificação WARC 1.1 para revisits.

Nada disso é segredo. A página wiki Duplication Reduction Processors diz que skipIdenticalDigests vem como false por padrão e que a deduplicação agnóstica em relação à URL precisa desses beans loader e storer. Não é um comportamento escondido que foi descoberto; como quase tudo que medi aqui, é comportamento documentado do Heritrix com um número de primeira mão anexado. A diferença está entre a documentação e o que as pessoas acreditam, e, na minha experiência, a crença costuma ser "o Heritrix deduplica", ponto final, sem asterisco de configuração.

Dois corolários valem ser fixados na cabeça:

Deduplicação acontece na escrita, não na banda. Isso é mais mecanismo do que algo que eu tenha medido separadamente, mas segue diretamente do funcionamento dos content digests: só dá para comparar um digest depois que os bytes chegam, então a segunda URL é buscada no origin de qualquer forma. Habilitar a cadeia reduz o que você armazena, não o que transfere nem o que o servidor de destino precisa entregar. Quem orça deduplicação como ganho de polidez ou banda está invertendo a lógica.

Estimativas de armazenamento baseadas em "vai deduplicar" podem estar muito erradas. Se você estiver arquivando um site com forte duplicação de template — PDFs espelhados, páginas de entrada padronizadas, versões de impressão dos mesmos artigos — e dimensionar discos assumindo que corpos idênticos vão colapsar, o perfil padrão pode consumir muito mais espaço do que essa conta sugere. O fixture com duas URLs prova o comportamento padrão, não o efeito em escala de milhões de URIs; esse efeito depende da taxa de duplicação, do tamanho dos payloads e do desenho de recrawl.

Scope e robots fizeram exatamente o que prometem

A palavra do próprio crawler sobre o que ele não buscou vale muito pouco, então ambos os casos foram medidos com um contador de hits do lado do servidor — o servidor de destino contando as próprias requisições, independentemente do que o Heritrix registrou.

Scope. Enquanto isso, o host dentro do escopo foi rastreado normalmente, então o crawl estava disciplinado e não quebrado. Vale uma ressalva: aqui eu rodei apenas o braço de escopo padrão, não um controle positivo com escopo ampliado; então leia isso como confirmação do desenho documentado, não como prova de dois lados.

Robots. O link sempre esteve acessível; somente a política de robots o suprimiu. A obediência é real e o escape hatch também é real, o que é o arranjo correto — algumas obrigações de arquivamento legitimamente se sobrepõem ao robots, e isso deve exigir digitar ignore de propósito em um arquivo de configuração.

Polidez: 57,7 segundos para rastrear vinte páginas locais

Um número decide se o Heritrix serve para o seu projeto.

Mesmo fixture, mesmo tratamento em três execuções, em um único host local com latência abaixo de um milissegundo:

O atraso efetivo fica exatamente no piso de minDelayMs: em um origin submilissegundo, delayFactor × fetch-time é irrelevante e o mínimo domina por construção. A razão entre as duas linhas não é muito útil porque o denominador de polidez zero é de apenas dezenas de milissegundos e varia de execução para execução. O resultado estável é o piso absoluto: o Heritrix padrão esperou cerca de três segundos entre requisições ao mesmo host neste fixture, transformando um crawl de vinte páginas em cerca de um minuto de wall time.

Uma forma concreta de sentir o impacto. Imagine que uma biblioteca universitária precise arquivar um site governamental de 50.000 páginas antes da desativação, tudo em um único host. Com um piso de 3 segundos por host, isso representa 150.000 segundos de espera forçada — cerca de 42 horas, ou quase um dia e três quartos, antes mesmo de contar o tempo de fetch. Essa conta vem do piso medido de 3.036 ms — 50.000 x 3,036 s = 151.800 s = 42,2 h; mesmo com o mínimo configurado de 3.000 ms, dá 41,7 h, o que arredonda para 42, não 41. Não é um crawl medido, mas é a aritmética que o seu plano de projeto precisa considerar.

Em defesa do Heritrix, a polidez é por host, porque a frontier faz a fila por host. Um crawl amplo em milhares de domínios paraleliza entre essas filas e não herda esse teto de forma global. Meu fixture era um único host, que é o pior caso para esse número específico. Se o seu alvo de arquivamento for um site grande e único, esse pior caso é o seu caso.

E isso é uma característica, não um defeito. O atraso é o que torna um crawler de arquivamento algo que um dono de site tolera em vez de bloquear. Reduzi-lo é uma decisão sobre o servidor de outra pessoa, e a ferramenta torna essa decisão explícita em vez de agressiva por padrão.

O que eu não testei

Essas medições cobrem disciplina de crawl em um fixture controlado, e nada além disso. Fora desse limite:

• Deduplicação entre crawls e recrawl. Medi apenas a deduplicação por content-digest dentro do mesmo crawl. Persistir um banco de histórico de URIs entre crawls separados (FetchHistoryProcessor + PersistLog) é outro mecanismo, e eu não o exercitei.
• Escala e estabilidade de longo prazo. Não houve frontier de um milhão de URIs, nem checkpoint-and-restore, nem execução de vários dias. Meu fixture mede disciplina, não resistência.
• Captura renderizada por JavaScript. A captura padrão do Heritrix é não baseada em navegador, e foi isso que medi. Os comportamentos opcionais com navegador não foram testados aqui.
• Polidez em um origin de alta latência. A latência local é submilissegundo, então minDelayMs dominou por construção. Como delayFactor escala em um servidor real lento não ficou isolado nos meus dados.
• Recuperação via sitemap. O robots.txt foi requisitado e a diretiva de sitemap foi seguida, mas eu não validei separadamente a recuperação de cada entrada <loc>.

O que deixar explícito antes do primeiro job de produção

O perfil padrão é longo, mas as decisões que mudam o significado de um arquivo são relativamente compactas. Comece pelo scope. Seeds geram prefixes SURT padrão, e as DecideRules podem ampliá-los ou reduzi-los em sequência. Revise a ordem final das regras com URLs representativas dentro e fora do escopo e, depois, confirme isso com tráfego do lado do servidor ou outro log independente de requisições. Um relatório de crawl sozinho não prova que um host excluído nunca foi contatado.

Em seguida, defina o que política de robots e identidade do operador significam para a coleta. O padrão testado obedeceu à regra de disallow do fixture, enquanto alterar robotsPolicyName para ignore fez o caminho bloqueado ser buscado. Essa troca é mecanicamente simples e institucionalmente relevante. Registre quem aprovou e por quê, junto com um operatorContactUrl funcional; a URL obrigatória dá ao dono do site um caminho de volta ao operador, mas não fornece a justificativa de autorização.

O planejamento de armazenamento precisa da sua própria decisão explícita. Se corpos idênticos devem virar registros de revisit, adicione e revise os processadores de histórico por content-digest antes de dimensionar o arquivo. A cadeia testada afetou a representação depois do fetch, então o tráfego de origem ainda deve ser orçado para ambas as URLs. A deduplicação entre crawls é um mecanismo separado e não deve ser inferida desse resultado de duas URLs em um único crawl. Um crawl pequeno de validação, com corpos duplicados conhecidos, é uma forma barata de confirmar que o grafo de beans implantado produz os tipos de registro esperados.

Por fim, trate a polidez como um insumo de agendamento, e não como um ajuste de última hora. No fixture local de host único, minDelayMs dominou o tempo total. Um projeto real deve calcular o piso por host configurado em relação ao número de hosts-alvo e ao prazo da coleta, e depois testar com latência representativa. Crawls amplos e sites únicos pressionam a frontier particionada por host de maneiras diferentes; esta análise mediu só o segundo caso. Mantenha o ciclo REST no runbook também: build, launch, unpause, poll, terminate e teardown são estados separados que valem a pena monitorar na automação.

Prós e contras

Prós

• Completude de arquivamento excelente por padrão: 20/20 responses com digest de payload, IP de captura e vínculo completo request↔response, sem exigir configuração.
• Preserva respostas de erro como fatos — linhas de status 200, 404 e 500 são todas armazenadas literalmente.
• A disciplina de scope foi verificada com um contador do lado do servidor: zero fetches fora do escopo enquanto o host dentro do escopo era rastreado normalmente.
• A obediência a robots realmente suprime o fetch, com um escape hatch deliberado ignore para arquivamento mandatado.
• Totalmente headless via REST — criar, buildar, lançar, consultar e limpar, tudo por curl, sem cliques na UI.
• Roda limpo em OpenJDK 26.0.1 sem flags de JVM, o que é uma higiene de Java moderno melhor do que a maioria dos codebases de 20 anos consegue oferecer.
• URL obrigatória de contato do operador impede que o crawler rode de forma anônima.
• Cada parte do crawl é um bean substituível, e foi por isso que ativar dedup levou três inserções de bean, não um fork.

Contras

• A deduplicação por content-digest vem desligada por padrão e grava payloads idênticos por completo — um risco real para planejamento de armazenamento.
• A implantação é pesada: distribuição de 41 MB, 114 jars, um motor Java mais Jetty e cerca de 750 linhas de configuração Spring.
• A polidez padrão impõe um piso de cerca de 3 segundos por host; um crawl de 20 URIs em um único host levou 57,7 segundos.
• Não há renderização JavaScript no caminho padrão, então conteúdo gerado só no cliente não será capturado.
• A superfície de configuração favorece quem tem experiência e penaliza uso casual; não existe um caminho de cinco minutos para o primeiro crawl.
• Nada na saída é dado estruturado. Extrair campos de um WARC é um projeto à parte.

Quem deve usar e quem deve passar longe

Heritrix é para instituições e equipes cujo entregável é o próprio arquivo. Bibliotecas, arquivos nacionais, preservação jurídica e de compliance, grupos de pesquisa que capturam a web como fonte primária, qualquer pessoa que precise provar daqui a cinco anos o que uma URL servia em um dia específico. Se as palavras "WARC", "replay" e "proveniência" já fazem parte do seu vocabulário, esta é a ferramenta em torno da qual o restante do ecossistema foi construído — e seu peso é o preço dessa interoperabilidade.

Sua frontier particionada por host e o longo histórico em arquivamento da web fazem dele um candidato plausível para crawls amplos em muitos domínios. Isso é uma consideração arquitetural e histórica do projeto, não um resultado de escala deste fixture; throughput de longo prazo, recuperação de checkpoints e comportamento em milhões de URIs continuam sem teste aqui.

Evite-o se o que você quer é dado, não um arquivo. Se o objetivo é obter uma planilha de produtos, listagens ou contatos, o Heritrix fará um trabalho impecável ao capturar páginas que depois você terá de processar em outro pipeline — e terá pago por um motor Java, uma configuração Spring e um piso de polidez de 3 segundos por isso. Evite também se seus alvos são apps de página única renderizados no cliente, em que um fetcher sem navegador captura apenas a casca e não o conteúdo; nesse caso, um arquivador baseado em navegador é a ferramenta correta. E evite-o se você precisa do primeiro resultado hoje, porque a curva de setup é real.

Alternativas e onde entra uma API gerenciada

Dentro do arquivamento, o contraponto moderno direto é o Browsertrix Crawler — um arquivador baseado em navegador que controla o Chromium e registra o que o navegador fez. Ele consegue capturar conteúdo produzido por JavaScript e ausente das respostas HTTP padrão do Heritrix, mas adiciona custo de implantação e runtime do navegador. Esta análise não fez benchmark comparativo lado a lado, então a decisão começa pelos requisitos de captura: estado gerado por navegador aponta para um arquivador com navegador; recursos HTTP convencionais continuam sendo o caminho nativo do Heritrix.

Leitura relacionada: análise do Browsertrix Crawler.

Para um problema de natureza bem diferente — você não quer um arquivo, quer dados estruturados extraídos das páginas — compare o Heritrix com sistemas de extração pelo resultado, sem tratá-los como crawlers equivalentes. O Heritrix é gratuito e self-hosted: você opera a JVM, mantém o arquivo de beans, dimensiona os discos e ajusta a polidez. Esse modelo faz sentido quando preservação é o entregável.

Divulgação: Thunderbit é o produto do editor e não foi testado neste fixture do Heritrix. Ele pertence à categoria de extração gerenciada: seu resultado são conteúdos de página ou registros estruturados, não arquivos WARC com qualidade de preservação. Escolha um arquivador quando reprodução e proveniência forem necessárias; considere um serviço de extração quando o entregável for linhas ou texto de documentos e a operação gerenciada for aceitável.

Arquivamento traz sua própria questão de permissão, e ela não é a mesma do scraping. O Heritrix obedece a robots.txt por padrão e exige que você se identifique antes de buscar um byte, o que é uma base boa — mas um crawl compatível com robots não é automaticamente autorizado. Direitos autorais, termos de uso, dados pessoais e o mandato da sua instituição ficam acima disso, e a política ignore existe para organizações com base legal para usá-la, não como um botão de conveniência. Se você estiver montando um programa de arquivamento, defina o escopo de autorização antes que os discos encham, e consulte o lado legal do web scraping e do arquivamento se esse for um território novo.

Experimente Thunderbit para extração de dados da web

Veredito

Vale a pena usar Heritrix? Sim — se o seu entregável é um arquivo e você tem alguém disposto a aprender Spring beans.

O fixture apoia uma decisão clara: o perfil padrão preservou de forma consistente response, request e metadados de captura; os controles de scope e robots afetaram os fetches do lado do servidor conforme configurado; e todo o ciclo do job rodou via REST. São propriedades úteis para um pipeline de arquivamento, dentro do limite pequeno e de host único testado aqui.

Os custos operacionais são igualmente claros: uma distribuição Java e uma configuração Spring grande, um atraso por host configurado que dominou este crawl local e a deduplicação por content-digest que exige processadores de histórico adicionais. Equipes que precisam de fidelidade WARC podem aceitar esses custos; equipes que precisam de campos extraídos devem começar em outra categoria.

Antes de um crawl de produção, verifique a cadeia de dedup, as configurações de polidez, o scope, a política de robots, a identidade do operador e as suposições de armazenamento em relação à configuração real do job. O perfil padrão é um ponto de partida, não uma declaração implícita dessas escolhas operacionais.

Experimente Thunderbit para extração de dados da web Get Started Free

Perguntas frequentes

operatorContactUrl torna um crawl autorizado? Não. Ele obriga o job a incluir uma URL de contato, o que dá aos operadores do site um caminho de responsabilização, mas não estabelece permissão, precisão de identidade, status de direitos autorais ou conformidade regulatória. Tudo isso continua sendo uma decisão de implantação fora do crawler.

A deduplicação por content-digest reduz requisições ao origin? Não na configuração testada aqui. As duas URLs foram buscadas antes que seus digests de payload pudessem ser comparados. A cadeia de histórico mudou como o segundo payload foi representado no armazenamento WARC; ela não transformou a segunda URL em uma requisição de rede ignorada.

O Heritrix consegue rodar sem a interface web? Sim. O ciclo testado — criar, enviar a configuração, buildar, iniciar, liberar, monitorar, encerrar e limpar — foi executado pela API REST com curl. A UI Jetty embutida não foi necessária.

O perfil padrão do Heritrix deduplica payloads idênticos? Não no fixture, com essa configuração. O perfil padrão armazenou as duas respostas idênticas como registros completos de response. Adicionar a cadeia de histórico de content-digest alterou a segunda captura para um registro de revisit, então a deduplicação é uma decisão de pipeline que você precisa configurar e validar, e não um padrão automático.

Como devo escolher um atraso de polidez? Trate os tempos locais desta análise como verificação de mecanismo, não como recomendação de produção. Defina o atraso com base nas regras do site-alvo, no acordo com o operador, na capacidade do servidor, no objetivo do crawl e na sua política de retry/concurrency, e depois confirme os intervalos reais entre requisições ao mesmo host nos logs.