🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
      • 🔸April 2025
      • 🔸May 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • Requirements
  • Creating a Grafana Cloud account
  • Configuring the Signer and the Stacks node
  • Install Alloy
  • Configure Alloy
  • Visualizing the metrics
  • Bonus: monitoring the host

Was this helpful?

  1. Guides & Tutorials
  2. Run a Signer

How to Monitor a Signer

PreviousHow to Read Signer LogsNextBest practices for running a Signer

Last updated 3 months ago

Was this helpful?

We will use to observe and monitor both the Signer and its corresponding Stacks node.

Requirements

Grafana's application observability docs have a . We will use:

  • Grafana Cloud to collect metrics and visualize them.

  • Grafana Alloy, on the Signer host, to push the metrics.

Creating a Grafana Cloud account

Before we begin, create a account (they offer a free tier that you can use).

Once done, access your dashboard and:

  1. Click on "Connections", then

  2. "Add new connection", and

  3. select "Hosted Prometheus metrics".

  4. Now select "Via Grafana Alloy", then

  5. On step 2, select "Run Grafana Alloy" to generate an API token.

Note the token GCLOUD_RW_API_KEY and the parameters GCLOUD_HOSTED_METRICS_URL and GCLOUD_HOSTED_METRICS_ID, we will use them later.

Configuring the Signer and the Stacks node

Ensure both your Signer configuration and your node configuration include the following lines:

# signer-config.toml
# ...
# Adjust to 0.0.0.0:30001 if running in Docker.
metrics_endpoint = "127.0.0.1:30001"
# node-config.toml
[node]
# ...
# Adjust to 0.0.0.0:9153 if running in Docker.
prometheus_bind = "127.0.0.1:9153"

The pre-compiled binaries already include the monitoring feature. However, if you are compiling the application binaries yourself, remember to enable the Cargo feature monitoring_prom while building them, for example:

cargo build --features monitoring_prom,slog_json --release

Once both binaries are running with the updated configuration, you can peek at the metrics being exposed:

curl 127.0.0.1:30001/metrics

# HELP stacks_signer_current_reward_cycle The current reward cycle
# TYPE stacks_signer_current_reward_cycle gauge
stacks_signer_current_reward_cycle 95
# HELP stacks_signer_node_rpc_call_latencies_histogram Time (seconds) measuring round-trip RPC call latency to the Stacks node
# TYPE stacks_signer_node_rpc_call_latencies_histogram histogram
...
stacks_signer_node_rpc_call_latencies_histogram_bucket{path="/v2/info",le="0.005"} 0
stacks_signer_node_rpc_call_latencies_histogram_bucket{path="/v2/info",le="0.01"} 0
stacks_signer_node_rpc_call_latencies_histogram_bucket{path="/v2/info",le="0.025"} 0
stacks_signer_node_rpc_call_latencies_histogram_bucket{path="/v2/info",le="0.05"} 985
stacks_signer_node_rpc_call_latencies_histogram_bucket{path="/v2/info",le="0.1"} 1194
...

Also, you'll have a /info endpoint on the same port:

curl 127.0.0.1:30001/info

Install Alloy

On Debian-based distributions:

sudo apt install gpg
sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install alloy

Configure Alloy

  • GCLOUD_HOSTED_METRICS_URL

  • GCLOUD_HOSTED_METRICS_ID

  • GCLOUD_RW_API_KEY

// For a full configuration reference, see https://grafana.com/docs/alloy
// For a default configuration, integrating all environmental variables from Grafana Cloud
// see https://storage.googleapis.com/cloud-onboarding/alloy/config/config.alloy

logging {
  level = "warn"
}

prometheus.exporter.unix "default" {
  include_exporter_metrics = true
  disable_collectors       = ["mdadm"]
}

prometheus.scrape "default" {
  targets = array.concat(
    prometheus.exporter.unix.default.targets,
    [
      {
        // Self-collect metrics
        job         = "alloy",
        __address__ = "127.0.0.1:12345",
      },
      {
        // stacks-signer
        job         = "stacks-signer",
        __address__ = "127.0.0.1:30001",
      },
      {
        // stacks-node
        job         = "stacks-node",
        __address__ = "127.0.0.1:9153",
      },
    ],
  )

  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

prometheus.remote_write "metrics_service" {
  external_labels = {"instance" = constants.hostname}
  endpoint {
    # TODO: Edit the URL below with your Grafana production URL.
    # should end with /api/prom/push
    url = "<your GCLOUD_HOSTED_METRICS_URL>"

    # TODO: Edit with your Grafana Cloud ID and Token
    basic_auth {
      username = "<your GCLOUD_HOSTED_METRICS_ID>"
      password = "<your GCLOUD_RW_API_KEY>"
    }
  }
}
sudo systemctl daemon-reload
sudo systemctl enable alloy.service
sudo systemctl start alloy.service

Metrics from your Signer and node will now start being pushed to Grafana Cloud.

Visualizing the metrics

You can now start building a dashboard to visualize the metrics.

  1. Log-in to Grafana Cloud and create a new Dashboard.

  2. Pick the Prometheus instance you created before as the data source.

  3. Create a new panel and pick stacks_signer_current_reward_cycle from the metrics.

You should now be able to see Stacks' current reward cycle, as measured by the Signer, into the dashboard.

Bonus: monitoring the host

sudo apt install prometheus-node-exporter
sudo systemctl enable prometheus-node-exporter
sudo systemctl start prometheus-node-exporter

This will expose metrics on port 9100 of localhost.

We can now configure alloy to push them to Grafana. Edit your /etc/alloy/config.alloy file and add the following:

prometheus.scrape "default" {
  targets = array.concat([

  ...

    {
        job         = "node_exporter",
        __address__ = "127.0.0.1:9100",
    }

  ...
])}

Now reload alloy and check its status:

sudo systemctl reload alloy
sudo systemctl status alloy

Follow these instructions to install .

Edit the file /etc/alloy/config.alloy as follows, by taking care of replacing the placeholders related to the prometheus endpoint with the parameters obtained when creating a :

Grafana comes with powerful data visualization tools. You can read about how to query and transform data , while here you will find examples on how to build .

will kick-start your dashboard.

.

Since we are here, we can also monitor the host itself. Debian-based distributions make it very easy for us by using .

node_exporter provides a lot of metrics. Poke at them through the Grafana Explorer or use one of the many prepared dashboard (e.g., ) to see comprehensive information. Once you have a dashboard ready, you can also use it to configure a few alerts (e.g., on disk space, etc).

🛠️
Grafana Cloud
great quick-start
Grafana Cloud
Grafana Alloy
here
Prometheus queries
This template
node_exporter
this one
Grafana Cloud account before