bull-horizon
Configura, instrumenta e depura o Bull Horizon (@bull-horizon/*), o painel de filas Bull e BullMQ montado dentro da app (Express, NestJS, Fastify, Koa, Hapi) ou via CLI. Use ao "montar o painel /bull"
SKILL.mdskills/bull-horizon/SKILL.md
GitHubBull Horizon
Bull Horizon é um dashboard (UI React + API GraphQL) para filas Bull (v3/v4) e BullMQ, distribuído como biblioteca: você monta o router/plugin dentro da sua app Node e ele lê as filas direto do Redis. Mostra jobs (listar, buscar com jsonata, retry, remove, promote), contagens ao vivo, histórico de throughput opcional, endpoint Prometheus opcional e, para filas de agente de IA, cada tentativa como um run (passos LLM, tools, tokens, custo). Com flows declarados, mostra o pipeline entre filas e o caminho de um item pelo trace id.
Fork mantido do bull-monitor (s-r-x, arquivado em 2023). Desde a v6 o escopo npm é @bull-horizon/*; as classes mantiveram o nome (BullMonitorExpress, BullMonitorFastify...).
Quando usar esta skill
- Montar o painel numa app (NestJS é o caso mais comum) ou rodar o CLI standalone.
- Adicionar uma fila nova ao painel, separar filas em grupos, marcar fila como readonly.
- Ligar métricas (throughput, tela Metrics history), ajustar retenção, expor Prometheus.
- Instrumentar uma fila de agente de IA (
aina fila +createAgentRunno worker). - Declarar um flow (pipeline que atravessa filas) e propagar o trace nos workers (
flowsno monitor +startTrace/withTrace/continueTrace). - Proteger a rota do painel (ele não tem auth própria).
- Depurar: fila não aparece, sem histórico, aba Agents ausente, run ausente, contagem
lost, custo sem preço, trace quebrado ou ausente na aba Flows. - Migrar um projeto de
@bull-monitor/*para@bull-horizon/*.
Pacotes
| Pacote | Papel |
|---|---|
@bull-horizon/root |
Núcleo: BullAdapter, BullMQAdapter, tipos de config, createAgentRun. Dependência dos adapters |
@bull-horizon/express |
BullMonitorExpress: expõe monitor.router (Express e NestJS) |
@bull-horizon/fastify |
BullMonitorFastify: init({ app }) + app.register(monitor.plugin) |
@bull-horizon/koa |
BullMonitorKoa: monitor.router.routes() (peer koa-router) |
@bull-horizon/hapi |
BullMonitorHapi: server.register(monitor.plugin). Congelado em apollo-server-hapi v3 |
@bull-horizon/cli |
Binário bull-horizon, painel standalone sem integrar com app |
Todos os pacotes têm a mesma versão. Instale o adapter e o root na mesma versão (o adapter de fila é importado do root):
# estável (latest)
npm i @bull-horizon/express @bull-horizon/root
# beta com runs de agente (tag `beta`): fixe a versão exata nos dois
npm i @bull-horizon/express@6.5.0-beta.0 @bull-horizon/root@6.5.0-beta.0
Runs de agente (ai, createAgentRun, tela Agents) existem a partir da 6.5.0-beta.0. Pre-release não casa com range: ^6.5.0 não instala a beta, e ^6.4.0 nunca sobe sozinho para ela. Enquanto estiver em beta, use a versão exata. Quando a 6.5.0 sair como latest, troque para ^6.5.0.
Bull vs BullMQ: o adapter de fila define o provider. Mesmas opções nos dois.
import { BullAdapter } from '@bull-horizon/root/dist/bull-adapter'; // fila do pacote `bull`
import { BullMQAdapter } from '@bull-horizon/root/dist/bullmq-adapter'; // fila do pacote `bullmq`
new BullAdapter(queue, { group: 'App', readonly: false, ai: undefined });
| Opção da fila | Efeito |
|---|---|
group |
Rótulo cosmético: agrupa filas numa entrada recolhível da sidebar |
readonly |
Esconde/bloqueia ações que alteram jobs (retry, remove, add...) |
ai |
Marca fila de agente (true ou AgentQueueConfig). Ver references/agent-runs.md |
Config do monitor (new BullMonitorX({...})): queues (obrigatório), metrics (off por padrão), prometheus (off), ai (pricing e recentRuns), flows e flowsOptions (ver references/flows.md), baseUrl (Fastify/Koa/Hapi), gqlIntrospection (default: true fora de produção), textSearchScanCount (500).
Fluxo de decisão
- Qual framework? NestJS ou Express:
@bull-horizon/express. Fastify, Koa, Hapi: o pacote correspondente. Só quer olhar filas sem mexer na app: CLI. Receitas emreferences/setup-nestjs.md. - Qual lib de fila?
bull→BullAdapter.bullmq→BullMQAdapter. Uma instância de adapter por fila. - Quais filas? Todas as que o time precisa ver. Cada uma passada explicitamente em
queues. - Grupos? Mais de ~4 filas ou fluxos distintos: um mapa
QUEUE_GROUPSnome → grupo. - Histórico? Precisa de gráfico de throughput, tela Metrics history, ou abas Metrics/Runs de agente:
metrics: {}(ou com retenção custom). Verreferences/metrics-and-prometheus.md. - Prometheus/Grafana?
prometheus: true+metrics. Rota sem auth: proteja igual ao painel. - Fila de agente de IA?
aina fila,createAgentRunno worker (job que não chama o modelo:await recorder.skip('motivo')oumarkAgentRunSkipped),removeOnCompletenumérico,ai.pricingno monitor. Verreferences/agent-runs.md. - Item de negócio atravessa várias filas? Declare o flow em
flows(etapas = filas),startTracenas entradas,withTraceem todoqueue.adddo flow,encodeTrace/continueTraceem elo por webhook,metricsligado, retenção numérica. Verreferences/flows.md. - Quem acessa? Defina a proteção da rota antes de subir (Cloudflare Access, VPN, basic auth, middleware de sessão).
Regras de ouro
- Fila não passada ao monitor não aparece. Registrar a fila no módulo (
BullModule.registerQueue) não basta: o painel lista só as filas emqueues. Fila nova =@InjectQueueno service do monitor + adapter na lista + grupo no mapa. - Um grupo por fila, num mapa central (
QUEUE_GROUPS[queue.name]). Fila sem entrada no mapa fica fora de grupo (aparece solta). - Toda fila embrulhada num adapter. Passar a
Queuecrua (ou um adapter de outra cópia de@bull-horizon/root) faz a fila ser descartada comconsole.error('Since version 3.0.0 every queue should be wrapped...'). - Métricas são opt-in. Sem
metricsnão há throughput, Metrics history, nem abas Metrics/Runs de agente. Contagens ao vivo funcionam sem. - Métricas só contam com o monitor no ar. Nada é retroativo; restart deixa buraco. É observabilidade, não contabilidade.
- Fila de agente exige retenção numérica.
removeOnComplete: true/removeOnFail: trueapaga o run junto com o job (viralost). Use número ou{ age, count }. - Dado sensível =
detail: 'basic'(o default).fullgrava inputs/outputs de tool, textos e a fala do usuário no Redis e nos backups. - Mesmo
AgentQueueConfigno monitor e no worker. Um objeto exportado de um arquivo de constantes da fila. - Sem auth nativa. Quem alcança a rota lê e altera tudo (inclusive logs de job e GraphQL). Proteja a rota com algo antes do router.
await monitor.init()antes de montar o router/plugin.- Run de agente mora no
job.log, gravado pelocreateAgentRun.job.dataleva só ids, o processor dáawaitnofinish/faile retorna só uma referência, nunca o run. Ler o run doreturnvalueé só compatibilidade com worker antigo (verreferences/agent-runs.md§ 0). - Flow: trace em todo elo.
startTraceem toda entrada ewithTrace(job, data)em todoadddo flow; umaddsem ele quebra o caminho ali. Um trace por item (lote grande = um trace por item comparent), mesmoFlowConfigno monitor e no worker. - Chave de negócio do flow é id interno opaco (UUID, chave do banco). Nunca email, telefone, documento, nome, nem hash deles: a busca roda sem auth e vira oráculo de existência.
Snippet mínimo (Express)
import Express from 'express';
import Queue from 'bull';
import { BullMonitorExpress } from '@bull-horizon/express';
import { BullAdapter } from '@bull-horizon/root/dist/bull-adapter';
const app = Express();
const monitor = new BullMonitorExpress({
queues: [new BullAdapter(new Queue('emails', process.env.REDIS_URL), { group: 'App' })],
metrics: {}, // opcional: liga histórico
});
await monitor.init();
app.use('/bull', requireAuth, monitor.router); // requireAuth: seu middleware
Para NestJS (padrão canônico com BullMonitorService + módulo), use references/setup-nestjs.md.
Migração de @bull-monitor
- Trocar dependências:
@bull-monitor/<pkg>→@bull-horizon/<pkg>(mesma versão em todos). - Trocar imports, inclusive
@bull-monitor/root/dist/bull-adapter→@bull-horizon/root/dist/bull-adapter. - Classes, opções e a chave Redis de métricas (
bull_monitor::metrics::) não mudaram: o histórico existente continua. - CLI: binário
bull-monitor→bull-horizon. - Versões antigas (<6) dependiam de
apollo-server-*v2/v3; a v6 usa@apollo/serverv4 (exceto Hapi). Se o app já usa body parser próprio no Express,init({ disableBodyParser: true }). - Defaults de métricas mudaram na v6:
collectInterval1 min e retenção em camadas de 90 dias (antes 1 h e 100 pontos). Ajuste se dependia do antigo.
Referências
references/setup-nestjs.md: NestJS canônico (service + módulo), proteção da rota, snippets Express/Fastify/Koa/Hapi/CLI.references/metrics-and-prometheus.md:metrics, retenção em camadas, o que cada tela mostra, Prometheus e scrape.references/agent-runs.md: filas de agente de IA,createAgentRuncom AI SDK v6, basic vs full, conversa, pricing, erros comuns.references/flows.md: flows e traces: declarar o flow,startTrace/withTrace/continueTrace, retenção, status do trace, tetos, erros comuns.references/troubleshooting.md: sintoma → causa → correção.
Documentação completa no repositório: README.md, docs/agent-runs.md, docs/flows.md, examples/ (nest, express, fastify, koa, hapi, grafana) em https://github.com/marconneves/bull-horizon.