Skip to content

Commit de162f7

Browse files
K-PhoenK-Phoen
committed
Improve README and documentation index page
1 parent 8a85a30 commit de162f7

2 files changed

Lines changed: 132 additions & 48 deletions

File tree

‎.mkdocs/docs/index.md‎

Lines changed: 43 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,30 @@ hide:
66

77
# Grafana Foundation SDK
88

9-
A set of libraries for manipulating and generating Grafana resources
10-
– dashboards, alerts, … – as-code.
9+
The Grafana Foundation SDK is a set of **_types_**, and **_builder libraries_**
10+
that let you define Grafana dashboards and other resources using strongly typed
11+
code. By writing your resources as code, you can:
1112

12-
**_Types_**, **_builder libraries_** and **JSON to code converters** are
13-
provided in the following languages:
13+
* **Leverage strong typing**: Catch errors at compile time, ensuring more reliable configurations.
14+
* **Enhance version control**: Track changes seamlessly using standard version control systems like Git.
15+
* **Automate deployments**: Integrate dashboard provisioning into your CI/CD pipelines for consistent and repeatable setups.
1416

15-
* Go
16-
* Java
17-
* PHP
18-
* Python
19-
* Typescript
17+
The SDK supports multiple programming languages, including **Go**, **TypeScript**, **Python**, **PHP**, and **Java**, so you can choose the one that best fits your development environment.
2018

2119
!!! note
2220

23-
The various SDKs are generated by [`cog`][cog] from
24-
schemas exposed by Grafana.
21+
This SDK is best suited for Grafana >= 12, but will work with Grafana >= 10.
2522

26-
## Examples
23+
## Overview
24+
25+
Here's a quick overview of how the SDK works:
26+
27+
* **Builder pattern**: The SDK implements the builder pattern to let you define dashboards fluently. You start with a `DashboardBuilder`, then add panels, queries, and other components step by step.
28+
* **Strong typing**: Everything in the SDK is strongly typed. This gives you autocompletion in your IDE, catches mistakes early, and helps ensure you're always using valid configuration values.
29+
* **Structured options**: When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable and predictable.
30+
* **Resources**: Multiple resources are supported by the SDK. Dashboards, alerts, …
31+
32+
For example, here is how dashboards can be built:
2733

2834
=== "Go"
2935

