Tezos-facts: machine-readable Tezos data, including a Prometheus service-discovery feed of public RPC nodes

Project Updates
1

Hi everyone,

I’d like to share tezos-facts, a small project that aggregates public information about Tezos public nodes into machine-readable JSON files, published for anyone to consume:

What it publishes

Every file is regenerated automatically from public sources:

  • merged_prometheus_sd.json — all known public Tezos RPC nodes, aggregated and deduplicated from teztnets.com, taquito.io, docs.tezos.com and octez.js, formatted as Prometheus HTTP service discovery. Targets carry labels like tezos_network, provider, and source_sd, so you can filter to just the networks or sources you care about.

Per-source SD files are also published if you’d rather consume a single source.

Using it with Prometheus

The main use case is chain health monitoring: watching the head level of public nodes to detect head drift or a stalled chain. merged_prometheus_sd.json plugs directly into http_sd_configs, and since Tezos nodes expose JSON RPC (not Prometheus metrics), you pair it with the Prometheus JSON exporter:

scrape_configs:
  - job_name: tezos_public_rpc_head
    metrics_path: /probe
    params:
      module: [tezos_head_header]
    http_sd_configs:
      - url: https://tezos-infra.gitlab.io/vigies/tezos-facts/merged_prometheus_sd.json
        refresh_interval: 1h
    relabel_configs:
      # SD target host -> the RPC URL the JSON exporter must fetch
      - source_labels: [__address__]
        target_label: __param_target
        replacement: https://${1}/chains/main/blocks/head/header
      - source_labels: [__address__]
        target_label: instance
      # send the scrape to the JSON exporter instead of the node
      - target_label: __address__
        replacement: json-exporter:7979

And the JSON exporter module (--config.file):

modules:
  tezos_head_header:
    metrics:
      - name: tezos_public_node_head_level
        help: "Head block level from /chains/main/blocks/head/header"
        path: '{ .level }'

From there, a simple max(tezos_public_node_head_level) by (tezos_network) gives you the public head of each network — useful as a reference point to alert when your own nodes drift behind, or when a chain halts entirely. This is exactly how we use it in production to monitor our node fleet.

If you run a public RPC endpoint that isn’t listed in the upstream sources, the best way to appear in the feed is to get listed there (teztnets, taquito, or docs.tezos.com).

Thanks @jevonearth for the json format on taquito :wink:

2 Likes