Tracking: Subgraph Radio Frontend

[pete-fathom]

Introduction

As it operates, Subgraph Radio surfaces and handles a wide range of data, including:

• Messages flowing through the Graphcast network on the subgraph-radio partition (based on the content topic)
• Underlying Waku data (number of connected peers, boot nodes, other metadata)
• Miscellaneous data used for the Radio's internal operations

The Radio handles this data and saves some of it to an in-memory store. That store gets persisted to a local JSON file at an interval, in order for the Radio to pick up where it left off between reruns. The data in the store is made available through a GraphQL endpoint that is exposed on the Radio's HTTP server. Aside from that, some of the data flowing through the Radio is being tracked with the help of Prometheus metrics and can be optionally exposed for scraping by a Prometheus server. The combination of the data in the store and the metrics serves as a base for the Grafana dashboard configuration. We can already see that the Radio has access to a pool of useful data that can be sampled at any time.

Subgraph Radio also defines multiple helper functions that are used to gather external data, needed for it's internal logic. This includes helpers for querying data from different GraphQL APIs (Core Network Subgraph, Registry Subgraph), as well as different parts of the Indexer stack - Graph Node endpoint(s), (optionally) Indexer Management Server, etc. These helpers can be used to fetch any data that might not be readily available in the store, but can be important especially for more complex and highly specific tasks.

Problem statement

All of the data mentioned above is currently scattered in different places and it's hard for users to find what they need, especially if they want to dig deeper and understand a specific event, like when and why a POI divergence has happened, which Indexers agree or disagree with the user's locally generated POI, how they're separated in groups, and more. All this is in the context of the POI cross-checking feature of Subgraph Radio, but a user might also be interested to know when a Subgraph Developer has signalled an intent to upgrade their Subgraph, who that Developer is, when was the last time they published a new version, etc, in the case of the Subgraph Upgrade Pre-sync feature. Looking forward the use cases for a richer interface to the Radio's data set will only grow larger.

Existing tooling

Subgraph Radio users can currently utilise the Grafana dashboard JSON provided in the repo, in order to set up their dashboard and monitor different panels based on Prometheus metrics exposed by the Radio. That provides a snapshot of the current state of the Radio and also some historical data of how the metrics have changed over time.

While the Grafana dashboard is certainly helpful for monitoring the state of the Radio, diving further into the Radio's data needs to happen through the HTTP server's GraphQL API. The GraphQL API provides a lot of useful query options, it has its limitations, after all it can only serve data that's readily available to the Radio (in other words - data that is saved locally).

To illustrate the issue more clearly - let's say a user monitors Subgraph Radio using the Grafana dashboard, they notice a POI divergence for a given subgraph on a given block. They then use the HTTP server's GraphQL endpoint to see all the senders that have sent a public POI that differs from the user's locally generated public POI. This is enough manual work as it is, but on top of that the user is still unable to identify those senders by their display name or Indexer URL, for instance. To do that, the user would have to send more request to the Network subgraph GraphQL endpoint.

Potential solution

Abstract

Subgraph Radio can serve a frontend application that utilises the in-memory store to visualise POI comparison results, as well as other useful data. This frontend should provide an intuitive interface for users to click-through items and dig deeper into relevant data.

Specific (implementation ideas)

Basic

