This page hosts a catalogue of widgets for visualising libp2p introspection data, built on the libp2p observer-toolkit.
- Usage
- Contribute a widget
To simply explore what the libp2p Observation Deck has to offer, visit the deployed page and select "Samples", then choose one of the pre-made sample files. This allows you explore the libp2p Observation Deck catalogue and try out widgets using mock libp2p data samples.
First, run libp2p using the Introspection module, and get the port number and URI of the libp2p Introspection endpoint. In the libp2p Observation Deck UI, open "Live Connection" and enter this as a websocket URL: for example, if the introspection module endpoint is introspect on port 12345, enter ws://localhost:12345/introspect.
If this works, a "loading" message should display and then the page will navigate to the libp2p Observation Deck catalogue.
The libp2p Observation Deck uses the libp2p Observer Shell which can export libp2p Introspection data as a binary file.
If you have such a file, you can import it using the "Upload a file" option, by either dragging the file into the opened "Upload a file" button or clicking again to use your operating system's usual file browser.
After selecting a data source, the libp2p Observation Deck catalogue is shown. This displays all widgets currently approved for inclusion. Each displays a screenshot and a short description.
Click on one to open it and use it to visualize the currently loaded libp2p Introspection data.
To close a widget and return to the catalogue, click the close "x" icon in the top right of the widget's header.
Most widgets have optional data filters. These can be set and unset by opening the "active filters" button on the right of the widget's header. While any widget-level filters are active, this button is highlighted and displays the number of currently active filters.
Unlike the "global" data filters set in the control panel, these filters only apply within the scope of the current widget and do not affect the data shown in the timeline or data exported using the Export data button. Their usage is the same in other ways, including having options to both disable and reset the filters.
The same widget description shown in the catalogue view may be accessed for the currently selected widget by opening the "About" button on the left side of the widget's header.
When data is available, the main part of the control panel along the bottom of the screen is an interactive timeline. Each libp2p Introspection data set includes a series of "state" messages giving metrics of libp2p subsystems at a moment in time, and the timeline allows users to scroll back through these state messages to inspect a particular moment.
To help the user spot interesting activity, an area chart visualisation of data traffic inbound and outbound data traffic is shown.
Clicking anywhere on the timeline selects that point in time. The magenta bar indicating the selected state jumps, and the area coverred by the bar indicates the selected time span, giving an indication of the resolution of the temporal resolution of the selected data as well as its position.
The bar may also be dragged, which will update visualisations as the bar moves, and may be nudged one message forward or backward using the keyboard left and right arrow keys.
Data after the currently selected time point is shaded to indicate that it is excluded from any visualisation in the currently selected widget.
When a point in time other than the latest is selected, an "x" icon is shown next to the current time label. Clicking this resets the timeline to the latest state message, allowing all available data to be included in the currently selected widget.
By default, as new data is received by a live websocket connection, it is immediately shown and the timeline bar stays at the rightmost point in the timeline.
When a point earlier than the latest has been selected, this selection persists and new data is appended to the timeline after the current selection, not updating the current widget.
Clicking the "x" to reset the timeline reverts to the default behaviour and resumes live updates of the widget.
When the data source is a websocket connection, the icon on the left of the control panel indicating the data source acts as a "play/pause" button. Clicking on it sends a "pause" or "start" signal to the libp2p Introspection server, instructing the server to queue new data instead of sending it.
Note that because the libp2p Introspection server may have already dispatched or queued messages, there may be a small amount of data received after "pausing".
To guide users towards interesting points in a libp2p Introspection data set, the timeline displays a visualisation of traffic over time. The yellow upper area indicates how much new inbound data was receieved during a time interval, and the blue lower area indicates how much outbound data was sent out during that time interval. Bands on these areas indicate particular connections.
Mouseover of a particular band in this visualisation highlights that connection's inbound and outbound data activity across the timeline. These user selections are shared with widgets allowing widgets to highlight items with the same Peer ID as the highlighted connections.
The current data source may be changed at any time by clicking the topmost button in the left side of the control panel. This opens the same interface for choosing a data source as on the home page: see section 1.1 for details.
Filters may be applied to centrally held data by clicking the "filter" button on the left side of the control panel. Any data removed by these filters is removed from every widget, from the timeline, and also excluded from data file exports.
When connected to a live websocket, filters are applied to all new incoming data as well as old data stored in memory.
While filters are active, this button is highlighted and indicates the number of currently active filters.
When selections have been made for a filter, a checkbox is shown to the left of the filter name allowing users to disable the filter without clearing the current selection. This can be useful for quickly toggling a filter on and off to see what data changes.
Filter controls can be reset, clearing all selections to the default state, using the "x" icon to the right of the filter name.
The current loaded data, after applying global filters, may be exported as a binary file that can be loaded into the libp2p Observation Deck (or other tools built on libp2p Observer Catalogue). The file format used for these files is described in the libp2p Observer file format docs, and matches the format of binary sent and recieved over websockets.
Clicking the Export Button prepares data for export and displays the current file size of the binary to be exported. Clicking this button downloads this binary file, with a datestamped filename.
The Peer Id of the libp2p node acting as data source is displayed in the control panel for reference. It is displayed as a "PeerId Avatar" from the libp2p Observer SDK, and this same presentation may be used in widgets.
Each Peer ID displayed using this avatar format shows an automatically-generated hexagonal image with coloured segments. These colours are generated from the hash of the full Peer ID, and will be the same any time this Peer ID appears. In visualisations that include many Peer IDs, this may help users to spot frequently-appearing Peer Ids and help users follow peer ids that move as data changes.
The last 5 characters of the Peer ID are shown. This can help users locate occurences of a particular Peer ID using tools such as "find".
On mouseover of a Peer ID avatar, the full Peer ID string is shown, along with a button that immediately copies the full Peer ID to the clipboard.
The last button in the left side of the control panel opens a window that displays information about the libp2p node providing the data, its environment, and the settings of the libp2p Introspection server.
This refers to the implementation of the P2P engine being used. For example, an entry go-libp2p indicates that the data is coming from a node using go-libp2p, the golang implementation of libp2p.
This gives the version number of the P2P implementation described above.
This gives the operating system on which the given P2P implemenation is running.
This indicates the frequency at which state messages are being generated by the libp2p Introspection server, and therefore indicates the granularity of data on the timeline.
On live websocket connections, this is edittable: a new interval duration may be set and a signal will be sent to the libp2p Introspection server to start generating and sending state messages at this new frequency.
This indicates the maximum amount of time old messages will be kept for before being discarded to potentially free memory.
On live websocket connections, this is edittable: a new cutoff time may be set and a signal will be sent to the libp2p Introspection server allowing it to update its settings, and the app's own datastore will start discarding data older than this given time.
If memory issues are found using the libp2p Observation Deck on a system with limited memory or in a context where a very large amount of data is being sent, lowering this setting may improve performance.
This project is open to community-created widgets, and will include high quality, useful widgets that have been approved by the core team.
To contribute a widget:
-
See if any project to create a widget similar to your idea already exists. It is advisable to post a discussion issue on this repo discussing your idea before starting work.
-
Create a libp2p Observer widget
- Run the libp2p Observer create widget script (no prior installation or local setup needed)
- Follow the libp2p Observer developer guide and other documentation on the libp2p Observer project.
-
Post the widget to GitHub and publish it to NPM
-
Post a PR to this repo following the Contribution Guidelines