This is an all-in-one tool to help you visualize and report on bull! It runs as a docker container that you can spin up with local development or host wherever you see fit. The core goal of this project is to provide realtime integration of your bull queues with existing bull tooling...without needing to run write any custom code. The following is automatically included:

• Automatic discovery of your bull queues (just point this at your redis instance)
• Automatic configuration of prometheus metrics for each discovered queue
• Configurable UI support to visualize bull queues (supported: arena, bull-board, bull-master)
• Sentry error reporting (just pass SENTRY_DSN environment variable)
• Elastic ECS logging when NODE_ENV is set to production
• Bundled oauth2_proxy if you want to restrict access (disabled by default)

You can test it out with docker by running (if you want to access something running on your host machine and not within the docker network you can use the special hostname host.docker.internal):

docker run -d --rm \
  --name bull-monitor \
  -e "NODE_ENV=development" \
  -e "REDIS_HOST=host.docker.internal" \
  -e "REDIS_PORT=6001" \
  -e "PORT=3000" \
  -e "BULL_WATCH_QUEUE_PREFIXES=bull" \
  -e "UI=bull-master" \
  -p 3000:3000 \
  ejhayes/nodejs-bull-monitor:latest

To use with docker compose, add the following to docker-compose.yml:

bull-monitor:
  image: ejhayes/nodejs-bull-monitor:latest
  ports:
    - 3000:3000
  environment:
    REDIS_HOST: <your redis host>
    REDIS_PORT: <your redis port>
    BULL_WATCH_QUEUE_PREFIXES: bull
    PORT: 3000
    UI: bull-master

Then run docker-compose up bull-monitor. Assuming no issues, the following paths are available:

The following environment variables are supported:

To get started:

npm install
npm run services:start
npm run start:dev

If you want to run the tests:

npm run test
npm run test:e2e

To build the container (will be built/tagged as ejhayes/nodejs-bull-monitor):

npm run ci:build

A test script is included so you can try creating and/or processing bull jobs. Examples:

# create a queue and add jobs to it (no processing)
npm run generate:create

# process queue jobs only
npm run generate:process

# create and process jobs
npm run generate

The default behavior of npm run generate is to:

• Create MyBullQueue queue if it doesn't exist.
• Add a dummy job every 10 milliseconds.
• Add a worker that with concurrency 15 that processes up to 200 jobs per 1 second (jobs retried up to 4 times).
• Configure each job to take up to 200 milliseconds. Jobs can fail randomly.

See ./test.ts for more details.

NOTE: metrics are available at the /metrics endpoint

For each queue that is created the following metrics are automatically tracked.

The following labels are available:

Things to note about these metrics:

• Queue metrics are GLOBAL not worker specific
• Gauge metrics (*_total) are refreshed every 60 seconds. To change this you'll need to set environment variable BULL_COLLECT_QUEUE_METRICS_INTERVAL_MS to another value.

You can visualize your queue metrics in Grafana! There are several pieces that need to be running for this to work:

• bull-monitor - this utility must be running (and the /metrics endpoint should be accessible)
• prometheus - you need to be running prometheus and have it configured to scrape bull-monitor
• grafana - grafana needs to be setup and configured to scrape data from prometheus

If you want to play around with a local setup of this:

# start services
npm run services:start
npm run start:dev

# generate/process dummy data
npm run generate

You can now go to: http://localhost:3001/dashboard/import and load dashboards:

Grafana Dashboard Name	Grafana ID	Description	Screenshot
Queue Overview	14538	High level overview of all monitored bull queues
Queue Specific	14537	Queue specific details

There are 3 options currently available for UIs: bull-board, arena, and bull-master.

From: https://github.com/felixmosh/bull-board#readme. This is the default UI. If you want to be explicit just set UI environment variable to bull-board.

From: https://github.com/hans-lizihan/bull-master. To use this UI you'll need to set the UI environment variable to bull-master.

From: https://github.com/bee-queue/arena. To use this UI you'll need to set the UI environment variable to arena.

You can restrict access to bull monitor using the built in OAuth2 proxy. To enable you'll need the following environment variables at a minimum:

• USE_OAUTH2_PROXY (must be set to 1)
• OAUTH2_PROXY_REDIRECT_URL (this is what the oauth provider will be redirecting to)
• OAUTH2_PROXY_CLIENT_ID
• OAUTH2_PROXY_SECRET_ID

Many other configuration options are possible. See the OAuth2 Proxy documentation for more information.

• This is intended as a back office monitoring solution. You should not make expose this publicly
• This is currently intended to run as a single process and should not be scaled horizontally (future todo item)

You can spin up a full local development environment by running:

# start services
npm run services:start
npm run start:dev

The following services are available (and automatically configured) at these locations:

• Grafana UI: http://localhost:3001
• Prometheus: http://localhost:3002
• SMTP (Mailhog): http:localhost: http://localhost:3003 (username: test, password: test)
• Redis: localhost:6001
• SMTP Server (used by Grafana Alerts): localhost:6002 (no auth required, no encryption)

When you are done you can get rid of everything with:

npm run services:remove

# OR if you want to stop without removing
npm run services:stop

See the roadmap for idas on how to improve this project.

Thanks goes to these wonderful people (emoji key):

Eric Hayes 📖 🚇 ⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome!