Data Sources & Query Engine

Relevant source files

The following files were used as context for generating this wiki page:

• contribute/architecture/k8s-inspired-backend-arch.md
• AGENTS.md
• contribute/backend/recommended-practices.md
• contribute/backend/instrumentation.md
• public/app/features/alerting/unified/AGENTS.md
• public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts
• e2e-playwright/various-suite/frontend-sandbox-datasource.spec.ts

Introduction

The Data Sources & Query Engine represents the core functionality of Grafana, enabling the platform to query, visualize, and alert on data from various time series databases and SQL engines. The system is designed around a modular plugin architecture where specific data source implementations (such as Prometheus, Loki, or Amazon Redshift) are loaded into the Grafana backend or frontend to handle specialized query logic.

Architecturally, Grafana is moving toward a resource-oriented model for managing data sources, utilizing a Kubernetes-inspired approach. This includes a transition from Legacy APIs (/api/datasources) to structured Resource APIs (/apis/...) with strict schema validation using CUE and unified storage persistence. This evolution ensures consistent behavior, versioning, and machine-readable schemas for all data-related components.

Sources: contribute/architecture/k8s-inspired-backend-arch.md:1-15, AGENTS.md:55-70

Architecture and Data Flow

The query engine operates as an intermediary between user-defined dashboard panels (or alert rules) and the underlying data providers. The system supports both synchronous and asynchronous query handling flows.

Query Request Pipeline

When a query is initiated, it flows through a multi-layered backend structure:

1. API Layer: Handles incoming HTTP requests. Legacy routes typically reside in pkg/api/, while new Resource API routes are handled via pkg/services/apiserver/.
2. Service Layer: Business logic (e.g., verifying permissions, applying template variables) resides in pkg/services/.
3. TSDB Layer: Located in pkg/tsdb/, this layer contains the specific query backends for time series databases.
4. Plugin System: For external or community data sources, Grafana communicates with plugin processes via gRPC/protobuf.

Sources: AGENTS.md:65-80, contribute/architecture/k8s-inspired-backend-arch.md:144-180

The following diagram illustrates the request flow between the legacy and resource-oriented architectures:

The diagram shows how both Legacy and Resource APIs eventually converge on the configured SQL database, though they utilize different internal logic paths.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:144-180

Asynchronous Query Support

Advanced data sources, such as Amazon Redshift, support an asynchronous query flow. This is essential for long-running queries that might otherwise timeout. The flow involves:

• Starting the query.
• Checking query status periodically.
• Fetching results once the status is complete.
• Support for canceling statements.

Sources: public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts:460-475

Data Source Configuration and Management

Data sources are managed as resources with specific schemas. Modern implementations use CUE for defining these schemas, which automatically generates both Go types for the backend and TypeScript types for the frontend.

Configuration Fields

Data sources generally contain a mix of standard metadata and provider-specific settings:

Field	Type	Description
name	string	Unique identifier used in panels and queries.
type	string	The plugin ID (e.g., prometheus, redshift).
jsonData	object	Open-ended configuration for non-sensitive data (e.g., defaultRegion).
secureJsonData	object	Encrypted storage for sensitive data (e.g., secretKey, accessKey).
authType	string	Method of authentication (e.g., default, keys, credentials).

Sources: public/app/features/plugins/admin/mocks/catalogPlugin.mock.ts:250-320, contribute/architecture/k8s-inspired-backend-arch.md:110-125

Backend Integration via Wire

The backend uses Wire for Dependency Injection (DI). When adding or modifying data source services, developers must define interfaces within the pkg/services/ package and regenerate the DI code using make gen-go. This architecture ensures that global state is minimized and services can easily access configurations (e.g., setting.Cfg).

Sources: AGENTS.md:85-95, contribute/backend/recommended-practices.md:45-65

Frontend Implementation

On the frontend, data sources are integrated through the @grafana/data and @grafana/runtime packages.

Query Editors and Sandboxing

Query editors are the UI components used by users to build queries. Grafana is implementing "sandbox" wrappers around these editors to improve security and isolation for third-party plugins.

The sequence diagram shows how the sandbox wrapper intercepts state updates and manages the communication with the backend.
Sources: e2e-playwright/various-suite/frontend-sandbox-datasource.spec.ts:15-50

Instrumentation and Observability

Data source operations are heavily instrumented to provide visibility into query performance:

• Logs: Uses pkg/infra/log with area-specific names like tsdb.postgres or datasources.
• Metrics: Prometheus counters and histograms (e.g., grafana_http_request_duration_seconds) track query latency and volume.
• Traces: OpenTelemetry spans are created for IO-bound work. For instance, a trace might cover tsdb.HandleRequest to identify bottlenecks in external data providers.

Sources: contribute/backend/instrumentation.md:15-30, 85-100, 150-170

Conclusion

The Data Sources & Query Engine architecture is transitioning toward a highly standardized, resource-oriented model. By combining a plugin-based TSDB layer with a Kubernetes-inspired Resource API, Grafana provides a robust framework for handling diverse data types while maintaining strict schema validation and consistency across the platform. This structure supports critical features like asynchronous query handling and sandboxed frontend editors, ensuring the system remains scalable and secure for complex observability workflows.