Configure Grafana on Grafana Labs

Configure Grafana Enterprise

Fri, 03 Apr 2026 19:43:06 +0000

Configure Grafana Enterprise

This page describes Grafana Enterprise-specific configuration options that you can specify in a .ini configuration file or using environment variables. Refer to Configuration for more information about available configuration options.

[enterprise]

license_path

Local filesystem path to Grafana Enterprise’s license file. Defaults to <paths.data>/license.jwt.

license_text

When set to the text representation (i.e. content of the license file) of the license, Grafana will evaluate and apply the given license to the instance.

auto_refresh_license

When enabled, Grafana will send the license and usage statistics to the license issuer. If the license has been updated on the issuer’s side to be valid for a different number of users or a new duration, your Grafana instance will be updated with the new terms automatically. Defaults to true.

Note
The license only automatically updates once per day. To immediately update the terms for a license, use the Grafana UI to renew your license token.

license_validation_type

When set to aws, Grafana will validate its license status with Amazon Web Services (AWS) instead of with Grafana Labs. Only use this setting if you purchased an Enterprise license from AWS Marketplace. Defaults to empty, which means that by default Grafana Enterprise will validate using a license issued by Grafana Labs. For details about licenses issued by AWS, refer to Activate a Grafana Enterprise license purchased through AWS Marketplace.

[white_labeling]

app_title

Set to your company name to override application title.

login_logo

Set to complete URL to override login logo.

login_background

Set to complete CSS background expression to override login background. Example:

