Glossary?

[vorburger]

@31z4 how about we create a "glossary" about what all the metrics mean and how to interpret the graphs on the dashboard?

It could be a MD in this repo, linked from on top of the dashboard?

I'm no expert at this myself, and I'm not aware of any great simple existing description... the closest seems to be https://docs.saturn.tech/saturn-rewards?

What do you think about something like the following, using the terminology from the dashboard you built in this repo:

https://explorer.saturn.tech shows total available earnings for the world, broken down by region, down to each nodes. (Q: Is that per... day? Do you have a graph to plot world earnings over time?)

Nodes close to each other (Q: by physical geography, or by ... IP routing nearness?) get traffic for retrieval distributed to them based on their respective Weights to each other. Getting higher (Approximate) Retrievals leads to higher FIL Earnings.

Weight is determined based on Bias (good, higher values improve weight [Q: Is this correct?!]) and Penalty (bad, higher values decrease weight [Q: Is this correct?!]).

Then there should ideally be some explanations about Bias and Penalty values.

Would you accept a PR to make a start with this?

[vorburger]

Then there should ideally be some explanations about Bias and Penalty values.

E.g. "health_check_failures are caused by an unexpectedly (not deregistered) unreachable node. Fix this by resolving the root cause of the node unavailability. This penalty spikes with each health check failure event, and then remains for a while after, but steadily decreases on its own." and more like this.

[vorburger]

Actually, maybe the doc itself that I've outlined above should go on https://github.com/filecoin-saturn/L1-node/blob/main/docs/faq.md#penalties, and the Moonlet Penalties dashboard could just link to that.

[31z4]

Hi @vorburger. Thanks for you interest in contributing to Saturn Moonlet 🙏

Yes, the glossary of some kind if definitely needed. In fact, I've already documented the metrics itself: 16d152d. So that one can see a short description of every exposed Prometheus metric when manually scraping or building new charts in Grafana:

$ curl -s localhost:9000 | grep saturn_node_response
# HELP saturn_node_response_duration_milliseconds The time it takes by average for the node to respond to a request.
# TYPE saturn_node_response_duration_milliseconds gauge
saturn_node_response_duration_milliseconds{id="7362435b-cce9-49d7-b6b9-b03abe1b0ee7",quantile="0.01"} 2000.0
saturn_node_response_duration_milliseconds{id="7362435b-cce9-49d7-b6b9-b03abe1b0ee7",quantile="0.05"} 2000.0
saturn_node_response_duration_milliseconds{id="7362435b-cce9-49d7-b6b9-b03abe1b0ee7",quantile="0.5"} 2000.0
saturn_node_response_duration_milliseconds{id="7362435b-cce9-49d7-b6b9-b03abe1b0ee7",quantile="0.95"} 2000.0
saturn_node_response_duration_milliseconds{id="7362435b-cce9-49d7-b6b9-b03abe1b0ee7",quantile="0.99"} 2000.0

As the next step I'm going to add more detailed description for every chart on the dashboards. The will be a little "i" icon on top of each chart that you can hover and see the description. Like here, but with more details:

To do that I will refer to the hints on the official dashboard and the info you've gathered in filecoin-saturn/L1-node#481