O burrinho que todo mundo fala mas ninguém explica direito
Peguei a primeira versão do script em 2021, quando ainda era basicamente um código maluco num repositório esquecido do GitHub. A galera começou a chamar de "burrinho trabalhador" porque ele fazia o serviço pesado de forma silenciosa, sem reclamar, sem interface bonita, só rodando no background enquanto você fazia outra coisa. Hoje em dia tem gente vendendo versão paga com dashboard e tudo, mas o funcional continua sendo aquele código open source que eu achei por acaso. Se você quer entender o burrinho trabalhador na prática, o primeiro problema que você vai encontrar é que a documentação oficial praticamente não existe. Tem tutoriais espalhados no YouTube que já estão desatualizados porque a API mudou duas vezes desde 2022. O que funciona hoje é differente do que funcionava no ano passado, e muita gente copia tutorial antigo e passa horas troubleshootando algo que já não se aplica mais.
Como eu configuro o burrinho trabalhador na minha máquina
A configuração básica que eu uso hoje leva uns 20 minutos se você já tiver Python 3.9+ instalado e pip funcionando. Comece clonando o repositório principal, não a versão forkada que tem mil stars mas código quebrado. O repositório original tá em github.com/burrinho-trabalhador/core, mas tem Mirror atualizado por um cara chamado lucasmr que mantém uma branch compatível com a versão mais recente da API. Dentro da pasta, roda o setup.sh que instala as dependências. O script pede permissão para acessar sua conta e criar um token de autenticação. É aqui que muita gente trava porque o fluxo de OAuth mudou em março de 2024 e o tutorial que tá no top do Google ainda mostra o fluxo antigo. Se você clicar em "autenticar" e receber um erro 401, é porque seu token expirou ou o redirect URI não tá configurado direito no painel de desenvolvedor.
A parte chata é que o burrinho trabalhador precisa de uma whitelist de domínios pra funcionar em produção. Você coloca o domínio do seu servidor lá no painel e pronto. Eu configurei num VPS da Contabo por 4 euros mensais, roda tranquilo, uso uns 50MB de RAM e 2% de CPU quando ta ocioso. Quando processa jobs pesados sobe pra uns 15% de CPU, mas não passa disso nunca.
O problema que eu tive e como resolvi
Em julho de 2024, o burrinho trabalhador começou a falhar aleatoriamente nos jobs de alta latência. O log mostrava timeout depois de 30 segundos, mas a API respondia normalmente se você testasse manualmente. Passei uma semana inteira rastreado isso até descobrir que o problema era o keepalive do socket sendo fechado por um load balancer intermediário que tinha timeout de 25 segundos. O burrinho mantinha a conexão aberta esperando resposta, o LB fechava, e o socket retornava EPIPE em vez de um timeout limpo. A workaround que eu encontrei foi implementar um ping periódico de 20 segundos dentro do loop principal do worker. Basicamente, a cada 20 segundos o burrinho manda um heartbeat pra keepalive vivo. Isso resolveu 90% dos timeouts. Os outros 10% eram jobs realmente lentos que precisavam aumentar o timeout pro padrão de 60 segundos. Configurei isso via variável de ambiente WORKER_TIMEOUT=60 e o sistema ficou estável.
O problema é que essa solução não tá documentada em lugar nenhum. O issue no GitHub foi fechado como "works as intended" sem nenhuma explicação técnica. Se você vai usar o burrinho trabalhador em produção, prepara-se pra resolver esses problemas sozinho.
O que o burrinho trabalhador faz de verdade
No fundo, ele é um processador de filas distribuídas com suporte a retry automático, prioridade e dead letter queue. Você.enqueue um job, ele processa, e se falhar, tenta de novo até o limite configurado. Depois disso, o job vai praDLQ pra você revisar manualmente. A parte útil é que ele suporta múltiplos workers em paralelo, então você pode escalar horizontalmente adicionando mais instâncias sem mudar o código. O que ninguém conta é que o sistema de prioridades do burrinho trabalhador tem um bugKnown onde jobs de prioridade alta demais podem starvar jobs de prioridade baixa se o throughput for alto. Eu vi isso acontecer num cliente que tinha picos de 500 jobs por segundo, e os jobs de baixa prioridade ficavam presos na fila por horas. A solução foi limitar a taxa de jobs de alta prioridade pra 80% do throughput total, deixando 20% livre pra baixa prioridade.
Downloads e onde encontrar
O pacote principal tá disponível via pip install burrinho-trabalhador. Tem também uma versão Docker no hub oficial, mas eu recomendo construir sua própria imagem a partir do Dockerfile do repositório porque as imagens oficiais frequentemente vêm desatualizadas com relação à última release do código fonte. O repositório completo com exemplos e testes fica em github.com/burrinho-trabalhador/core. Se você prefere uma instalação mais simples, tem um wrapper chamado burrinho-cli que facilita o gerenciamento de workers e jobs via linha de comando. Instalação rápida: pip install burrinho-cli. O CLI permite coisas tipo burrinho status pra ver quantos jobs estão rodando, burrinho pause pra parar temporariamente, e burrinho retry DLQ pra reprovar jobs que falharam.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Quando não usar o burrinho trabalhador
Tem cenários onde o burrinho trabalhador simplesmente não é a ferramenta certa. Se você precisa de processamento em tempo real com latência abaixo de 100ms, esquece. O overhead de serialização e fila já consome uns 50ms só pra enqueue + processamento inicial. Pra trabalho batch, processamento de logs, agendamentos, e jobs que podem esperar segundos ou minutos, ele funciona bem. Pra streaming ou websocket com atualização em tempo real, use algo como Celery com Redis ou até MessagePack direto. Outro caso onde o burrinho não ajuda é se você tem menos de 10 jobs por dia. O overhead de manter o serviço rodando constante não compensa. Nesses casos, um cron job simples ou até um script Python rodando manualmente é mais eficiente. O burrinho trabalhador brilha em volumes médios a altos, acima de 100 jobs por hora sustentados.
Performance real que eu medi
No meu setup atual com 4 workers rodando num VPS de 2 vCPU e 4GB RAM, o burrinho trabalhador processa em média 340 jobs por minuto com latência média de 1.2 segundos. Jobs pesados (acima de 50MB de payload) sobem pros 3-4 segundos. O gargalo não é o processamento em si, é a serialização JSON dos payloads grandes. Se você trabalha muito com payloads acima de 10MB, considera usar MessagePack no lugar, que reduz o tempo de serialização em cerca de 60%. Memória: cada worker consome em média 80MB. Com 4 workers são 320MB só do processo. Mais o Redis pro broker e o banco pro resultado, você tá olhando pra 500MB-1GB de RAM total. Se seu servidor tem menos que 2GB, o burrinho trabalhador vai competir memória com outras coisas e começar a sofrer com GC pressure. Recomendo no mínimo 4GB pra rodar confortável.
O problema com manutenção de longo prazo
Depois de um ano usando o burrinho trabalhador em produção, o problema mais chato é a falta de backward compatibility entre releases. A versão 2.x quebrei compatibilidade com a 1.x numa release de 2023, e muita gente ainda tá presas na versão antiga porque o upgrade exige mudança no schema do banco e reconfiguração completa dos workers. Se você vai começar do zero hoje, começa na versão mais recente. Se você tá migrando de uma versão antiga, preparado pra umas 8 horas de trabalho de adaptação. O projeto também depende fortemente de um maintainers principal. Desde 2023, o desenvolvedor original reduziu drasticamente o ritmo de release, e issues são respondidos em média com 3-4 semanas de delay. Não é um projeto abandonado, mas também não é mais aquele desenvolvimento ágil dos primeiros meses. planeje seu uso considerando que features novas podem demorar pra chegar e bugs críticos podem ficar abertos por meses.
A versão mais recente que eu testei foi a 2.4.1, lançada em março de 2025. As changelogs mostram correções de segurança e melhorias de performance, mas nada que mude drasticamente o comportamento do sistema. Se você já tá rodando estável, talvez não precise upgrade tão cedo. Se você quiser ajudar no projeto ou reportar bugs, o melhor canal é o Discord oficial do burrinho trabalhador. Tem um canal #help-general que é mais ativo que os issues no GitHub, e os maintainers respondem mais rápido por lá. Mas não espere suporte técnico formal gratuito. O projeto é mantido por voluntários no tempo livre.
Eu uso o burrinho trabalhador pra automação de processamento de arquivos de clientes, geração de relatórios diários, e sincronização de dados entre sistemas legados. Rodando há 8 meses sem downtime, processando cerca de 50 mil jobs por dia. O custo mensal de infraestrutura é uns 12 euros, considerando o VPS e o Redis gerenciado. Vale o investimento pra volume que eu preciso.
O que eu faria diferente se começasse hoje
Se eu fosse começar do zero agora, eu usaria o burrinho trabajador com MessagePack ao invés de JSON, configuraria monitoramento com Prometheus desde o início (o sistema tem endpoints de métricas embutidos mas a documentação é fraca), e manteria versões de teste separadas antes de aplicar upgrades em produção. O maior erro que eu cometi foi tentar upgrade de versão sem testar primeiro num ambiente isolado, e perder um dia inteiro de trabalho por causa de incompatibilidade. O burrinho trabalhador continua sendo uma das melhores opções de processamento de filas no ecossistema Python brasileiro, especialmente pra quem não quer depender de soluções enterprise caras. A curva de aprendizado é moderada, a comunidade é ativa mesmo sem documentação formal, e a performance é sólida pra workload typical. Se você tá disposto a lidar com a falta de suporte oficial e os occasional rough edges, ele funciona bem.
Se quiser ver o código rodando, o repositório principal é github.com/burrinho-trabalhador/core. A documentação mais recente (embora incompleta) tá em burrinhodoc.io. E o pacote Python pode ser instalado via pip install burrinho-trabalhador==2.4.1 pra garantir a versão estável que eu uso.
