Docs: Enhance datasource READMEs #254

josmperez · 2024-03-17T23:55:53Z

Enhance READMEs for datasource plugins. Note that installation information was missing for a few of these plugins and I have drafted some content based on similar plugins, but this needs to be checked for accuracy.

sympatheticmoose

Some initial comments

examples/datasource-basic/README.md

examples/datasource-http-backend/README.md

examples/datasource-http/README.md

examples/datasource-streaming-backend-websocket/README.md

examples/datasource-streaming-websocket/README.md

examples/panel-datalinks/README.md

Co-authored-by: David Harris <[email protected]>

josmperez

Incorporated feedback from reviewers.

examples/datasource-basic/README.md

examples/datasource-http/README.md

examples/datasource-logs/README.md

josmperez · 2024-09-12T19:52:57Z

I found a PR that dropped off my radar screen. I've incorporated feedback from reviwers.

CLAassistant · 2024-11-16T17:04:19Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

academo · 2024-11-25T08:53:46Z

examples/datasource-http-backend/README.md


 This example queries data from an HTTP API. The HTTP API returns data in JSON format, which is then converted to data frames.

-This differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than going through Grafana's data source HTTP proxy.
+This plugin differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than going through Grafana's data source HTTP proxy.


Suggested change

This plugin differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than going through Grafana's data source HTTP proxy.

This plugin differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than the front end code fetching through Grafana's data source HTTP proxy.

academo · 2024-11-25T08:54:39Z

examples/datasource-http/README.md


-This example queries data from an HTTP API.
+This repository contains a data source plugin that uses HTTP through Grafana's data source HTTP proxy.


Suggested change

This repository contains a data source plugin that uses HTTP through Grafana's data source HTTP proxy.

This repository contains a data source plugin that fetches data in the front end through Grafana's data source HTTP proxy.

academo · 2024-11-25T08:58:27Z

examples/datasource-http/README.md

+This repository contains a data source plugin that uses HTTP through Grafana's data source HTTP proxy.
+## Overview
+
+The Grafana HTTP Data Source Plugin shows the integration of a backend HTTP service as a custom data source within Grafana. This plugin serves as a reference implementation for developers seeking to incorporate HTTP-based data sources into their Grafana dashboards.


better remove the mention of "backend http service" and simply it call it "API" or "HTTP API" to not confuse people that might think there's backend code in this example.

Suggested change

The Grafana HTTP Data Source Plugin shows the integration of a backend HTTP service as a custom data source within Grafana. This plugin serves as a reference implementation for developers seeking to incorporate HTTP-based data sources into their Grafana dashboards.

The Grafana HTTP Data Source Plugin shows the integration of a HTTP API as a custom data source within Grafana. This plugin serves as a reference implementation for developers seeking to incorporate frontend HTTP-based data sources into their Grafana dashboards.

academo · 2024-11-25T08:58:54Z

examples/datasource-http/README.md

+
+Grafana supports a wide range of data sources, including Prometheus, MySQL, and Datadog. There’s a good chance you can already visualize metrics from the systems you have set up. In some cases, though, you already have an in-house metrics solution that you’d like to add to your Grafana dashboards. Grafana data source plugins enable you to integrate such solutions with Grafana.
+
+This plugin differs from the `datasource-http-backend` example because the data fetching happens through Grafana's data source HTTP proxy rather than going through the plugin backend.


Suggested change

This plugin differs from the `datasource-http-backend` example because the data fetching happens through Grafana's data source HTTP proxy rather than going through the plugin backend.

This plugin differs from the `datasource-http-backend` example because the data fetching happens in the frontend through Grafana's data source HTTP proxy rather than going through the plugin backend.

academo · 2024-11-25T09:00:16Z

examples/datasource-http/README.md

+   npm run dev
+   ```
+
+3. Build plugin in production mode:


We don't need to call for users to run both npm run dev and npm run build. We can ask them simply to run npm run build and that will be it.

These instructions are also missing calling npm run server which starts a docker container with grafana running the server.

academo · 2024-11-25T09:00:49Z

examples/datasource-http-backend/README.md

 The mockserver required for testing has been included in the Docker Compose file 

 Add a new data source in Grafana using the following URL:
 ```
 http://host.docker.internal:10000/metrics
 ```
+


We are missing the instructions to run the docker container so one can see the plugin running npm run server do we want to add that?

academo · 2024-11-25T09:01:35Z

examples/datasource-logs/README.md

+```bash
+$ npm install
+$ npm run build


We are missing the instructions to run the docker container so one can see the plugin running npm run server do we want to add that?

