btcore-exporter

Simple Prometheus exporter for exposing various metrics from a full Bitcoin Core node.

Works on macOS and GNU/Linux systems.

Table of Contents

• Installing
  • Manual Setup
  • Make Setup
  • Docker Setup
• License

Installing

Manual Setup

🔨

1️⃣ Clone the repo on the same machine where the Bitcoin Core node is running.

git clone https://github.com/joetor5/bitcoin-core-exporter.git
cd bitcoin-core-exporter

2️⃣ Create a Python venv and install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3️⃣ Start the exporter

chmod +x bitcoin_exporter.py
./bitcoin_exporter.py &

This will start the exporter http server on port 8000 and collect metrics every 60 seconds. You can select a different port with the -p arg. Run with -h arg for general usage and options.

4️⃣ View all the metrics (starting with bitcoin_)

curl http://localhost:8000/metrics

5️⃣ Modify the prometheus.yml config for pulling these metrics from the exporter

scrape_configs:

  - job_name: "bitcoin-core"
    scrape_interval: 60s
    static_configs:
      - targets: ["localhost:8000"]

6️⃣ Stop the exporter

pkill -f bitcoin_exporter

Make Setup

⚙️

1️⃣ Install make (if not already installed)

# Linux (Ubuntu)
sudo apt install make 

# macOS
brew install make      

2️⃣ Set up the virtual environment

make venv

3️⃣ Start the exporter

make run

4️⃣ Stop the exporter

make stop

5️⃣ Reset the virtual environment (optional)

If you want to reset your environment, you can delete the virtual environment and set it up again:

make clean  # Removes the virtual environment
make venv   # Recreates the virtual environment

6️⃣ Enable auto-start on reboot (optional)

If you want the Bitcoin Core exporter to start automatically when your system reboots, you can run:

make boot

This will:

• Generate a startup script (~/.bitcoin_exporter_boot.sh)
• Register the script in crontab to run on reboot

You can verify the scheduled job with:

crontab -l

If you want to remove the auto-start feature, run:

crontab -e

and delete the line that contains: @reboot ~/.bitcoin_exporter_boot.sh

Docker Setup

🐳

1️⃣ Install Docker (if not already installed)

# Linux (Ubuntu)
sudo apt update
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker

To check if Docker is installed:

docker --version
sudo systemctl status docker

✅ If you see the Docker version and the service active (running), installation is complete.

2️⃣ Add user to Docker group (optional, prevents needing sudo)

sudo usermod -aG docker $USER
newgrp docker

3️⃣ Start the container (Docker Compose)

In the project root directory, run:

docker compose up -d

✅ This will build the Docker image, start running it in the background, and set it to start on system boot.

If for some reason you can't run the Docker compose command, execute step #4 and #5 to build and run the image manually.

4️⃣ Build the Docker image (skip if step #3 was executed)

In the project root directory, run:

docker build -t bitcoin-exporter .

✅ This will create a Docker image named bitcoin-exporter.

5️⃣ Run the container (skip if step #3 was executed)

To start the exporter in a container:

docker run -d -p 8000:8000 --name bitcoin-exporter bitcoin-exporter

✅ This runs bitcoin_exporter.py in the background.

6️⃣ Verify that it's running

Check running containers:

docker ps

If the bitcoin-exporter container is running, test the metrics endpoint:

curl http://localhost:8000/metrics

✅ If you see Bitcoin metrics, the exporter is working!

7️⃣ Stop and remove the container (Docker Compose)

docker compose down

8️⃣ Stop and remove the container (manual, skip if step #7 was executed)

To stop the running container:

docker stop bitcoin-exporter

To remove the container:

docker rm bitcoin-exporter

To delete the image:

docker rmi bitcoin-exporter

9️⃣ Update the container image (Docker Compose)

Pull the latest changes:

git pull

Then stop the container, rebuild the image, and restart the container:

docker compose down
docker compose up --build -d && docker image prune -f

If Docker Compose is not an option, simply execute steps #8, #4, and #5 (in that order) for updating the image.

License

Distributed under the MIT License. See the accompanying file LICENSE.