mirror of
https://github.com/grafana/grafana.git
synced 2025-08-02 17:32:18 +08:00
Docs: Plugin doc review - backend topics - chunk 5 (#68662)
* Initial commit Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Minor fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Prettier fixes Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Incorporating review feedback Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Minor fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Giuseppe Guerra <giuseppe.guerra@grafana.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/grafana-plugin-sdk-for-go.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/plugin-protocol.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/plugin-protocol.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/plugin-protocol.md Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> * Update docs/sources/developers/plugins/backend/_index.md Co-authored-by: David Harris <david.harris@grafana.com> * Indentation fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Review feedback Signed-off-by: Joe Perez <joseph.perez@grafana.com> * Bug fix Signed-off-by: Joe Perez <joseph.perez@grafana.com> --------- Signed-off-by: Joe Perez <joseph.perez@grafana.com> Co-authored-by: Giuseppe Guerra <giuseppe.guerra@grafana.com> Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Co-authored-by: David Harris <david.harris@grafana.com>
This commit is contained in:
Joseph Perez
@ -11,24 +11,35 @@ title: Plugin protocol
|
||||
|
||||
# Plugin protocol
|
||||
|
||||
There’s a physical wire protocol that Grafana server uses to communicate with backend plugins. This is the contract between Grafana and backend plugins, that must be agreed upon for Grafana and a backend plugin to be able to communicate with each other. The plugin protocol is built on [gRPC](https://grpc.io/) and is defined in [Protocol Buffers (a.k.a., protobuf)](https://developers.google.com/protocol-buffers).
|
||||
The Grafana server uses a physical wire protocol to communicate with backend plugins. This protocol establishes a contract between Grafana and backend plugins to allow them to communicate with each other.
|
||||
|
||||
We advise for backend plugins to not be implemented directly against this protocol. Instead, prefer to use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher level APIs.
|
||||
## Developing with the plugin protocol
|
||||
|
||||
The plugin protocol is available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto). The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) since Grafana itself uses parts of the SDK as a dependency.
|
||||
{{% admonition type="caution" %}} We strongly recommend that backend plugin development not be implemented directly against the protocol. Instead, we prefer that you use the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) that implements this protocol and provides higher-level APIs. {{%
|
||||
/admonition %}}
|
||||
|
||||
If you choose to develop against the plugin protocol directly, you can do so using [Protocol Buffers](https://developers.google.com/protocol-buffers) (that is, protobufs) with [gRPC](https://grpc.io/).
|
||||
|
||||
Grafana's plugin protocol protobufs are available in the [GitHub repository](https://github.com/grafana/grafana-plugin-sdk-go/blob/master/proto/backend.proto).
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
The plugin protocol lives in the [Grafana Plugin SDK for Go]({{< relref "grafana-plugin-sdk-for-go/" >}}) because Grafana itself uses parts of the SDK as a dependency.
|
||||
{{% /admonition %}}
|
||||
|
||||
## Versioning
|
||||
|
||||
Additions of services, messages and fields in the latest version of the plugin protocol are expected to happen, but should not introduce any breaking changes. If breaking changes to the plugin protocol is needed, a new major version of the plugin protocol will be created and released together with a new major Grafana release. Grafana will then support both the old and the new plugin protocol for some time to make sure existing backend plugins continue to work.
|
||||
From time to time, Grafana will offer additions of services, messages, and fields in the latest version of the plugin protocol. We don't expect these updates to introduce any breaking changes. However, if we must introduce breaking changes to the plugin protocol, we'll create a new major version of the plugin protocol.
|
||||
|
||||
Because Grafana maintains the plugin protocol, the plugin protocol attempts to follow Grafana's versioning, However, that doesn't automatically mean that a new major version of the plugin protocol is created when a new major release of Grafana is released.
|
||||
Grafana will release new major versions of the plugin protocol alongside new major Grafana releases. When this happens, we'll support both the old and the new plugin protocol for some time to make sure existing backend plugins continue to work.
|
||||
|
||||
The plugin protocol attempts to follow Grafana's versioning. However, that doesn't mean we will automatically create a new major version of the plugin protocol when a new major release of Grafana is released.
|
||||
|
||||
## Writing plugins without Go
|
||||
|
||||
If you want to write a backend plugin in another language than Go, then it’s possible as long as the language supports [gRPC](https://grpc.io/). However, writing a plugin in Go is recommended and has several advantages that should be carefully taken into account before proceeding:
|
||||
If you want to write a backend plugin in a language other than Go, then it's possible as long as the language supports gRPC. However, we recommend that you develop your plugin in Go for several reasons:
|
||||
|
||||
- There's an official [SDK]({{< relref "grafana-plugin-sdk-for-go/" >}}) available.
|
||||
- Single binary as the compiled output.
|
||||
- Building and compiling for multiple platforms is easy.
|
||||
- A statically compiled binary (in most cases) doesn't require any additional dependencies installed on the target platform enabling it to run “everywhere”.
|
||||
- Small footprint in regards to binary size and resource usage.
|
||||
- We offer an official plugin SDK.
|
||||
- The compiled output is a single binary.
|
||||
- Writing for multiple platforms is easy. Typically, no additional dependencies must be installed on the target platform.
|
||||
- Small footprint for binary size.
|
||||
- Small footprint for resource usage.
|
||||
|
||||
Reference in New Issue
Block a user