We can start with a single view, similar to the Comparison Results panel from the Grafana dashboard (also drawing inspiration from Poifier's interface). It's important to note that the goal of this frontend is not to mimick/duplicate the panels in the dashboard, the dashboard will remain in use, which is why we don't need to copy or replicate the other panels.

This Comparison Results table view should immediately convey the following information:

• Subgraphs being actively cross-checked
• Blocks that the comparisons have happened at
• The comparison results themselves
• Number of matching and divergent Subgraphs
• The consensus public POI for each Subgraph
• Stake weight of each public POI
• Sender groups (by public POI)

This table view should be customisable, users should be able to filter results by subgraph, block, comparison result, sender(s), etc. Applying more than one filter at a time should be supported as well. Users should also be able to click on items such as, for instance, Subgraph deployment hash, sender address, block number, to dig deeper and view all the information we can provide for that item (for instance if it's a block number - we should display all the Subgraphs that were compared at that block number, if it's a Subgraph - all the comparison results we've saved for that Subgraph, all the senders that have also attested public POIs for it, all the blocks we've compared it on, etc).

All of this filtering and partitioning of data should use client-side routing.

Advanced

After the basic tabular view is in place, we can start supporting more advanced operations, such as:

• Sending graphql requests to the Radio's internal GraphQL endpoint, for more custom and/or complex queries if needed
• Sending graphql requests to the Core Network and Registry Subgraphs to get more detailed sender data
• Interfacing with other parts of the Indexer stack like Graph Node endpoint(s), Indexer Agent, etc
• Sending messages
• Changing the Radio's configurations on the fly

Implementation Issues

• Replicate Comparison Results view in Subgraph Radio frontend #59

[hopeyen]

some quick feedbacks

Messages flowing through the Graphcast network on the subgraph-radio pubsub topic

subgraph-radio is not a pubsub topic, it is part of a content topic

The GraphQL API provides a lot of useful query options, it has its limitations, after all it can only serve data that's readily available to the Radio (in other words - data that is saved locally).

This limitation isn't true; there are existing resolvers that query network subgraph (basic indexer info) and we used to do computations upon query requests, which was improved through persisting states.

user is still unable to identify those senders by their display name or Indexer URL, for instance. To do that, the user would have to send more request to the Network subgraph GraphQL endpoint.

This point can be easily resolved through adding the desired fields in our existing queries to the network subgraph, or a new variant of the existing query that includes display name and url.

Sending graphql requests to the Radio's internal GraphQL endpoint, for more custom and/or complex queries if needed
Sending graphql requests to the Core Network and Registry Subgraphs to get more detailed sender data

There's existing graphql playground interfaces for radio and the subgraphs. I'm failing to see understand why this should be part of the subgraph radio FE.
If there should be an aggregated place for making graphql requests, it might be out of scope here.

Interfacing with other parts of the Indexer stack like Graph Node endpoint(s), Indexer Agent, etc

Could you provide an example of how to use this

Sending messages

What kind of messages? How is this different from graphcast-web?

Changing the Radio's configurations on the fly

This can be implemented independently; indexer can use the API to update a config and doesn't require a frontend.

---

Overall I think the problem statement can be solved without an FE. My main concerns being

• when do we expect an indexer to use the FE?
• If we know the type of info they might be interested in, why not have the radio operator automatically generate it and send it through notification?
• Does it really make sense for a radio to have a grafana dashboard, a http server with restful and graphql APIs, notifications, and a separate frontend?
• A listener radio frontend makes more sense to me as a page of graphops explorer
• It would be good to have a mermaid diagram demonstrating how the frontend is expected to interact with existing components of the radio/sdk, as well as initial sketches of what you think the initial page should look like.

[pete-fathom]

Good points @hopeyen

when do we expect an indexer to use the FE?

I'd expect Indexers to use the FE the same way they'd use the frontend view of poifier, when they want a more interactive and feature rich environment compared to the Grafana dashboard. It makes interacting with all of the other Radio components a lot easier, can be a "one stop shop", and can reduce a lot of manual workflow on the user's side, as well as make the flow a whole lot easier. Generally it could aid user experience a lot.

Does it really make sense for a radio to have a grafana dashboard, a http server with restful and graphql APIs, notifications, and a separate frontend?

Nothing wrong with multiple options of interacting with/monitoring the Radio I think, different users will have different preferences.

A listener radio frontend makes more sense to me as a page of graphops explorer

Yes, for aggregated data meant for the explorer, having a listener Radio running somewhere and querying its GraphQL endpoint, then visualising that on the explorer, seems like the best option. The Subgraph Radio frontend would help us on that front as well because we would undergo a similar effort here (fetching data from a Radio's GraphqQL endpoint and visualising it, with options for users to customise the views)

If we know the type of info they might be interested in, why not have the radio operator automatically generate it and send it through notification?

This can be harder to customise on the user's end compared to a frontend, it can also be a one-time thing and might not require a scheduled notification

What kind of messages? How is this different from graphcast-web?

It is very different because our "flagship" implementations of Graphcast and Subgraph Radio will always be in Rust, we would much rather use the Radio (that's already running) to send messages via a web interface using this frontend, compared to graphcast-js. Graphcast-js is for cases where an underlying Rust-based Radio isn't there.

Could you provide an example of how to use this

This can be as simple as just fetching and visualising data from them that might be relevant to Subgraph Radio

This can be implemented independently; indexer can use the API to update a config and doesn't require a frontend.

Agreed, but as with other things - a frontend makes it easier for the user.

There's existing graphql playground interfaces for radio and the subgraphs. I'm failing to see understand why this should be part of the subgraph radio FE.
If there should be an aggregated place for making graphql requests, it might be out of scope here.

We don't want to have "an aggregated place for making graphql requests", but we can alleviate the need of users having to construct their queries in the graphql playground(s) every time if we identify useful repeating queries, we can fetch and provide that data upfront (this can also be customised through the frontend).

This point can be easily resolved through adding the desired fields in our existing queries to the network subgraph, or a new variant of the existing query that includes display name and url.

This is fair. That way we can avoid needing multiple queries both on the GraphQL playground and in the frontend.

subgraph-radio is not a pubsub topic, it is part of a content topic

Ah my bad, that's more proper wording indeed.

This limitation isn't true; there are existing resolvers that query network subgraph (basic indexer info) and we used to do computations upon query requests, which was improved through persisting states.

I agree it's not true as far as the Radio's internal operations are concerned, but I think it still is when we consider what users can query for on the existing GraphQL endpoint.