academo · 2024-11-25T09:02:56Z

examples/datasource-streaming-backend-websocket/README.md


-## Build
+The plugin connects to the backend through a streaming connection and the backend establishes a connection to an external WebSocket server.


This whole sentence is strange

Suggested change

The plugin connects to the backend through a streaming connection and the backend establishes a connection to an external WebSocket server.

The plugin frontend connects to the backend through with a websocket and the backend establishes a connection to an external server.

academo · 2024-11-25T09:04:43Z

examples/datasource-streaming-backend-websocket/README.md

@@ -15,7 +20,7 @@ npm install
 npm run build
  ```

-and run the Grafana and the example websocket server with Docker compose:
+2. Run the Grafana and the example WebSocket server with Docker compose:

 ```sh
 cd streaming-backend-websocket-plugin


wrong path

Suggested change

cd streaming-backend-websocket-plugin

cd websocket-server

academo · 2024-11-25T09:06:31Z

examples/datasource-streaming-backend-websocket/README.md

@@ -15,7 +20,7 @@ npm install
 npm run build
  ```

-and run the Grafana and the example websocket server with Docker compose:
+2. Run the Grafana and the example WebSocket server with Docker compose:


This doesn't run grafana. only the websocket server

Suggested change

2. Run the Grafana and the example WebSocket server with Docker compose:

2. Run the example WebSocket server with Docker compose:

academo · 2024-11-25T09:07:02Z

examples/datasource-streaming-backend-websocket/README.md

@@ -15,7 +20,7 @@ npm install
 npm run build


Suggested change

npm run build

npm run build

npm run server

academo · 2024-11-25T09:11:11Z

examples/datasource-streaming-websocket/README.md

-## Build
+## Overview
+
+The Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.


Suggested change

The Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.

The Frontend Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.

academo · 2024-11-25T09:11:30Z

examples/datasource-streaming-websocket/README.md

+
+The Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.
+
+This server returns random numeric values at random intervals.


Which server?

academo

Thanks @josmperez for all the work in these READMEs but there's some work to be done:

We need to make sure all READMEs we are modifying are following the same format and contain the same amount of instructions. For example many examples call to run npm run server and some not. Some call to run the e2e tests as part of the instructions to "get started" but there's no reason at all to run the e2e tests if you want to run the example.
We must mention frontend and backend likewise to make sure people understand examples that are frontend-oriented and backend-oriented. specially in data sources.
There's this sentence we throw aroung sometimes Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. There’s a... that doesn't really fit in an example readme (IMO). but we don't consistently use it. Let's either put it everywhere or remove it.
In the places we mention Grafana's data source HTTP proxy we must mention that the request happens in the frontend and THEN goes through the data source http proxy. So it is clear this is not a custom backend component.

There are a few places where the text is out of context or just not related at all with th example README. I wrote individual comments about those I found but there might be more.

josmperez · 2024-12-04T18:42:41Z

Thanks @josmperez for all the work in these READMEs but there's some work to be done:

We need to make sure all READMEs we are modifying are following the same format and contain the same amount of instructions. For example many examples call to run npm run server and some not. Some call to run the e2e tests as part of the instructions to "get started" but there's no reason at all to run the e2e tests if you want to run the example.

We must mention frontend and backend likewise to make sure people understand examples that are frontend-oriented and backend-oriented. specially in data sources.

There's this sentence we throw aroung sometimes Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. There’s a... that doesn't really fit in an example readme (IMO). but we don't consistently use it. Let's either put it everywhere or remove it.

In the places we mention Grafana's data source HTTP proxy we must mention that the request happens in the frontend and THEN goes through the data source http proxy. So it is clear this is not a custom backend component.

There are a few places where the text is out of context or just not related at all with th example README. I wrote individual comments about those I found but there might be more.

I'm happy to take another look at this PR and make the requested changes; however, recently at the offsite we discussed long-term plans that would involve removing many of these examples. For this reason, I'd like to pause work on this until I've had a chance to re-prioritize.

Enhance datasource READMEs

4cabc61

josmperez added the documentation Improvements or additions to documentation label Mar 17, 2024

josmperez requested a review from sympatheticmoose March 17, 2024 23:55

josmperez self-assigned this Mar 17, 2024

josmperez requested review from a team as code owners March 17, 2024 23:55

josmperez requested review from Ukochka, wbrowne, oshirohugo and xnyo and removed request for a team March 17, 2024 23:55

sympatheticmoose reviewed Apr 17, 2024

View reviewed changes

josmperez mentioned this pull request Jul 30, 2024

Docs: Streamline plugin examples #348

Open

josmperez and others added 10 commits September 12, 2024 12:07

Update examples/datasource-http-backend/README.md

7461145

Co-authored-by: David Harris <[email protected]>

Update examples/datasource-http/README.md

76f2c6a

Co-authored-by: David Harris <[email protected]>

Update examples/datasource-logs/README.md

01ee913

Co-authored-by: David Harris <[email protected]>

Update examples/datasource-streaming-backend-websocket/README.md

cd0e420

Co-authored-by: David Harris <[email protected]>

Update examples/datasource-streaming-backend-websocket/README.md

fc5cd0c

Co-authored-by: David Harris <[email protected]>

Update examples/datasource-streaming-backend-websocket/README.md

94a061f

Co-authored-by: David Harris <[email protected]>

Change first sentence per reviewer feedback

9cda9e3

Reviewer feedback

40e670b

Add link

7127094

Add link to UI components across all DS examples

17d6508

josmperez commented Sep 12, 2024

View reviewed changes

examples/datasource-basic/README.md Show resolved Hide resolved

examples/datasource-http/README.md Outdated Show resolved Hide resolved

examples/datasource-http/README.md Outdated Show resolved Hide resolved

examples/datasource-logs/README.md Outdated Show resolved Hide resolved

Merge branch 'main' into josmperez/datasource-docs

639eae9

josmperez requested a review from sympatheticmoose October 3, 2024 17:38

tolzhabayev approved these changes Nov 11, 2024

View reviewed changes

Merge branch 'main' into josmperez/datasource-docs

5d0312c

academo reviewed Nov 25, 2024

View reviewed changes

academo requested changes Nov 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Enhance datasource READMEs #254

Docs: Enhance datasource READMEs #254

josmperez commented Mar 17, 2024

sympatheticmoose left a comment

josmperez left a comment

josmperez commented Sep 12, 2024

CLAassistant commented Nov 16, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024

academo Nov 25, 2024 •

edited

Loading

academo left a comment

josmperez commented Dec 4, 2024

	This plugin differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than going through Grafana's data source HTTP proxy.
	This plugin differs from the `datasource-http` example because the data fetching happens in the plugin backend rather than the front end code fetching through Grafana's data source HTTP proxy.


		This example queries data from an HTTP API.
		This repository contains a data source plugin that uses HTTP through Grafana's data source HTTP proxy.

	The Grafana HTTP Data Source Plugin shows the integration of a backend HTTP service as a custom data source within Grafana. This plugin serves as a reference implementation for developers seeking to incorporate HTTP-based data sources into their Grafana dashboards.
	The Grafana HTTP Data Source Plugin shows the integration of a HTTP API as a custom data source within Grafana. This plugin serves as a reference implementation for developers seeking to incorporate frontend HTTP-based data sources into their Grafana dashboards.


		Grafana supports a wide range of data sources, including Prometheus, MySQL, and Datadog. There’s a good chance you can already visualize metrics from the systems you have set up. In some cases, though, you already have an in-house metrics solution that you’d like to add to your Grafana dashboards. Grafana data source plugins enable you to integrate such solutions with Grafana.

		This plugin differs from the `datasource-http-backend` example because the data fetching happens through Grafana's data source HTTP proxy rather than going through the plugin backend.


		## Build
		The plugin connects to the backend through a streaming connection and the backend establishes a connection to an external WebSocket server.

	The plugin connects to the backend through a streaming connection and the backend establishes a connection to an external WebSocket server.
	The plugin frontend connects to the backend through with a websocket and the backend establishes a connection to an external server.

	2. Run the Grafana and the example WebSocket server with Docker compose:
	2. Run the example WebSocket server with Docker compose:

	The Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.
	The Frontend Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.


		The Streaming WebSocket Data Source Plugin illustrates the integration of WebSocket-based data sources into Grafana dashboards. This plugin serves as a reference implementation for developers aiming to incorporate real-time streaming data into their Grafana visualizations.

		This server returns random numeric values at random intervals.

Docs: Enhance datasource READMEs #254

Are you sure you want to change the base?

Docs: Enhance datasource READMEs #254

Conversation

josmperez commented Mar 17, 2024

sympatheticmoose left a comment

Choose a reason for hiding this comment

josmperez left a comment

Choose a reason for hiding this comment

josmperez commented Sep 12, 2024

CLAassistant commented Nov 16, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

academo Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

academo Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

academo Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

academo Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

academo left a comment

Choose a reason for hiding this comment

josmperez commented Dec 4, 2024

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024 •

edited

Loading

academo Nov 25, 2024 •

edited

Loading