Trait grafana_plugin_sdk::backend::DiagnosticsService

pub trait DiagnosticsService {
    type CheckHealthError: Error;
    type CollectMetricsError: Error;

    // Required methods
    fn check_health<'life0, 'async_trait>(
        &'life0 self,
        request: CheckHealthRequest
    ) -> Pin<Box<dyn Future<Output = Result<CheckHealthResponse, Self::CheckHealthError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn collect_metrics<'life0, 'async_trait>(
        &'life0 self,
        request: CollectMetricsRequest
    ) -> Pin<Box<dyn Future<Output = Result<CollectMetricsResponse, Self::CollectMetricsError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
}

Trait for services that provide a health check and/or metric collection endpoint.

The health check is used when checking that a datasource is configured correctly, or (for app plugins) is exposed in Grafana’s HTTP API.

Grafana will also expose a metrics endpoint at /api/plugins/<plugin id>/metrics if this trait is implemented, and will call the collect_metrics function to get metrics for the plugin in text-based Prometheus exposition format. This allows plugins to be instrumented in detail.

Example

use grafana_plugin_sdk::backend;
use prometheus::{Encoder, TextEncoder};

struct MyPlugin {
    metrics: prometheus::Registry,
}

#[backend::async_trait]
impl backend::DiagnosticsService for MyPlugin {
    type CheckHealthError = std::convert::Infallible;

    async fn check_health(
        &self,
        request: backend::CheckHealthRequest,
    ) -> Result<backend::CheckHealthResponse, Self::CheckHealthError> {
        // A real plugin may ensure it could e.g. connect to a database, was configured
        // correctly, etc.
        Ok(backend::CheckHealthResponse::ok("Ok".to_string()))
    }

    type CollectMetricsError = prometheus::Error;

    async fn collect_metrics(
        &self,
        request: backend::CollectMetricsRequest,
    ) -> Result<backend::CollectMetricsResponse, Self::CollectMetricsError> {
        let mut buffer = vec![];
        let encoder = TextEncoder::new();
        encoder.encode(&self.metrics.gather(), &mut buffer)?;
        Ok(backend::CollectMetricsResponse::new(Some(backend::MetricsPayload::prometheus(buffer))))
    }
}

Required Associated Types

type CheckHealthError: Error

The type of error that can occur when performing a health check request.

type CollectMetricsError: Error

The type of error that can occur when collecting metrics.

Required Methods

fn check_health<'life0, 'async_trait>( &'life0 self, request: CheckHealthRequest ) -> Pin<Box<dyn Future<Output = Result<CheckHealthResponse, Self::CheckHealthError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Check the health of a plugin.

For a datasource plugin, this is called automatically when a user clicks ‘Save & Test’ in the UI when editing a datasource.

For an app plugin, a health check endpoint is exposed in the Grafana HTTP API and allows external systems to poll the plugin’s health to make sure it is running as expected.

See https://grafana.com/docs/grafana/latest/developers/plugins/backend/#health-checks.

fn collect_metrics<'life0, 'async_trait>( &'life0 self, request: CollectMetricsRequest ) -> Pin<Box<dyn Future<Output = Result<CollectMetricsResponse, Self::CollectMetricsError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Collect metrics for a plugin.

See https://grafana.com/docs/grafana/latest/developers/plugins/backend/#collect-metrics.

Implementors