Configuration & Settings
Relevant source files
The following files were used as context for generating this wiki page:
Configuration and settings in Grafana define the operational behavior of the application, ranging from server-side backend parameters to frontend feature flags. The system is designed to allow developers to customize their environment for development while ensuring production stability through strictly defined defaults and provisioning capabilities.
The project is currently undergoing a architectural shift to move settings from package-level variables to a centralized setting.Cfg struct. This transition aims to eliminate global state and facilitate better dependency injection using tools like Wire. Sources: contribute/backend/recommended-practices.md:65-70
Configuration Files and Hierarchy
Grafana utilizes a hierarchical configuration system based on .ini files. The system loads a set of default values which can then be overridden by user-defined custom configurations.
| File | Purpose | Location |
|---|---|---|
defaults.ini | Contains the base configuration for all Grafana instances. | conf/ |
sample.ini | A template provided for users to create their own configuration. | conf/ |
custom.ini | The primary file used by developers and admins to override defaults. | conf/ |
When a pull request includes configuration changes, developers are required to update all three relevant files: conf/defaults.ini, conf/sample.ini, and the external documentation. Sources: contribute/create-pull-request.md:143-148, contribute/developer-guide.md:214-220
Development Mode
For local development, the app_mode setting is typically set to development within custom.ini. This enables specific debugging features and relaxes certain production constraints. Sources: contribute/developer-guide.md:222-225
Backend Configuration Architecture
The backend architecture is moving away from global package variables toward a structured configuration object.
The Cfg Struct and Dependency Injection
The setting.Cfg struct is the central repository for backend settings. Modern services and components are instructed to inject setting.Cfg rather than accessing the setting package directly. This approach reduces global state, making the code easier to test and debug. Sources: contribute/backend/recommended-practices.md:65-73
The diagram shows the flow from static INI files into the centralized Cfg struct, which is then injected into various backend services.
Provisioning
Grafana supports "Provisioning," which allows the configuration of resources like data sources, alert notifiers, and dashboards via configuration files instead of the UI or API. This ensures that Grafana state can be version-controlled and reproduced easily. Sources: contribute/backend/recommended-practices.md:110-120
Frontend Configuration and Feature Toggles
The frontend accesses configuration and feature-specific settings primarily through the @grafana/runtime package.
Feature Toggles
Larger changes or experimental features are often wrapped in feature flags. This allows code to be merged into the main branch frequently without exposing incomplete functionality to all users. Feature flags are defined in pkg/services/featuremgmt/toggles_gen.csv and accessed via the config object in the frontend. Sources: WORKFLOW.md:52-54, public/app/features/alerting/unified/AGENTS.md:267-273
The Config Object
The frontend config object provides access to system-wide settings, such as whether Unified Alerting is enabled (unifiedAlertingEnabled). Sources: public/app/features/alerting/unified/AGENTS.md:275-278
Sequence of a frontend component checking a feature toggle during render.
Instrumentation and Logging Configuration
Configuration also extends to how Grafana monitors itself through logs, metrics, and traces.
- Log Filters: Developers can configure specific log levels for individual loggers (e.g.,
infra.log) via the[log.filters]section in the INI files. This allows for granular debugging of specific subsystems likeoauthorprovisioning. Sources: contribute/backend/instrumentation.md:83-100 - Tracing: Distributed tracing (OpenTelemetry) must be explicitly enabled and configured with an address (e.g., a Jaeger endpoint) in the
config.inifor spans to be collected. Sources: contribute/backend/instrumentation.md:313-317
Summary
Configuration in Grafana is a multi-layered system designed for flexibility and scalability. By centralizing settings into the setting.Cfg struct and leveraging feature toggles, the project maintains a balance between rapid development and robust production deployments. Proper configuration management requires synchronizing changes across multiple .ini files and ensuring that new services utilize dependency injection rather than global state. Sources: contribute/backend/recommended-practices.md:65-70, contribute/create-pull-request.md:143-148