@@ -231,6 +237,31 @@ provided in the following languages:
231237
console.log(JSON.stringify(builder.build(), null, 2));
232238
```
233239

240+
!!! tip
241+
242+
More examples can be found in the [`./examples/`](https://github.com/grafana/grafana-foundation-sdk/tree/main/examples)
243+
folder of the Foundation SDK repository.
244+
245+
## Publishing resources
246+
247+
After you've defined your resource as code, call the `build()` function (its
248+
actual name might be slightly different depending on language choice) and
249+
output the result as a JSON.
250+
251+
With the JSON payload, you can:
252+
253+
* Call [Grafana's API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/) to programmatically manage the resource.
254+
* Use [Grafana CLI](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/) publish the resource from CLI.
255+
256+
## Next steps
257+
258+
With the basics of using the Grafana Foundation SDK in mind, here are some possible next steps:
259+
260+
* **Explore more features**: Check out the full API reference to learn more about what the SDK can do.
261+
* **Version control your resources**: Store your resources code in a Git repository to track changes over time.
262+
* **Automate provisioning with CI/CD**: [Integrate the SDK into your CI/CD pipeline](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/dashboard-automation/) to deploy dashboards and other resources automatically.
263+
* **Explore a more [real-world example of using the SDK](https://www.youtube.com/watch?v=ZjWdGVsrCiQ)**
264+
234265
## Maturity
235266

236267
The Grafana Foundation SDK should be considered as "public preview". While it is used by Grafana Labs in production, it still is under active development.
@@ -244,5 +275,3 @@ Additional information can be found in [Release life cycle for Grafana Labs](htt
244275
## License
245276

246277
[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0)
247-
248-
[cog]: <https://github.com/grafana/cog>

‎README.md‎

Lines changed: 89 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,98 @@
11
# Grafana Foundation SDK
22

3-
A set of libraries for manipulating and generating Grafana resources
4-
– dashboards, alerts, … – as-code.
3+
The Grafana Foundation SDK is a set of **_types_**, and **_builder libraries_**
4+
that let you define Grafana dashboards and other resources using strongly typed
5+
code. By writing your resources as code, you can:
56

6-
**_Types_**, **_builder libraries_** and **JSON to code converters** are
7-
provided in the following languages:
7+
* **Leverage strong typing**: Catch errors at compile time, ensuring more reliable configurations.
8+
* **Enhance version control**: Track changes seamlessly using standard version control systems like Git.
9+
* **Automate deployments**: Integrate dashboard provisioning into your CI/CD pipelines for consistent and repeatable setups.
810

9-
* Go
10-
* Java
11-
* PHP
12-
* Python
13-
* Typescript
11+
The SDK supports multiple programming languages, including **Go**, **TypeScript**, **Python**, **PHP**, and **Java**, so you can choose the one that best fits your development environment.
1412

1513
> [!NOTE]
16-
> The content of this repository is generated by [`cog`][cog] from
17-
> schemas exposed by Grafana.
18-
19-
## Navigating the SDK
20-
21-
This SDK is best suited for Grafana >= 12.0
22-
23-
For older versions, the following table can be used to select a version of the
24-
SDK suitable for your Grafana instance.
25-
26-
| Grafana Version | `cog` Version | Branch |
27-
| ---------------- | ------------- | ------ |
28-
| `v11.6.x` | `v0.0.x` | [v11.6.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.6.x%2Bcog-v0.0.x) |
29-
| `v11.5.x` | `v0.0.x` | [v11.5.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.5.x%2Bcog-v0.0.x) |
30-
| `v11.4.x` | `v0.0.x` | [v11.4.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.4.x%2Bcog-v0.0.x) |
31-
| `v11.3.x` | `v0.0.x` | [v11.3.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.3.x%2Bcog-v0.0.x) |
32-
| `v11.2.x` | `v0.0.x` | [v11.2.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.2.x%2Bcog-v0.0.x) |
33-
| `v11.1.x` | `v0.0.x` | [v11.1.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.1.x%2Bcog-v0.0.x) |
34-
| `v11.0.x` | `v0.0.x` | [v11.0.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v11.0.x%2Bcog-v0.0.x) |
35-
| `v10.4.x` | `v0.0.x` | [v10.4.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v10.4.x%2Bcog-v0.0.x) |
36-
| `v10.3.x` | `v0.0.x` | [v10.3.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v10.3.x%2Bcog-v0.0.x) |
37-
| `v10.2.x` | `v0.0.x` | [v10.2.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v10.2.x%2Bcog-v0.0.x) |
38-
| `v10.1.x` | `v0.0.x` | [v10.1.x+cog-v0.0.x](https://github.com/grafana/grafana-foundation-sdk/tree/v10.1.x%2Bcog-v0.0.x) |
14+
> This SDK is best suited for Grafana >= 12, but will work with Grafana >= 10.
15+
16+
## Overview
17+
18+
Here's a quick overview of how the SDK works:
19+
20+
* **Builder pattern**: The SDK implements the builder pattern to let you define dashboards fluently. You start with a `DashboardBuilder`, then add panels, queries, and other components step by step.
21+
* **Strong typing**: Everything in the SDK is strongly typed. This gives you autocompletion in your IDE, catches mistakes early, and helps ensure you're always using valid configuration values.
22+
* **Structured options**: When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable and predictable.
23+
* **Resources**: Multiple resources are supported by the SDK. Dashboards, alerts, …
24+
25+
For example, here is how a dashboard can be built in Go:
26+
27+
```go
28+
package main
29+
30+
import (
31+
"encoding/json"
32+
"fmt"
33+
34+
"github.com/grafana/grafana-foundation-sdk/go/common"
35+
"github.com/grafana/grafana-foundation-sdk/go/dashboard"
36+
"github.com/grafana/grafana-foundation-sdk/go/prometheus"
37+
"github.com/grafana/grafana-foundation-sdk/go/timeseries"
38+
"github.com/grafana/grafana-foundation-sdk/go/units"
39+
)
40+
41+
func main() {
42+
builder := dashboard.NewDashboardBuilder("Sample dashboard").
43+
Uid("generated-from-go").
44+
Tags([]string{"generated", "from", "go"}).
45+
Refresh("1m").
46+
Time("now-30m", "now").
47+
Timezone(common.TimeZoneBrowser).
48+
WithRow(dashboard.NewRowBuilder("Overview")).
49+
WithPanel(
50+
timeseries.NewPanelBuilder().
51+
Title("Network Received").
52+
Unit(units.BitsPerSecondSI).
53+
Min(0).
54+
WithTarget(
55+
prometheus.NewDataqueryBuilder().
56+
Expr(`rate(node_network_receive_bytes_total{job="integrations/raspberrypi-node", device!="lo"}[$__rate_interval]) * 8`).
57+
LegendFormat("{{ device }}"),
58+
),
59+
)
60+
61+
sampleDashboard, err := builder.Build()
62+
if err != nil {
63+
panic(err)
64+
}
65+
dashboardJson, err := json.MarshalIndent(sampleDashboard, "", " ")
66+
if err != nil {
67+
panic(err)
68+
}
69+
70+
fmt.Println(string(dashboardJson))
71+
}
72+
```
73+
74+
> [!NOTE]
75+
> More examples can be found in the [`./examples/`](https://github.com/grafana/grafana-foundation-sdk/tree/main/examples) folder.
76+
77+
## Publishing resources
78+
79+
After you've defined your resource as code, call the `build()` function (its
80+
actual name might be slightly different depending on language choice) and
81+
output the result as a JSON.
82+
83+
With the JSON payload, you can:
84+
85+
* Call [Grafana's API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/) to programmatically manage the resource.
86+
* Use [Grafana CLI](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/) publish the resource from CLI.
87+
88+
## Next steps
89+
90+
With the basics of using the Grafana Foundation SDK in mind, here are some possible next steps:
91+
92+
* **Explore more features**: Check out the full [API reference](https://grafana.github.io/grafana-foundation-sdk/) to learn more about what the SDK can do.
93+
* **Version control your resources**: Store your resources code in Git to track changes over time.
94+
* **Automate provisioning with CI/CD**: [Integrate the SDK into your CI/CD pipeline](https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/dashboard-automation/) to deploy dashboards and other resources automatically.
95+
* **Explore a more [real-world example of using the SDK](https://www.youtube.com/watch?v=ZjWdGVsrCiQ)**
3996

4097
## Maturity
4198

@@ -47,5 +104,3 @@ The code in this repository should be considered as "public preview". While it i
47104
## License
48105

49106
[Apache 2.0 License](./LICENSE)
50-
51-
[cog]: <https://github.com/grafana/cog>

0 commit comments

Comments
 (0)