grafana_plugin_sdk/
lib.rs

1/*! A lean, protocol-first SDK for building Grafana backend plugins in Rust.
2
3Backend plugins communicate with Grafana via gRPC (the `pluginv2` protocol),
4run as a [go-plugin] subprocess. This crate implements that protocol.
5
6The default build is intentionally small and dependency-light — it implements
7only what a resource/health plugin needs: custom HTTP-style requests
8(`CallResource`) and health checks (`CheckHealth`). Dataframe queries and
9streaming are opt-in behind cargo features (see below).
10
11The crate is organised into:
12
13- [`backend`] contains the traits a plugin implements (e.g.
14  [`ResourceService`][backend::ResourceService] and
15  [`DiagnosticsService`][backend::DiagnosticsService]) and the
16  [`Plugin`][backend::Plugin] type that serves them.
17- [`live`] contains channel/path types used by [Grafana Live].
18- `data` (feature `data`) contains the fundamental dataframe structures
19  (`Frame`, `Field`) and their metadata.
20
21The [`prelude`] re-exports the [`GrafanaPlugin`] derive macro and, with the
22`data` feature, the traits for building frames and fields.
23
24The low-level generated structs are exposed in the [`pluginv2`] module as an
25escape hatch, if required.
26
27See the docs on [backend plugins on grafana.com] for an introduction to backend
28Grafana plugins.
29
30# Logging
31
32Emit logs with the [`tracing`] macros; install [`backend::layer`], call
33[`backend::init_hclog_subscriber`] before bootstrap work, or enable
34[`Plugin::init_subscriber`][backend::Plugin::init_subscriber] so they are written
35in the [hclog] format Grafana understands. This is the idiomatic replacement for
36the Go SDK's `backend/log` logger.
37
38# Build information
39
40[`build_info!`] captures the plugin's [`BuildInfo`][buildinfo::BuildInfo] (id and
41version) from its Cargo metadata.
42
43# Feature flags
44
45- `automtls` — go-plugin automatic mTLS, required to connect to a Grafana instance
46  that serves backend plugins with AutoMTLS (the default). Opt-in.
47- `data` — dataframe support: the `data` module (`Frame`/`Field`),
48  `DataService`/`QueryData`, and Arrow IPC serialization. Pulls in Apache Arrow.
49- `stream` — Grafana Live `StreamService` (implies `data`).
50- `httpadapter` — a [`ResourceService`][backend::ResourceService] that serves
51  `CallResource` requests by running them through an `axum::Router`.
52- `reqwest` — adds the `httpclient` module and an
53  [`IntoHttpResponse`][backend::IntoHttpResponse] implementation for `reqwest::Response`.
54- `prometheus` — encodes a `prometheus::Registry` directly into
55  [`CollectMetricsResponse`][backend::CollectMetricsResponse].
56- `opentelemetry` — extracts distributed trace context from Grafana's incoming
57  gRPC metadata and attaches it to each request's `tracing` span.
58- `gen-proto` — regenerate the protobuf bindings using a vendored `protoc` binary.
59
60[hclog]: https://github.com/hashicorp/go-hclog
61
62[Backend plugins on grafana.com]: https://grafana.com/docs/grafana/latest/developers/plugins/backend/
63[Grafana Live]: https://grafana.com/docs/grafana/latest/live/
64[go-plugin]: https://github.com/hashicorp/go-plugin
65*/
66#![cfg_attr(docsrs, feature(doc_notable_trait))]
67#![deny(missing_docs)]
68
69/// Re-export of the arrow crate depended on by this crate.
70///
71/// We recommend that you use this re-export rather than depending on arrow
72/// directly to ensure compatibility; otherwise, rustc/cargo may emit mysterious
73/// error messages.
74///
75/// Only available when the `data` feature is enabled.
76#[cfg(feature = "data")]
77pub use arrow;
78
79#[doc(hidden)]
80pub use serde_json;
81
82#[cfg(feature = "reqwest")]
83extern crate reqwest_lib as reqwest;
84
85#[allow(
86    missing_docs,
87    clippy::all,
88    clippy::nursery,
89    clippy::pedantic,
90    rustdoc::all
91)]
92pub mod pluginv2 {
93    //! The low-level structs generated from protocol definitions.
94    include!("pluginv2/pluginv2.rs");
95}
96
97pub mod backend;
98pub mod buildinfo;
99#[cfg(feature = "data")]
100pub mod data;
101#[cfg(feature = "httpadapter")]
102pub mod httpadapter;
103#[cfg(feature = "reqwest")]
104pub mod httpclient;
105pub mod live;
106
107/// Contains useful helper traits, in particular the [`GrafanaPlugin`] derive macro
108/// and (with the `data` feature) the traits for constructing `Field`s and `Frame`s.
109pub mod prelude {
110    pub use grafana_plugin_sdk_macros::GrafanaPlugin;
111
112    #[cfg(feature = "data")]
113    pub use crate::data::{ArrayIntoField, FromFields, IntoField, IntoFrame, IntoOptField};
114}
115
116#[doc(inline)]
117pub use grafana_plugin_sdk_macros::*;
118
119/// WARNING: Do not use this method outside of the SDK.
120#[doc(hidden)]
121pub fn async_main<R>(fut: impl std::future::Future<Output = R> + Send) -> R {
122    tokio::runtime::Builder::new_multi_thread()
123        .thread_name("grafana-plugin-worker-thread")
124        .enable_all()
125        .build()
126        .expect("create tokio runtime")
127        .block_on(fut)
128}
grafana_plugin_sdk/lib.rs

grafana_plugin_sdk/
lib.rs
