repository·main·Indexed 41 days ago
https://github.com/grafana/scenesA framework and SDK for building highly interactive, dynamic dashboards and applications within the Grafana ecosystem. Version 0.15.0 provides built-in support for template variables, versatile layouts, panel rendering, and URL synchronization. The project includes the core @grafana/scenes SDK and @grafana/scenes-react for React-based development.
@grafana/scenes is a framework designed to enable the implementation of versatile Grafana app plugins. It allows developers to build applications that mimic the Grafana dashboarding experience, providing built-in support for:
scenes-app package serves as a basic template for building Grafana applications using the @grafana/scenes library. It provides a starting point for developers looking to create custom Grafana-based applications or plugins that leverage the Scenes framework for UI composition and state management.Grafana Scenes is a framework designed to help you build highly interactive Grafana applications. The project is split into several key packages:
@grafana/scenes-react is a library designed to simplify the development of Grafana scene applications. It allows developers to use familiar React patterns—such as context, hooks, and components—to build highly interactive Grafana apps.
For full library documentation, visit https://grafana.com/developers/scenes.
@grafana/scenes is a library designed to build highly interactive, dashboard-like experiences within Grafana app plugins. It provides built-in support for common dashboarding requirements, including:
When implementing logic that depends on variables (like a SceneQueryRunner), you should avoid executing actions while variables are still loading.
Use sceneGraph.hasVariableDependencyInLoadingState(model) to check if any variable in the dependency chain is currently in a loading state. This function performs a deep check through the entire dependency tree.
If your object subscribes to both time and variables, variables might change as a reaction to time changes. To avoid double reactions and ensure stability, use the following pattern:
VariableDependencyConfig.onVariableUpdateCompleted callback. This callback is triggered whenever a dependency changes value or when the variable update process (including loading phases) is completed.hasVariableDependencyInLoadingState before issuing queries or heavy logic to skip execution while the dependency chain is resolving.This ensures that even if a variable doesn't change its value but merely completes its loading phase, your object is notified to proceed.
You can share query results between multiple panels by placing a single SceneQueryRunner at a high level in the scene hierarchy.
To display different subsets of that data in different panels, use a SceneDataTransformer at the individual panel level. You can filter the resulting DataFrame array by checking the refId property on each DataFrame to determine which query produced it.
To build a highly interactive Grafana app plugin using Scenes, you use two primary abstractions: SceneApp and SceneAppPage.
SceneApp is the root object that manages the entire application lifecycle, including routing and URL synchronization. It acts as the container for all your application's pages.SceneAppPage represents an individual page within your app. It handles page-specific metadata (like titles and icons), routing (via url and routePath), navigation (via tabs and drilldowns), and the actual content to be rendered (via the getScene function).Workflow:
getScene function that returns an EmbeddedScene.SceneAppPage configuration.SceneAppPage in the pages array of a SceneApp instance.SceneApp using the useSceneApp hook within your React plugin component.const getScene = () => new EmbeddedScene({ /* ... content ... */ });
const myAppPage = new SceneAppPage({
title: 'My Page',
url: '/my-page',
getScene,
});
const sceneApp = new SceneApp({
pages: [myAppPage],
});Behaviors allow you to implement custom scene logic as side effects. They are useful for tasks like conditionally hiding elements or attaching shared functionalities across different scene objects.
To attach behaviors to a scene object, use the $behaviors state property. For example, you can attach them to a SceneQueryRunner or any other SceneObject.
const queryRunner = new SceneQueryRunner({
$behaviors: [
/* list of behaviors */
],
datasource: {
type: 'prometheus',
uid: 'gdev-prometheus',
},
queries: [
{
refId: 'A',
range: true,
format: 'time_series',
expr: 'rate(prometheus_http_requests_total[5m])',
},
],
});Scenes support several types of variables to parameterize queries, panel titles, and custom scene objects:
QueryVariable: Generates a list of values from a query (e.g., metric names, server names).DataSourceVariable: Defines a list of data sources of a specific type.CustomVariable: Manually defined options using a comma-separated list.ConstantVariable: A variable that holds a constant value.TextBoxVariable: A free text input field with an optional default value.A scene object's parent is automatically set when it is added to the state of another object. Do not reuse the same instance of a scene object in multiple locations within a scene or across different scenes, as this will cause parentage conflicts.
If you need to use the same object definition in multiple places, use one of these two patterns:
SceneObjectRef: Wrap the instance in a SceneObjectRef. This allows you to store a reference to the instance in another object's state without changing the original object's parent.$data property on a common ancestor, use DataProviderSharer. This utility acts as a data provider that can forward or share data from another existing data provider to specific scene objects.