{"id":20388285,"url":"https://github.com/libp2p/observation-deck","last_synced_at":"2025-07-19T08:04:12.621Z","repository":{"id":66118949,"uuid":"265962534","full_name":"libp2p/observation-deck","owner":"libp2p","description":"🐣 [WIP] Catalogue of widgets for visualising libp2p introspection data, built on libp2p/observer-toolkit","archived":false,"fork":false,"pushed_at":"2025-05-09T20:02:32.000Z","size":15781,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-09T21:20:24.980Z","etag":null,"topics":["libp2p","observability"],"latest_commit_sha":null,"homepage":"https://libp2p.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libp2p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-21T22:14:58.000Z","updated_at":"2025-05-09T20:02:36.000Z","dependencies_parsed_at":"2024-01-31T18:04:29.582Z","dependency_job_id":null,"html_url":"https://github.com/libp2p/observation-deck","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/libp2p/observation-deck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libp2p%2Fobservation-deck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libp2p%2Fobservation-deck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libp2p%2Fobservation-deck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libp2p%2Fobservation-deck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libp2p","download_url":"https://codeload.github.com/libp2p/observation-deck/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libp2p%2Fobservation-deck/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265904251,"owners_count":23846673,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["libp2p","observability"],"created_at":"2024-11-15T03:08:32.276Z","updated_at":"2025-07-19T08:04:12.568Z","avatar_url":"https://github.com/libp2p.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# observation-deck\n\n**[Deployed here][1]**\n\nThis page hosts a catalogue of widgets for visualising libp2p introspection data, built on the [libp2p observer-toolkit](https://github.com/libp2p/observer-toolkit).\n\n\u003c!-- MarkdownTOC --\u003e\n\n- [Usage](#usage)\n  - [1. Connecting to libp2p Introspection data](#1-connecting-to-libp2p-introspection-data)\n    - [1.1 Try it out without your own data](#11-try-it-out-without-your-own-data)\n    - [1.2 Connect to a libp2p Introspection node](#12-connect-to-a-libp2p-introspection-node)\n    - [1.3 Upload a file](#13-upload-a-file)\n  - [2. Choosing a widget](#2-choosing-a-widget)\n    - [2.1 Closing a widget](#21-closing-a-widget)\n    - [2.2 Using widget data filters](#22-using-widget-data-filters)\n    - [2.3 About the current widget](#23-about-the-current-widget)\n  - [3. Using the timeline](#3-using-the-timeline)\n    - [3.1 Selecting a point in time](#31-selecting-a-point-in-time)\n    - [3.2 Resetting to the latest point in time](#32-resetting-to-the-latest-point-in-time)\n    - [3.3 Showing incoming live data](#33-showing-incoming-live-data)\n    - [3.4 Pausing live data](#34-pausing-live-data)\n    - [3.5 Timeline traffic visualisation](#35-timeline-traffic-visualisation)\n  - [4. Changing a data source](#4-changing-a-data-source)\n  - [5. Global data filters](#5-global-data-filters)\n    - [5.1 Active filters](#51-active-filters)\n    - [5.2 Disabling filters](#52-disabling-filters)\n    - [5.3 Reseting filters](#53-reseting-filters)\n  - [6. Exporting data](#6-exporting-data)\n  - [7. Peer Ids](#7-peer-ids)\n    - [7.1. Peer Id avatar image](#71-peer-id-avatar-image)\n    - [7.2. Peer Id snippet](#72-peer-id-snippet)\n    - [7.3. Full Peer ID in tooltip](#73-full-peer-id-in-tooltip)\n  - [7.4. Info and Settings](#74-info-and-settings)\n    - [7.4.1. Implementation](#741-implementation)\n    - [7.4.2. Version](#742-version)\n    - [7.4.3. Platform](#743-platform)\n    - [7.4.4. \"State messages every:\"](#744-state-messages-every)\n    - [7.4.5. \"Discard data after:\"](#745-discard-data-after)\n- [Contribute a widget](#contribute-a-widget)\n\n\u003c!-- /MarkdownTOC --\u003e\n\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n## Usage\n\n\u003ca id=\"1-connecting-to-libp2p-introspection-data\"\u003e\u003c/a\u003e\n### 1. Connecting to libp2p Introspection data\n\n\u003ca id=\"11-try-it-out-without-your-own-data\"\u003e\u003c/a\u003e\n#### 1.1 Try it out without your own data\n\nTo simply explore what the libp2p Observation Deck has to offer, visit the [deployed page][1] 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.\n\n\u003ca id=\"12-connect-to-a-libp2p-introspection-node\"\u003e\u003c/a\u003e\n#### 1.2 Connect to a libp2p Introspection node\n\nFirst, 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`.\n\nIf this works, a \"loading\" message should display and then the page will navigate to the libp2p Observation Deck catalogue.\n\n\u003ca id=\"13-upload-a-file\"\u003e\u003c/a\u003e\n#### 1.3 Upload a file\n\nThe libp2p Observation Deck uses the [libp2p Observer Shell](https://github.com/libp2p/observer-toolkit/tree/master/packages/shell) which can export libp2p Introspection data as a binary file.\n\nIf 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.\n\n\u003ca id=\"2-choosing-a-widget\"\u003e\u003c/a\u003e\n### 2. Choosing a widget\n\nAfter 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.\n\nClick on one to open it and use it to visualize the currently loaded libp2p Introspection data.\n\n\u003ca id=\"21-closing-a-widget\"\u003e\u003c/a\u003e\n#### 2.1 Closing a widget\n\nTo close a widget and return to the catalogue, click the close \"x\" icon in the top right of the widget's header.\n\n\u003ca id=\"22-using-widget-data-filters\"\u003e\u003c/a\u003e\n#### 2.2 Using widget data filters\n\nMost 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.\n\nUnlike the [\"global\" data filters set in the control panel](#5-global-data-filters), 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](#6-exporting-data) button. Their usage is the same in other ways, including having options to both [disable](#52-disabling-filters) and [reset](#53-reseting-filters) the filters.\n\n\u003ca id=\"23-about-the-current-widget\"\u003e\u003c/a\u003e\n#### 2.3 About the current widget\n\nThe 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.\n\n\u003ca id=\"3-using-the-timeline\"\u003e\u003c/a\u003e\n### 3. Using the timeline\n\nWhen 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.\n\nTo help the user spot interesting activity, an area chart visualisation of data traffic inbound and outbound data traffic is shown.\n\n\u003ca id=\"31-selecting-a-point-in-time\"\u003e\u003c/a\u003e\n#### 3.1 Selecting a point in time\n\nClicking 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.\n\nThe 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.\n\nData after the currently selected time point is shaded to indicate that it is excluded from any visualisation in the currently selected widget.\n\n\u003ca id=\"32-resetting-to-the-latest-point-in-time\"\u003e\u003c/a\u003e\n#### 3.2 Resetting to the latest point in time\n\nWhen 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.\n\n\u003ca id=\"33-showing-incoming-live-data\"\u003e\u003c/a\u003e\n#### 3.3 Showing incoming live data\n\nBy 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.\n\nWhen 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.\n\nClicking the \"x\" to [reset the timeline](#32-resetting-to-the-latest-point-in-time) reverts to the default behaviour and resumes live updates of the widget.\n\n\u003ca id=\"34-pausing-live-data\"\u003e\u003c/a\u003e\n#### 3.4 Pausing live data\n\nWhen 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.\n\nNote that because the libp2p Introspection server may have already dispatched or queued messages, there may be a small amount of data received after \"pausing\".\n\n\u003ca id=\"35-timeline-traffic-visualisation\"\u003e\u003c/a\u003e\n#### 3.5 Timeline traffic visualisation\n\nTo 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.\n\nMouseover 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.\n\n\u003ca id=\"4-changing-a-data-source\"\u003e\u003c/a\u003e\n### 4. Changing a data source\n\nThe 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.\n\n\u003ca id=\"5-global-data-filters\"\u003e\u003c/a\u003e\n### 5. Global data filters\n\nFilters 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.\n\nWhen connected to a live websocket, filters are applied to all new incoming data as well as old data stored in memory.\n\n\u003ca id=\"51-active-filters\"\u003e\u003c/a\u003e\n#### 5.1 Active filters\n\nWhile filters are active, this button is highlighted and indicates the number of currently active filters.\n\n\u003ca id=\"52-disabling-filters\"\u003e\u003c/a\u003e\n#### 5.2 Disabling filters\n\nWhen 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.\n\n\u003ca id=\"53-reseting-filters\"\u003e\u003c/a\u003e\n#### 5.3 Reseting filters\n\nFilter controls can be reset, clearing all selections to the default state, using the \"x\" icon to the right of the filter name.\n\n\u003ca id=\"6-exporting-data\"\u003e\u003c/a\u003e\n### 6. Exporting data\n\nThe current loaded data, after applying [global filters](#5-global-data-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](https://github.com/libp2p/observer-toolkit/tree/master/packages/catalogue)). The file format used for these files is described in the [libp2p Observer file format docs](https://github.com/libp2p/observer-toolkit/blob/master/docs/file-format.md), and matches the format of binary sent and recieved over websockets.\n\nClicking 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.\n\n\u003ca id=\"7-peer-ids\"\u003e\u003c/a\u003e\n### 7. Peer Ids\n\nThe 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.\n\n\u003ca id=\"71-peer-id-avatar-image\"\u003e\u003c/a\u003e\n#### 7.1. Peer Id avatar image\n\nEach 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.\n\n\u003ca id=\"72-peer-id-snippet\"\u003e\u003c/a\u003e\n#### 7.2. Peer Id snippet\n\nThe 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\".\n\n\u003ca id=\"73-full-peer-id-in-tooltip\"\u003e\u003c/a\u003e\n#### 7.3. Full Peer ID in tooltip\n\nOn 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.\n\n\u003ca id=\"74-info-and-settings\"\u003e\u003c/a\u003e\n### 7.4. Info and Settings\n\nThe 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.\n\n\u003ca id=\"741-implementation\"\u003e\u003c/a\u003e\n#### 7.4.1. Implementation\n\nThis 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`](https://github.com/libp2p/go-libp2p), the [golang](https://golang.org/) implementation of [libp2p](https://github.com/libp2p).\n\n\u003ca id=\"742-version\"\u003e\u003c/a\u003e\n#### 7.4.2. Version\n\nThis gives the version number of the P2P implementation described above.\n\n\u003ca id=\"743-platform\"\u003e\u003c/a\u003e\n#### 7.4.3. Platform\n\nThis gives the operating system on which the given P2P implemenation is running.\n\n\u003ca id=\"744-state-messages-every\"\u003e\u003c/a\u003e\n#### 7.4.4. \"State messages every:\"\n\nThis 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.\n\nOn 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.\n\n\u003ca id=\"745-discard-data-after\"\u003e\u003c/a\u003e\n#### 7.4.5. \"Discard data after:\"\n\nThis indicates the maximum amount of time old messages will be kept for before being discarded to potentially free memory.\n\nOn 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.\n\nIf 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.\n\n\u003ca id=\"contribute-a-widget\"\u003e\u003c/a\u003e\n## Contribute a widget\n\nThis project is open to community-created widgets, and will include high quality, useful widgets that have been approved by the core team.\n\nTo contribute a widget:\n\n - 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.\n\n - Create a [libp2p Observer](https://github.com/libp2p/observer-toolkit) widget\n   - Run the [libp2p Observer create widget](https://github.com/libp2p/observer-toolkit/tree/master/packages/create-widget) script (no prior installation or local setup needed)\n   - Follow the [libp2p Observer developer guide](https://github.com/libp2p/observer-toolkit/blob/master/docs/file-format.md) and other documentation on the [libp2p Observer](https://github.com/libp2p/observer-toolkit) project.\n - Post the widget to GitHub and publish it to NPM\n - Post a PR to this repo following the [Contribution Guidelines](./contribute.md)\n\n[1]: https://libp2p.github.io/observation-deck/\n[2]: https://github.com/libp2p/go-libp2p/issues/775\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibp2p%2Fobservation-deck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibp2p%2Fobservation-deck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibp2p%2Fobservation-deck/lists"}