[white_labeling]
login_background = url(http://www.bhmpics.com/wallpapers/starfield-1920x1080.jpg)

menu_logo

Set to complete URL to override menu logo.

fav_icon

Set to complete URL to override fav icon (icon shown in browser tab).

apple_touch_icon

Set to complete URL to override Apple/iOS icon.

hide_edition

Set to true to remove the Grafana edition from appearing in the footer.

footer_links

List the link IDs to use here. Grafana will look for matching link configurations, the link IDs should be space-separated and contain no whitespace.

[usage_insights.export]

By exporting usage logs, you can directly query them and create dashboards of the information that matters to you most, such as dashboard errors, most active organizations, or your top-10 most-used queries.

enabled

Enable the usage insights export feature.

storage

Specify a storage type. Defaults to loki.

[usage_insights.export.storage.loki]

type

Set the communication protocol to use with Loki, which is either grpc or http. Defaults to grpc.

url

Set the address for writing logs to Loki (format must be host:port).

tls

Decide whether or not to enable the TLS (Transport Layer Security) protocol when establishing the connection to Loki. Defaults to true.

tenant_id

Set the tenant ID for Loki communication, which is disabled by default. The tenant ID is required to interact with Loki running in multi-tenant mode.

batch_wait_duration

How long to wait before sending a request to Loki with the batch of events. Uses duration format: e.g. 5s, 1m. Defaults to 5s.

Whatever happens first between batch_wait_duration and batch_size_bytes will trigger the batch to be sent to Loki.

If the wait duration is very long and the batch_size_bytes is very high, events may take a long time to be sent.

batch_size_bytes

How many events (in bytes) to accumulate in a single batch before sending it to Loki. Defaults to 100 KiB.

Whatever happens first between batch_wait_duration and batch_size_bytes will trigger the batch to be sent to Loki.

If you wish to always wait for the batch_wait_duration, set this to a very high number.

[analytics.summaries]

buffer_write_interval

Interval for writing dashboard usage stats buffer to database.

buffer_write_timeout

Timeout for writing dashboard usage stats buffer to database.

rollup_interval

Interval for trying to roll up per dashboard usage summary. Only rolled up at most once per day.

rollup_timeout

Timeout for trying to rollup per dashboard usage summary.

[analytics.views]

recent_users_age

Age for recent active users.

[reporting]

enabled

Enable or disable the reporting feature. When disabled, no reports are generated, and the UI is hidden. By default, reporting is enabled (true).

rendering_timeout

Timeout for the following reporting rendering requests: generating PDFs, generating embedded dashboard images for report emails, and generating attached CSV files. Default is 10 seconds (10s).

concurrent_render_limit

Maximum number of concurrent calls to the rendering service. Default is 4.

image_scale_factor

Scale factor for rendering images. Value 2 is enough for monitor resolutions, 4 would be better for printed material. Setting a higher value affects performance and memory. Default is 2.

max_attachment_size_mb

Set the maximum file size in megabytes for the report email attachments. Default is 10.

fonts_path

Path to the directory containing font files.

font_regular

Name of the TrueType font file with regular style. Default is DejaVuSansCondensed.ttf.

font_bold

Name of the TrueType font file with bold style.

font_italic

Name of the TrueType font file with italic style. Default is DejaVuSansCondensed-Oblique.ttf.

font_min_text_size

The minimum pixel size that Grafana uses when rendering fonts. Default is 4.

max_request_retries

Maximum number of times the following reporting rendering requests are retried before returning an error: generating PDFs, generating embedded dashboard images for report emails, and generating attached CSV files. Default is 0, which means it is disabled.

allowed_domains

Allowed domains to receive reports. Use an asterisk (*) to allow all domains. Use a comma-separated list to allow multiple domains. Example: allowed_domains = grafana.com, example.org. Default is *.

[auditing]

Auditing allows you to track important changes to your Grafana instance. By default, audit logs are logged to file but the auditing feature also supports sending logs directly to Loki.

enabled

Enable the auditing feature. Defaults to false.

loggers

List of enabled loggers.

log_dashboard_content

Keep dashboard content in the logs (request or response fields). This can significantly increase the size of your logs.

log_datasource_query_request_body

Whether to record data source queries’ request body. This can significantly increase the size of your logs. Enabled by default.

log_datasource_query_response_body

Whether to record data source queries’ response body. This can significantly increase the size of your logs. Enabled by default.

verbose

Log all requests and keep requests and responses body. This can significantly increase the size of your logs.

log_all_status_codes

Set to false to only log requests with 2xx, 3xx, 401, 403, 500 responses.

max_response_size_bytes

Maximum response body (in bytes) to be recorded. May help reducing the memory footprint caused by auditing.

[auditing.logs.file]

path

Path to logs folder.

max_files

Maximum log files to keep.

max_file_size_mb

Max size in megabytes per log file.

[auditing.logs.loki]

url

Set the URL for writing logs to Loki.

tls

If true, it establishes a secure connection to Loki. Defaults to true.

tenant_id

Set the tenant ID for Loki communication, which is disabled by default. The tenant ID is required to interact with Loki running in multi-tenant mode.

retries

The amount of times the HTTP or gRPC client will retry a failed request to Loki. The default is 10.

timeout

The timeout duration of an HTTP request or gRPC call to Loki. The default is 3s.

[auth.saml]

enabled

If true, the feature is enabled. Defaults to false.

allow_sign_up

If true, allow new Grafana users to be created through SAML logins. Defaults to true.

certificate

Base64-encoded public X.509 certificate. Used to sign requests to the IdP.

certificate_path

Path to the public X.509 certificate. Used to sign requests to the IdP.

private_key

Base64-encoded private key. Used to decrypt assertions from the IdP.

private_key_path

Path to the private key. Used to decrypt assertions from the IdP.

idp_metadata

Base64-encoded IdP SAML metadata XML. Used to verify and obtain binding locations from the IdP.

idp_metadata_path

Path to the SAML metadata XML. Used to verify and obtain binding locations from the IdP.

idp_metadata_url

URL to fetch SAML IdP metadata. Used to verify and obtain binding locations from the IdP.

max_issue_delay

Time since the IdP issued a response and the SP is allowed to process it. Defaults to 90 seconds.

metadata_valid_duration

How long the SPs metadata is valid. Defaults to 48 hours.

assertion_attribute_name

Friendly name or name of the attribute within the SAML assertion to use as the user name. Alternatively, this can be a template with variables that match the names of attributes within the SAML assertion.

assertion_attribute_login

Friendly name or name of the attribute within the SAML assertion to use as the user login handle. Defaults to login.

assertion_attribute_email

Friendly name or name of the attribute within the SAML assertion to use as the user email. Defaults to email.

assertion_attribute_groups

Friendly name or name of the attribute within the SAML assertion to use as the user groups.

assertion_attribute_role

Friendly name or name of the attribute within the SAML assertion to use as the user roles.

assertion_attribute_org

Friendly name or name of the attribute within the SAML assertion to use as the user organization.

assertion_attribute_external_uid

Friendly name or name of the attribute within the SAML assertion to use as the user external UID. Defaults to userUID.

allowed_organizations

List of comma- or space-separated organizations. Each user must be a member of at least one organization to log in.

org_mapping

List of comma- or space-separated Organization:OrgId:Role mappings. Organization can be * meaning “All users”. Role is optional and can have the following values: Admin, Editor ,Viewer or None.

role_values_none

List of comma- or space-separated roles that will be mapped to the None role.

role_values_viewer

List of comma- or space-separated roles that will be mapped to the Viewer role.

role_values_editor

List of comma- or space-separated roles that will be mapped to the Editor role.

role_values_admin

List of comma- or space-separated roles that will be mapped to the Admin role.

role_values_grafana_admin

List of comma- or space-separated roles that will be mapped to the Grafana Admin (Super Admin) role.

[keystore.vault]

url

Location of the Vault server.

namespace

Vault namespace if using Vault with multi-tenancy.

auth_method

Method for authenticating towards Vault. Vault is inactive if this option is not set. Current possible values: token.

token

Secret token to connect to Vault when auth_method is token.

lease_renewal_interval

Time between checking if there are any secrets which needs to be renewed.

lease_renewal_expires_within

Time until expiration for tokens which are renewed. Should have a value higher than lease_renewal_interval.

lease_renewal_increment

New duration for renewed tokens. Vault may be configured to ignore this value and impose a stricter limit.

[security.egress]

Security egress makes it possible to control outgoing traffic from the Grafana server.

host_deny_list

A list of hostnames or IP addresses separated by spaces for which requests are blocked.

host_allow_list

A list of hostnames or IP addresses separated by spaces for which requests are allowed. All other requests are blocked.

header_drop_list

A list of headers that are stripped from the outgoing data source and alerting requests.

cookie_drop_list

A list of cookies that are stripped from the outgoing data source and alerting requests.

[security.encryption]

algorithm

Encryption algorithm used to encrypt secrets stored in the database and cookies. Possible values are aes-cfb (default) and aes-gcm. AES-CFB stands for Advanced Encryption Standard in cipher feedback mode, and AES-GCM stands for Advanced Encryption Standard in Galois/Counter Mode.

[caching]

When query caching is enabled, Grafana can temporarily store the results of data source queries and serve cached responses to similar requests.

backend

The caching backend to use when storing cached queries. Options: memory, redis, and memcached.

The default is memory.

enabled

Setting ’enabled’ to true allows users to configure query caching for data sources.

This value is true by default.

Note
This setting enables the caching feature, but it does not turn on query caching for any data source. To turn on query caching for a data source, update the setting on the data source configuration page. For more information, refer to the query caching docs.

ttl

Time to live (TTL) is the time that a query result is stored in the caching system before it is deleted or refreshed. This setting defines the time to live for query caching, when TTL is not configured in data source settings. The default value is 1m (1 minute).

max_ttl

The max duration that a query result is stored in the caching system before it is deleted or refreshed. This value will override ttl config option or data source setting if the ttl value is greater than max_ttl. To disable this constraint, set this value to 0s.

The default is 0s (disabled).

Note
Disabling this constraint is not recommended in production environments.

max_value_mb

This value limits the size of a single cache value. If a cache value (or query result) exceeds this size, then it is not cached. To disable this limit, set this value to 0.

The default is 1.

connection_timeout

This setting defines the duration to wait for a connection to the caching backend.

The default is 5s.

read_timeout

This setting defines the duration to wait for the caching backend to return a cached result. To disable this timeout, set this value to 0s.

The default is 0s (disabled).

Note
Disabling this timeout is not recommended in production environments.

write_timeout

This setting defines the number of seconds to wait for the caching backend to store a result. To disable this timeout, set this value to 0s.

The default is 0s (disabled).

Note
Disabling this timeout is not recommended in production environments.

[caching.encryption]

enabled

When ’enabled’ is true, query values in the cache are encrypted.

The default is false.

encryption_key

A string used to generate a key for encrypting the cache. For the encrypted cache data to persist between Grafana restarts, you must specify this key. If it is empty when encryption is enabled, then the key is automatically generated on startup, and the cache clears upon restarts.

The default is "".

[caching.memory]

gc_interval

When storing cache data in-memory, this setting defines how often a background process cleans up stale data from the in-memory cache. More frequent “garbage collection” can keep memory usage from climbing but will increase CPU usage.

The default is 1m.

max_size_mb

The maximum size of the in-memory cache in megabytes. Once this size is reached, new cache items are rejected. For more flexible control over cache eviction policies and size, use the Redis or Memcached backend.

To disable the maximum, set this value to 0.

The default is 25.

Note
Disabling the maximum is not recommended in production environments.

[caching.redis]

url

The full Redis URL of your Redis server. For example: redis://username:password@localhost:6379. To enable TLS, use the rediss scheme.

The default is "redis://localhost:6379".

cluster

A comma-separated list of Redis cluster members, either in host:port format or using the full Redis URLs (redis://username:password@localhost:6379). For example, localhost:7000, localhost: 7001, localhost:7002. If you use the full Redis URLs, then you can specify the scheme, username, and password only once. For example, redis://username:password@localhost:0000,localhost:1111,localhost:2222. You cannot specify a different username and password for each URL.

Note
If you have specify cluster, the value for url is ignored.

Note
You can enable TLS for cluster mode using the rediss scheme in Grafana Enterprise v8.5 and later versions.

prefix

A string that prefixes all Redis keys. This value must be set if using a shared database in Redis. If prefix is empty, then one will not be used.

The default is "grafana".

[caching.memcached]

servers

A space-separated list of memcached servers. Example: memcached-server-1:11211 memcached-server-2:11212 memcached-server-3:11211. Or if there’s only one server: memcached-server:11211.

The default is "localhost:11211".

tls_enabled

Enables TLS authentication for memcached. Defaults to false.

tls_cert_path

Path to the client certificate, which will be used for authenticating with the server. Also requires the key path to be configured.

tls_key_path

Path to the key for the client certificate. Also requires the client certificate to be configured.

tls_ca_path

Path to the CA certificates to validate the server certificate against. If not set, the host’s root CA certificates are used.

tls_server_name

Override the expected name on the server certificate.

connection_timeout

Timeout for the memcached client to connect to memcached. Defaults to 0, which uses the memcached client default timeout per connection scheme.

[recorded_queries]

enabled

Whether the recorded queries feature is enabled

min_interval

Sets the minimum interval to enforce between query evaluations. The default value is 10s. Query evaluation will be adjusted if they are less than this value. Higher values can help with resource management.

The interval string is a possibly signed sequence of decimal numbers, followed by a unit suffix (ms, s, m, h, d), e.g. 30s or 1m.

max_queries

The maximum number of recorded queries that can exist.

default_remote_write_datasource_uid

The UID of the datasource where the query data will be written.

If all default_remote_write_* properties are set, this information will be populated at startup. If a remote write target has already been configured, nothing will happen.

default_remote_write_path

The api path where metrics will be written

If all default_remote_write_* properties are set, this information will be populated at startup. If a remote write target has already been configured, nothing will happen.

default_remote_write_datasource_org_id

The org id of the datasource where the query data will be written.

If all default_remote_write_* properties are set, this information will be populated at startup. If a remote write target has already been configured, nothing will happen.

Configure feature toggles

Fri, 03 Apr 2026 19:43:06 +0000

Configure feature toggles

You use feature toggles, also known as feature flags, to enable or disable features in Grafana. You can turn on feature toggles to try out new functionality in development or test environments.

This page contains a list of available feature toggles. To learn how to turn on feature toggles, refer to our Configure Grafana documentation. Feature toggles are also available to Grafana Cloud Advanced customers. If you use Grafana Cloud Advanced, you can open a support ticket and specify the feature toggles and stack for which you want them enabled.

For more information about feature release stages, refer to Release life cycle for Grafana Labs and Manage feature toggles.

General availability feature toggles

Most generally available features are enabled by default. You can disable these feature by setting the feature flag to “false” in the configuration.

Feature toggle name	Description	Enabled by default
`publicDashboardsScene`	Enables public dashboard rendering using scenes	Yes
`featureHighlights`	Highlight Grafana Enterprise features
`cloudWatchCrossAccountQuerying`	Enables cross-account querying in CloudWatch datasources	Yes
`logsContextDatasourceUi`	Allow datasource to provide custom UI for context view	Yes
`lokiQuerySplitting`	Split large interval queries into subqueries with smaller time intervals	Yes
`influxdbBackendMigration`	Query InfluxDB InfluxQL without the proxy	Yes
`logsExploreTableVisualisation`	A table visualisation for logs in Explore	Yes
`awsDatasourcesTempCredentials`	Support temporary security credentials in AWS plugins for Grafana Cloud customers	Yes
`awsAsyncQueryCaching`	Enable caching for async queries for Redshift and Athena. Requires that the datasource has caching and async query support enabled	Yes
`dashgpt`	Enable AI powered features in dashboards	Yes
`kubernetesDashboards`	Use the kubernetes API in the frontend for dashboards	Yes
`cloudWatchBatchQueries`	Runs CloudWatch metrics queries as separate batches
`annotationPermissionUpdate`	Change the way annotation permissions work by scoping them to folders and dashboards.	Yes
`dashboardScene`	Enables dashboard rendering using scenes for all roles	Yes
`alertingQueryOptimization`	Optimizes eligible queries in order to reduce load on datasources
`cloudWatchNewLabelParsing`	Updates CloudWatch label parsing to be more accurate	Yes
`pluginProxyPreserveTrailingSlash`	Preserve plugin proxy trailing slash.
`azureMonitorPrometheusExemplars`	Allows configuration of Azure Monitor as a data source that can provide Prometheus exemplars	Yes
`cloudWatchRoundUpEndTime`	Round up end time for metric queries to the next minute to avoid missing data	Yes
`newFiltersUI`	Enables new combobox style UI for the Ad hoc filters variable in scenes architecture	Yes
`alertingQueryAndExpressionsStepMode`	Enables step mode for alerting queries and expressions	Yes
`improvedExternalSessionHandling`	Enables improved support for OAuth external sessions. After enabling this feature, users might need to re-authenticate themselves.	Yes
`useSessionStorageForRedirection`	Use session storage for handling the redirection after login	Yes
`pluginsSriChecks`	Enables SRI checks for plugin assets
`timeRangePan`	Enables time range panning functionality	Yes
`newTimeRangeZoomShortcuts`	Enables new keyboard shortcuts for time range zoom operations	Yes
`azureMonitorDisableLogLimit`	Disables the log limit restriction for Azure Monitor when true. The limit is enabled by default.
`enableSCIM`	Enables SCIM support for user and group management	Yes
`alertingUIOptimizeReducer`	Enables removing the reducer from the alerting UI when creating a new alert rule and using instant query	Yes
`azureMonitorEnableUserAuth`	Enables user auth for Azure Monitor datasource only	Yes
`alertingNotificationsStepMode`	Enables simplified step mode in the notifications section	Yes
`elasticsearchCrossClusterSearch`	Enables cross cluster search in the Elasticsearch data source
`lokiLabelNamesQueryApi`	Defaults to using the Loki `/labels` API instead of `/series`	Yes
`improvedExternalSessionHandlingSAML`	Enables improved support for SAML external sessions. Ensure the NameID format is correctly configured in Grafana for SAML Single Logout to function properly.	Yes
`newLogsPanel`	Enables the new logs panel	Yes
`alertingMigrationUI`	Enables the alerting migration UI, to migrate data source-managed rules to Grafana-managed rules	Yes
`alertingImportYAMLUI`	Enables a UI feature for importing rules from a Prometheus file to Grafana-managed rules	Yes
`unifiedNavbars`	Enables unified navbars
`grafanaAssistantInProfilesDrilldown`	Enables integration with Grafana Assistant in Profiles Drilldown	Yes
`sharingDashboardImage`	Enables image sharing functionality for dashboards	Yes
`tabularNumbers`	Use fixed-width numbers globally in the UI
`azureResourcePickerUpdates`	Enables the updated Azure Monitor resource picker	Yes
`opentsdbBackendMigration`	Run queries through the data source backend

Public preview feature toggles

Public preview features are supported by our Support teams, but might be limited to enablement, configuration, and some troubleshooting.

Feature toggle name	Description
`panelTitleSearch`	Search for dashboards using panel title
`grpcServer`	Run the GRPC server
`renderAuthJWT`	Uses JWT-based auth for rendering instead of relying on remote cache
`refactorVariablesTimeRange`	Refactor time range variables flow to reduce number of API calls made when query variables are chained
`faroDatasourceSelector`	Enable the data source selector within the Frontend Apps section of the Frontend Observability
`enableDatagridEditing`	Enables the edit functionality in the datagrid panel
`externalServiceAccounts`	Automatic service account and token setup for plugins
`dashboardNewLayouts`	Enables new dashboard layouts
`pdfTables`	Enables generating table data as PDF in reporting
`canvasPanelPanZoom`	Allow pan and zoom in canvas panel
`alertingSaveStateCompressed`	Enables the compressed protobuf-based alert state storage. Default is enabled.
`sqlExpressions`	Enables SQL Expressions, which can execute SQL queries against data source results.
`queryLibrary`	Enables Saved queries (query library) feature
`savedQueriesRBAC`	Enables Saved queries (query library) RBAC permissions
`dashboardTemplates`	Enables a flow to get started with a new dashboard from a template
`alertRuleRestore`	Enables the alert rule restore feature
`azureMonitorLogsBuilderEditor`	Enables the logs builder mode for the Azure Monitor data source
`logsPanelControls`	Enables a control component for the logs panel in Explore
`interactiveLearning`	Enables the interactive learning app
`newGauge`	Enable new gauge visualization
`newVizSuggestions`	Enable new visualization suggestions
`vizPresets`	Enable visualization presets
`preventPanelChromeOverflow`	Restrict PanelChrome contents with overflow: hidden;
`newPanelPadding`	Increases panel padding globally
`transformationsEmptyPlaceholder`	Show transformation quick-start cards in empty transformations state

Development feature toggles

The following toggles require explicitly setting Grafana’s app mode to ‘development’ before you can enable this feature toggle. These features tend to be experimental.

Feature toggle name	Description
`grafanaAPIServerWithExperimentalAPIs`	Register experimental APIs with the k8s API server, including all datasources
`grafanaAPIServerEnsureKubectlAccess`	Start an additional https handler and write kubectl options

Configure profiling and tracing to troubleshoot Grafana

Fri, 03 Apr 2026 19:43:06 +0000

Configure profiling and tracing to troubleshoot Grafana

You can set up the grafana-server process to enable certain diagnostics when it starts. This can be useful when investigating certain performance problems. It’s not recommended to have these enabled by default.

Turn on profiling and collect profiles

The grafana-server can be started with the command-line option -profile to enable profiling, -profile-addr to override the default HTTP address (localhost), and -profile-port to override the default HTTP port (6060) where the pprof debugging endpoints are available. Further, -profile-block-rate controls the fraction of goroutine blocking events that are reported in the blocking profile, default 1 (i.e. track every event) for backward compatibility reasons, and -profile-mutex-rate controls the fraction of mutex contention events that are reported in the mutex profile, default 0 (i.e. track no events). The higher the fraction (that is, the smaller this value) the more overhead it adds to normal operations.

Running Grafana with profiling enabled and without block and mutex profiling enabled should only add a fraction of overhead and is suitable for continuous profiling. Adding a small fraction of block and mutex profiling, such as 10-5 (10%-20%) should in general be fine.

Enable profiling:

./grafana server -profile -profile-addr=0.0.0.0 -profile-port=8080

Enable profiling with block and mutex profiling enabled with a fraction of 20%:

./grafana server -profile -profile-addr=0.0.0.0 -profile-port=8080 -profile-block-rate=5 -profile-mutex-rate=5

Note that pprof debugging endpoints are served on a different port than the Grafana HTTP server. Check what debugging endpoints are available by browsing http://<profile-addr><profile-port>/debug/pprof.

There are some additional godeltaprof endpoints available which are more suitable in a continuous profiling scenario. These endpoints are /debug/pprof/delta_heap, /debug/pprof/delta_block, /debug/pprof/delta_mutex.

You can configure or override profiling settings using environment variables:

export GF_DIAGNOSTICS_PROFILING_ENABLED=true
export GF_DIAGNOSTICS_PROFILING_ADDR=0.0.0.0
export GF_DIAGNOSTICS_PROFILING_PORT=8080
export GF_DIAGNOSTICS_PROFILING_BLOCK_RATE=5
export GF_DIAGNOSTICS_PROFILING_MUTEX_RATE=5

In general, you use the Go command pprof to both collect and analyze profiling data. You can also use curl or similar to collect profiles which could be convenient in environments where you don’t have the Go/pprof command available. Next, some usage examples of using curl and pprof to collect and analyze memory and CPU profiles.

Analyzing high memory usage/memory leaks:

When experiencing high memory usage or potential memory leaks it’s useful to collect several heap profiles and later when analyzing, compare them. It’s a good idea to wait some time, e.g. 30 seconds, between collecting each profile to allow memory consumption to increase.

curl http://<profile-addr>:<profile-port>/debug/pprof/heap > heap1.pprof
sleep 30
curl http://<profile-addr>:<profile-port>/debug/pprof/heap > heap2.pprof

You can then use pprof tool to compare two heap profiles:

go tool pprof -http=localhost:8081 --base heap1.pprof heap2.pprof

Analyzing high CPU usage:

When experiencing high CPU usage it’s suggested to collect CPU profiles over a period of time, e.g. 30 seconds.

curl 'http://<profile-addr>:<profile-port>/debug/pprof/profile?seconds=30' > profile.pprof

You can then use pprof tool to analyze the collected CPU profile:

go tool pprof -http=localhost:8081 profile.pprof

Use tracing

The grafana-server can be started with the arguments -tracing to enable tracing and -tracing-file to override the default trace file (trace.out) where trace result is written to. For example:

./grafana server -tracing -tracing-file=/tmp/trace.out

You can configure or override profiling settings using environment variables:

export GF_DIAGNOSTICS_TRACING_ENABLED=true
export GF_DIAGNOSTICS_TRACING_FILE=/tmp/trace.out

View the trace in a web browser (Go required to be installed):

go tool trace <trace file>
2019/11/24 22:20:42 Parsing trace...
2019/11/24 22:20:42 Splitting trace...
2019/11/24 22:20:42 Opening browser. Trace viewer is listening on http://127.0.0.1:39735

For more information about how to analyze trace files, refer to Go command trace.

Configure custom branding

Fri, 03 Apr 2026 19:43:06 +0000

Configure custom branding

Custom branding enables you to replace the Grafana Labs brand and logo with your corporate brand and logo.

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team. For Cloud customers, please provide custom elements and logos to our Support team. We will help you host your images and update your custom branding.

The grafana.ini file includes Grafana Enterprise custom branding. As with all configuration options, you can use environment variables to set custom branding.

With custom branding, you have the ability to modify the following elements:

Application title
Login background
Login logo
Side menu top logo
Footer and help menu links
Fav icon (shown in browser tab)
Login title (will not appear if a login logo is set)
Login subtitle (will not appear if a login logo is set)
Login box background
Loading logo

You will have to host your logo and other images used by the custom branding feature separately. Make sure Grafana can access the URL where the assets are stored.

The configuration file in Grafana Enterprise contains the following options. For more information about configuring Grafana, refer to Configure Grafana.

# Enterprise only
[white_labeling]
# Set to your company name to override application title
;app_title =

# Set to main title on the login page (Will not appear if a login logo is set)
;login_title =

# Set to login subtitle (Will not appear if a login logo is set)
;login_subtitle =

# Set to complete URL to override login logo
;login_logo =

# Set to complete CSS background expression to override login background
# example: login_background = url(http://www.bhmpics.com/wallpapers/starfield-1920x1080.jpg)
;login_background =

# Set to complete CSS background expression to override login box background
;login_box_background =

# Set to complete URL to override menu logo
;menu_logo =

# Set to complete URL to override fav icon (icon shown in browser tab)
;fav_icon =

# Set to complete URL to override apple/ios icon
;apple_touch_icon =

# Set to complete URL to override loading logo
;loading_logo =

# Set to `true` to remove the Grafana edition from appearing in the footer
;hide_edition =

Note
For the login_logo option, Grafana recommends using SVG files that are 48 pixels by 48 pixels or smaller. You also don’t need to use the url() function for login_logo.

Additionally, you can copy images to the local Grafana image directory, /usr/share/grafana/public/img/, and set login_logo to the stored image. For example:
ini
login_logo = /public/img/<YOUR_LOGO.svg>

You have the option of adding custom links in place of the default footer links (Documentation, Support, Community). Below is an example of how to replace the default footer and help links with custom links.

footer_links = support guides extracustom
footer_links_support_text = Support
footer_links_support_url = http://your.support.site
footer_links_guides_text = Guides
footer_links_guides_url = http://your.guides.site
footer_links_extracustom_text = Custom text
footer_links_extracustom_url = http://your.custom.site

The following example shows configuring custom branding using environment variables instead of the custom.ini or grafana.ini files.

GF_WHITE_LABELING_FOOTER_LINKS=support guides extracustom
GF_WHITE_LABELING_FOOTER_LINKS_SUPPORT_TEXT=Support
GF_WHITE_LABELING_FOOTER_LINKS_SUPPORT_URL=http://your.support.site
GF_WHITE_LABELING_FOOTER_LINKS_GUIDES_TEXT=Guides
GF_WHITE_LABELING_FOOTER_LINKS_GUIDES_URL=http://your.guides.site
GF_WHITE_LABELING_FOOTER_LINKS_EXTRACUSTOM_TEXT=Custom Text
GF_WHITE_LABELING_FOOTER_LINKS_EXTRACUSTOM_URL=http://your.custom.site

Note
The following two links are always present in the footer:

Grafana edition
Grafana version with build number

If you specify footer_links or GF_WHITE_LABELING_FOOTER_LINKS, then all other default links are removed from the footer, and only what is specified is included.

Custom branding for shared dashboards

In addition to the customizations described below, you can customize the footer of your shared dashboards. To customize the footer of a shared dashboard, add the following section to the grafana.ini file.

[white_labeling.public_dashboards]

# Hides the footer for the shared dashboards if set to `true`.
# example: footer_hide = "true"
;footer_hide =

# Set to text shown in the footer
;footer_text =

# Set to complete url to override shared dashboard footer logo. Default is `grafana-logo` and will display the Grafana logo.
# An empty value will hide the footer logo.
;footer_logo =

# Set to link for the footer
;footer_link =

# Set to `true` to hide the Grafana logo next to the title
;header_logo_hide =

If you specify footer_hide to true, all the other values are ignored because the footer will not be shown.

Settings updates at runtime

Fri, 03 Apr 2026 19:43:06 +0000

Settings updates at runtime

Note
This functionality is deprecated and will be removed in a future release. For configuring SAML authentication, please use the new SSO settings API.

By updating settings at runtime, you can update Grafana settings without needing to restart the Grafana server.

Updates that happen at runtime are stored in the database and override settings from other sources (arguments, environment variables, settings file, etc). Therefore, every time a specific setting key is removed at runtime, the value used for that key is the inherited one from the other sources in the reverse order of precedence (arguments > environment variables > settings file). When no value is provided through any of these options, then the value used will be the application default

Currently, it only supports updates on the auth.saml section.

Update settings via the API

You can update settings through the Admin API.

When you submit a settings update via API, Grafana verifies if the given settings updates are allowed and valid. If they are, then Grafana stores the settings in the database and reloads Grafana services with no need to restart the instance.

So, the payload of a PUT request to the update settings endpoint (/api/admin/settings) should contain (either one or both):

An updates map with a key, and a value per section you want to set.
A removals list with keys per section you want to unset.

For example, if you provide the following updates:

{
  "updates": {
    "auth.saml": {
      "enabled": "true",
      "single_logout": "false"
    }
  }
}

it would enable SAML and disable single logouts. And, if you provide the following removals:

{
  "removals": {
    "auth.saml": ["allow_idp_initiated"]
  }
}

it would remove the key/value setting identified by allow_idp_initiated within the auth.saml. So, the SAML service would be reloaded and that value would be inherited for either (settings .ini file, environment variable, command line arguments or any other accepted mechanism to provide configuration).

Therefore, the complete HTTP payload would looks like:

{
  "updates": {
    "auth.saml": {
      "enabled": "true",
      "single_logout": "false"
    }
  },
  "removals": {
    "auth.saml": ["allow_idp_initiated"]
  }
}

In case any of these settings cannot be overridden nor valid, it would return an error and these settings won’t be persisted into the database.

Background job (high availability set-ups)

Grafana Enterprise has a built-in scheduled background job that looks into the database every minute for settings updates. If there are updates, it reloads the Grafana services affected by the detected changes.

The background job synchronizes settings between instances in a highly available set-up. So, after you perform some changes through the HTTP API, then the other instances are synchronized through the database and the background job.

Control access with role-based access control

If you have role-based access control enabled, you can control who can read or update settings. Refer to the Admin API for more information.

Configure a data source SOCKS5 connection proxy

Fri, 03 Apr 2026 19:43:06 +0000

Configure a data source SOCKS5 connection proxy

Grafana provides support for proxying data source connections through a secure SOCKS5 proxy. This enables you to securely connect to data sources hosted in a different network than Grafana.

To make use of this functionality, you need to deploy a SOCKS5 proxy server that supports TLS on a machine accessible from where your Grafana instance is running, and within the same network as your data source. From there, Grafana establishes a mutually trusted connection from Grafana to the proxy. Then the SOCKS5 proxy can proxy the Grafana data source connection to your private data source instance without exposing your data source to the public internet.

Known limitations

You can configure only one SOCKS5 proxy per Grafana instance. This is because the SOCKS5 proxy address and TLS configuration is set at the Grafana instance level.
All built-in core data sources are compatible, but not all external data sources are. For a list of supported data sources, refer to private data source connect.

Before you begin

To complete this task, you must first have a SOCKS5 proxy server running, using host certificates signed by a Certificate Authority (CA) that you can get the public certificate for. You must also have a TLS client key pair for Grafana, with the client certificate signed by the same CA used to sign the proxy server certificate.

Steps

For Grafana to send data source connections to the socks5 server, use the following table to configure the secure_socks_datasource_proxy section of the config.ini:

Key	Description	Example
`enabled`	Enable this feature in Grafana	true
`root_ca_cert`	The file path of the root ca cert used to sign the proxy server certificate	/etc/ca.crt
`client_key`	The file path of the client private key	/etc/client.key
`client_cert`	The file path of the client public key	/etc/client.crt
`server_name`	The domain name of the proxy, used for SNI	proxy.grafana.svc.cluster.local
`proxy_address`	The address of the proxy	localhost:9090
`allow_insecure`	Disable TLS in the socks proxy	false

Set up a data source and configure it to send data source connections through the proxy.

To configure your data sources to send connections through the proxy, enableSecureSocksProxy=true must be specified in the data source json. You can do this in the API or use file based provisioning.

Additionally, if using SOCKS5 authentication, you can set the SOCKS5 username and password by adding secureSocksProxyUsername in the data source’s jsonData field and secureSocksProxyPassword in the data source’s secureJsonData field.