On June 1st, 2024, the Saturn node provider program was concluded.

Saturn Moonlet

Filecoin Saturn monitoring for node operators. More powerful and insightful alternative to Saturn Node Dashboard that anyone can run.

Saturn Moonlet provides a node operator with the following:

• Real-time and historical metrics about node stats and earnings.
• Ability to run arbitrary PromQL queries against node metrics.
• Ability to build custom dashboards.
• Alerts based on metrics.
• Anything else that Grafana and Prometheus can do 😉

It does not require installing any additional software on a Saturn node. You only need Docker Compose to run it locally or on your server.

If you're interested, you can see how it's made.

This project is neither affiliated with the Filecoin Saturn project nor the Protocol Labs organization. Although, it was built during the HackFS 2023 hackaton and was nominated for the "Best use of Filecoin Saturn" prize 🥇

Try it

Public version is available at moonlet.cronian.tech.

Note that public version offers limited features allowing you only to evaluate and test Saturn Moonlet. It is not an end product and provided "AS IS".

Run locally

It's easy to run Saturn Moonlet locally using Docker Compose:

# Clone the repo and change the current directory.
git clone https://github.com/cronian-tech/saturn-moonlet.git
cd saturn-moonlet

# Create empty environment files, so that you can customize service configuration if needed.
touch docker/prometheus-exporter/.env
touch docker/grafana/local/.env

# Run services in the background.
docker compose --profile local up -d

This command will start Prometheus Exporter, Prometheus, and Grafana services listening on localhost with persistent storage in Docker volumes.

Go to http://localhost:3000 and check out the dashboard 🌖

Run in production

For production, Grafana is configured to use HTTPS for secure web traffic. It's up to you how to obtain an SSL certificate and a key for encryption. For example, check Grafana documentation for possible options.

Once you've got a certificate and a key, you must place it to docker/grafana/ssl under the following names:

$ ls docker/grafana/ssl
grafana.crt grafana.key

Production Grafana configuration is almost similar to default except for HTTPS (see docker/grafana/production/grafana.ini). You can override this configuration by setting environment variables in docker/grafana/production/.env.

For example, override the default admin user, password, and email:

cat << EOF > docker/grafana/production/.env
GF_SECURITY_ADMIN_USER=saturn
GF_SECURITY_ADMIN_PASSWORD=SuperSecret
GF_SECURITY_ADMIN_EMAIL=example@email.com
EOF

If you don't want to override anything, simply create an empty environment file for Grafana:

touch docker/grafana/production/.env

By default Prometheus Exporter observes all nodes in the network. If that's what you need, just create and empty environment file for Prometheus Exporter, and you're ready to go.

touch docker/prometheus-exporter/.env

Otherwise, list specific node IDs in a file and point Prometheus Exporter to that file:

# Create conf directory if does not exist.
mkdir -p docker/prometheus-exporter/conf

# Specify node IDs.
cat << EOF > docker/prometheus-exporter/conf/nodes.txt
9b7c3402-e90f-4d12-833d-ccb50a3c261d
2aadfe2c-2111-4602-9bf9-1b38884b02e7
EOF

# Tell Prometheus Exporter to observe specific node IDs.
# Note that path to the file is within a Docker container.
echo SATURN_PROMETHEUS_EXPORTER_NODES=/conf/nodes.txt > docker/prometheus-exporter/.env

Now everything is ready to launch Saturn Moonlet 🚀

docker compose --profile production up -d

TODO

The following is the non-exhaustive list of highlights about what's expected in the upcoming versions of Saturn Moonlet. Please leave feedback in the linked issues if you're interested in particular features.

• Automate TLS certificate management for self-hosted
• Improve Prometheus Exporter reliability
• Add metrics for failed scrapes to Prometheus Exporter
• Add charts for health check failures to Saturn Node Details dashboard
• Visualise node state on Saturn Node Details dashboard
• Optional metrics backfill for self-hosted
• Optional Saturn node logs ingestion for self-hosted

How it's made

Saturn Moonlet consists of thee main components.

• Prometheus Exporter is a Python service that fetches node stats and earnings via the same public HTTP APIs that Saturn Node Dashboard uses. It exposes this info in a simple text-based format.
• Prometheus periodically scrapes metrics exposed by Prometheus Exporter and persists these metrics in a local on-disk time series database. Prometheus stores historical data about node stats and earnings.
• Grafana uses Prometheus as a data source and provides a node operator with powerfull web interface to query and visualize node metrics. It comes with two pre-defined dashboards to overview nodes in the network and see details about a particular node. It also allows to configure alerts.

License

This project is licensed under the MIT License - see the LICENSE file for details.