Documentation Grafana documentation Set up Configure Grafana

Configure Grafana

You can use Grafana Cloud to avoid installing, maintaining, and scaling your own instance of Grafana. Create a free account to get started, which includes free forever access to 10k metrics, 50GB logs, 50GB traces, 500VUh k6 testing & more.

Grafana has default and custom configuration files.

Customize your Grafana instance

You can customize your Grafana instance by modifying the custom configuration file or by using environment variables.

• To see the list of settings for a Grafana instance, refer to View server settings.
• After you add custom options, uncomment the relevant sections of the configuration file and restart Grafana for your changes to take effect.

Configuration file location

The default settings for a Grafana instance are stored in the <WORKING DIRECTORY>/conf/defaults.ini file. Don’t change this file.

Depending on your OS, your custom configuration file is either the <WORKING DIRECTORY>/conf/custom.ini file or the /usr/local/etc/grafana/grafana.ini file. You can use a custom configuration path with the --config option.

Linux

If you installed Grafana using the deb or RPM packages, then your configuration file is located at /etc/grafana/grafana.ini and a separate custom.ini is not used. This path is specified in the Grafana init.d script using --config option.

Docker

Refer to Configure a Grafana Docker image for information about environmental variables, persistent storage, and building custom Docker images.

Windows

On Windows, the sample.ini file is located in the same directory as defaults.ini file. It contains all the settings commented out. Copy sample.ini and name it custom.ini.

macOS

By default, the configuration file is located at /opt/homebrew/etc/grafana/grafana.ini or /usr/local/etc/grafana/grafana.ini. For a Grafana instance installed using Homebrew, edit the grafana.ini file directly. Otherwise, add a configuration file named custom.ini to the conf directory to override the settings defined in conf/defaults.ini.

Grafana Cloud

There is no local configuration file for Grafana Cloud stacks, but many of these settings are still configurable. To edit configurable settings, open a support ticket.

Remove comments in the .ini files

Grafana uses semicolons (;) to comment out lines in the INI file. To uncomment a line, remove the semicolon (;) from the beginning of that line.

Grafana ignores all configuration lines that begin with a semicolon.

For example:

ini Copy

;http_port = 3000

Override configuration with environment variables

Don’t use environment variables to add new configuration settings. Instead, use environment variables to override existing options.

To override an option:

Bash Copy

GF_<SECTION NAME>_<KEY>

Where <SECTION NAME> is the text within the square brackets ([ and ]) in the configuration file. All letters must be uppercase, periods (.) and dashes (-) must replaced by underscores (_). For example, if you have these configuration settings:

ini Copy

# default section
instance_name = ${HOSTNAME}

[security]
admin_user = admin

[auth.google]
client_secret = 0ldS3cretKey

[plugin.grafana-image-renderer]
rendering_ignore_https_errors = true

[feature_toggles]
newNavigation = true

You can override variables on Linux machines with:

Bash Copy

export GF_DEFAULT_INSTANCE_NAME=my-instance
export GF_SECURITY_ADMIN_USER=owner
export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey
export GF_PLUGIN_GRAFANA_IMAGE_RENDERER_RENDERING_IGNORE_HTTPS_ERRORS=true
export GF_FEATURE_TOGGLES_newNavigation=true

Variable expansion

If any of your options contains the expression $__<PROVIDER>{<ARGUMENT>}or ${<ENVIRONMENT VARIABLE>}, then Grafana evaluates them. The evaluation runs the provider with the provided argument to get the final value of the option.

There are three providers: env, file, and vault.

env provider

The env provider expands environment variables. If you set an option to $__env{PORT} the value of the PORT environment variable replaces it. For environment variables you can also use the short-hand syntax ${PORT}.

The following example sets the log directory to the path in the LOGDIR environment variable:

ini Copy

[paths]
logs = $__env{LOGDIR}/grafana

file provider

The file provider reads a file from the filesystem. It trims whitespace from the beginning and the end of files.

The following example sets the database password to the contents of the /etc/secrets/gf_sql_password file:

ini Copy

[database]
password = $__file{/etc/secrets/gf_sql_password}

vault provider

The vault provider lets manage your secrets with Hashicorp Vault.

Configuration options

The following headings describe the sections and configuration options of the Grafana configuration file.

app_mode

Options are production and development. Default is production. Don’t change this option unless you are working on Grafana development.

instance_name

Set the name of the Grafana server instance. Used in logging, internal metrics, and clustering info. Defaults to: ${HOSTNAME}, which uses the value of the environment variable HOSTNAME, if that is empty or doesn’t exist Grafana tries to use system calls to get the machine name.

[paths]

data

Path to where Grafana stores the sqlite3 database (if used), file-based sessions (if used), and other data. This path is usually specified via command line in the init.d script or the systemd service file.

macOS: The default SQLite database is located at /usr/local/var/lib/grafana

temp_data_lifetime

How long temporary images in data directory should be kept. Defaults to: 24h. Supported modifiers: h (hours), m (minutes), for example: 168h, 30m, 10h30m. Use 0 to never clean up temporary files.

logs

Path to where Grafana stores logs. This path is usually specified via command line in the init.d script or the systemd service file. You can override it in the configuration file or in the default environment variable file.

Override log path using the command line argument cfg:default.paths.logs:

Bash Copy

./grafana-server --config /custom/config.ini --homepath /custom/homepath cfg:default.paths.logs=/custom/path

macOS: By default, the log file should be located at /usr/local/var/log/grafana/grafana.log.

plugins

Directory where Grafana automatically scans and looks for plugins. For information about manually or automatically installing plugins, refer to Install Grafana plugins.

macOS: By default, the Mac plugin location is: /usr/local/var/lib/grafana/plugins.

provisioning

Directory that contains provisioning configuration files that Grafana applies on startup. Dashboards are reloaded when the JSON files change.

[server]

protocol

http,https,h2,socket or socket_h2

min_tls_version

The TLS Handshake requires a minimum TLS version. The available options are TLS1.2 and TLS1.3. If you do not specify a version, the system uses TLS1.2.

http_addr

The host for the server to listen on. If your machine has more than one network interface, you can use this setting to expose the Grafana service on only one network interface and not have it available on others, such as the loopback interface. An empty value is equivalent to setting the value to 0.0.0.0, which means the Grafana service binds to all interfaces.

In environments where network address translation (NAT) is used, ensure you use the network interface address and not a final public address; otherwise, you might see errors such as bind: cannot assign requested address in the logs.

http_port

The port to bind to, defaults to 3000. To use port 80 you need to either give the Grafana binary permission for example:

Bash Copy

sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server

Or redirect port 80 to the Grafana port using:

Bash Copy

sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000

Another way is to put a web server like Nginx or Apache in front of Grafana and have them proxy requests to Grafana.

domain

This setting is only used in as a part of the root_url setting (see below). Important if you use GitHub or Google OAuth.

enforce_domain

Redirect to correct domain if the host header does not match the domain. Prevents DNS rebinding attacks. Default is false.

root_url

This is the full URL used to access Grafana from a web browser. This is important if you use Google or GitHub OAuth authentication (for the callback URL to be correct).

serve_from_sub_path

Serve Grafana from sub-path specified in root_url setting. By default it is set to false for compatibility reasons.

By enabling this setting and using a sub-path in root_url like root_url = http://localhost:3000/grafana, Grafana is accessible on http://localhost:3000/grafana. If accessed without sub-path Grafana redirects the request to the sub-path.

router_logging

Set to true for Grafana to log all HTTP requests (not just errors). These are logged as Info level events to the Grafana log.

static_root_path

The path to the directory where the frontend files (HTML, JS, and CSS files). Defaults to public which is why the Grafana binary needs to be executed with working directory set to the installation path.

enable_gzip

Set this option to true to enable HTTP compression, this can improve transfer speed and bandwidth utilization. It is recommended that most users leave it set at the default of true, however compression might increase CPU usage on constrained environments or cause issues with poorly-configured reverse proxies.

cert_file

Path to the certificate file (if protocol is set to https or h2).

cert_key

Path to the certificate key file (if protocol is set to https or h2).

cert_pass

Optional. Password to decrypt encrypted certificates.

certs_watch_interval

Controls whether cert_key and cert_file are periodically watched for changes. Disabled, by default. When enabled, cert_key and cert_file are watched for changes. If there is change, the new certificates are loaded automatically.

socket_gid

GID of the socket when protocol=socket. Make sure that the user running the Grafana process is a member of the target group and is the file owner before you change this setting. It is recommended to set the GID as HTTP server user GID. Not set when the value is -1.

socket_mode

Mode where the socket should be set when protocol=socket. Make sure that Grafana process is the file owner before you change this setting.

socket

Path where the socket should be created when protocol=socket. Make sure Grafana has appropriate permissions for that path before you change this setting.

serve_on_socket

If set to true and the primary protocol is http, https, or h2, Grafana will additionally serve on the Unix domain socket configured via socket. Defaults to false.

cdn_url

Specify a full HTTP URL address to the root of your Grafana CDN assets. Grafana adds edition and version paths.

For example, given a CDN URL like https://cdn.myserver.com, Grafana tries to load a JavaScript file from http://cdn.myserver.com/grafana-oss/7.4.0/public/build/app.<HASH>.js.

read_timeout

Sets the maximum time using a duration format (5s/5m/5ms) before timing out read of an incoming request and closing idle connections. 0 means there is no timeout for reading the request.

[server.custom_response_headers]

This setting enables you to specify additional headers that the server adds to HTTP(S) responses.

Copy

exampleHeader1 = exampleValue1
exampleHeader2 = exampleValue2

[database]

Grafana needs a database to store users and dashboards (and other things). By default it is configured to use sqlite3 which is an embedded database (included in the main Grafana binary).

type

Either mysql, postgres or sqlite3, it’s your choice.

host

Only applicable to MySQL or Postgres. Includes IP or hostname and port or in case of Unix sockets the path to it. For example, for MySQL running on the same host as Grafana: host = 127.0.0.1:3306 or with Unix sockets: host = /var/run/mysqld/mysqld.sock

name

The name of the Grafana database. Leave it set to grafana or some other name.

user

The database user (not applicable for sqlite3).

password

The database user’s password (not applicable for sqlite3). If the password contains # or ; you have to wrap it with triple quotes. For example """#password;"""

url

Use either URL or the previous fields to configure the database Example: type://user:password@host:port/name

max_idle_conn

The maximum number of connections in the idle connection pool.

max_open_conn

The maximum number of open connections to the database. For MYSQL, configure this setting on both Grafana and the database. For more information, refer to sysvar_max_connections.

conn_max_lifetime

Sets the maximum amount of time a connection may be reused. The default is 14400 (which means 14400 seconds or 4 hours). For MySQL, this setting should be shorter than the wait_timeout variable.

migration_locking

Set to false to disable database locking during the migrations. Default is true.

locking_attempt_timeout_sec

For mysql and postgres only. Specify the time, in seconds, to wait before failing to lock the database for the migrations. Default is 0.

log_queries

Set to true to log the SQL calls and execution times.

ssl_mode

For Postgres, use any valid libpq sslmode, for example, disable, require, verify-full, etc. For MySQL, use either true, false, or skip-verify.

ssl_sni

For Postgres, set to 0 to disable Server Name Indication. This is enabled by default on SSL-enabled connections.

isolation_level

Only the MySQL driver supports isolation levels in Grafana. In case the value is empty, the driver’s default isolation level is applied. Available options are “READ-UNCOMMITTED”, “READ-COMMITTED”, “REPEATABLE-READ” or “SERIALIZABLE”.

ca_cert_path

The path to the CA certificate to use. On many Linux systems, certs can be found in /etc/ssl/certs.

client_key_path

The path to the client key. Only if server requires client authentication.

client_cert_path

The path to the client cert. Only if server requires client authentication.

server_cert_name

The common name field of the certificate used by the mysql or postgres server. Not necessary if ssl_mode is set to skip-verify.

path

Only applicable for sqlite3 database. The path to the database file.

cache_mode

For “sqlite3” only. Shared cache setting used for connecting to the database. (private, shared) Defaults to private.

wal

For “sqlite3” only. Setting to enable/disable Write-Ahead Logging. The default value is false (disabled).

SQLite stores the journal mode in the database file, so a database that was opened with WAL keeps using it. Setting wal back to false puts the database into DELETE journal mode again on the next start.

query_retries

This setting applies to sqlite only and controls the number of times the system retries a query when the database is locked. The default value is 0 (disabled).

transaction_retries

This setting applies to sqlite only and controls the number of times the system retries a transaction when the database is locked. The default value is 5.

instrument_queries

Set to true to add metrics and tracing for database queries. The default value is false.

[remote_cache]

Caches authentication tokens and other temporary authentication-related data in the configured database, Redis, or Memcached. This setting doesn’t configure Query Caching in Grafana Enterprise.

type

Either redis, memcached, or database. Defaults to database

connstr

The remote cache connection string. The format depends on the type of the remote cache. Options are database, redis, and memcache.

database

Leave empty when using database and Grafana uses the primary database.

redis

Example connection string: network=tcp,addr=127.0.0.1:6379,pool_size=100,db=0,username=grafana,password=grafanaRocks,ssl=false

• network (optional) can be tcp or unix.
• addr is the host : port of the Redis server.
• pool_size (optional) is the number of underlying connections that can be made to Redis.
• db (optional) is the number identifier of the Redis database you want to use.
• username (optional) is the connection identifier to authenticate the current connection.
• password (optional) is the connection secret to authenticate the current connection.
• ssl (optional) is if SSL should be used to connect to Redis server. The value may be true, false, or insecure. Setting the value to insecure skips verification of the certificate chain and hostname when making the connection.

memcache

Example connection string: 127.0.0.1:11211

[dataproxy]

logging

This enables data proxy logging, default is false.

timeout

How long the data proxy should wait before timing out. Default is 30 seconds.

This setting also applies to core backend HTTP data sources where query requests use an HTTP client with timeout set.

keep_alive_seconds

Interval between keep-alive probes. Default is 30 seconds. For more details, refer to the Dialer.KeepAlive documentation.

tls_handshake_timeout_seconds

The length of time that Grafana waits for a successful TLS handshake with the data source. Default is 10 seconds. For more information, refer to the Transport.TLSHandshakeTimeout documentation.

expect_continue_timeout_seconds

The length of time that Grafana waits for the first response headers from a data source after fully writing the request headers, if the request has an Expect: 100-continue header. A value of 0 results in the body being sent immediately. Default is 1 second. For more information, refer to the Transport.ExpectContinueTimeout documentation.

max_conns_per_host

Limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials are blocked. A value of 0 means that there are no limits. Default is 0. For more information, refer to the Transport.MaxConnsPerHost documentation.

max_idle_connections

The maximum number of idle connections that Grafana maintains. Default is 100. For more information, refer to the Transport.MaxIdleConns documentation.

idle_conn_timeout_seconds

The length of time that Grafana maintains idle connections before closing them. Default is 90 seconds. For more information, refer to the Transport.IdleConnTimeout documentation.

send_user_header

If enabled and user is not anonymous, data proxy adds the X-Grafana-User header with username into the request. Default is false.

response_limit

Limits the amount of bytes that Grafana reads from responses of outgoing HTTP requests. Default is 0 which means disabled.

row_limit

Limits the number of rows that Grafana processes from SQL data sources. Default is 1000000.

user_agent

Sets a custom value for the User-Agent header for outgoing data proxy requests. If empty, the default value is Grafana/<BuildVersion> (for example Grafana/13.0.0).

forward_user_agent

If enabled, the data proxy preserves the client’s original User-Agent header by appending it to the proxy’s User-Agent. Useful for tracking the originating client (browser, CLI, AI agent, etc.) at upstream data sources. Default is false.

For example, with this enabled, a request from a client carrying User-Agent: my-client/1.4 is forwarded with User-Agent: Grafana/13.0.0 my-client/1.4.

[analytics]

enabled

This option is also known as usage analytics. When false, this option disables the writers that write to the Grafana database and the associated features, such as dashboard and data source insights, presence indicators, and advanced dashboard search. The default value is true.

reporting_enabled

When enabled Grafana sends anonymous usage statistics to stats.grafana.org. Grafana doesn’t track IP addresses, only counters of running instances, versions, dashboards, and errors.

The anonymous usage statistics help inform the future development of Grafana. Counters are sent every 24 hours. Default value is true.

check_for_updates

Set to false to disable checking for new versions of Grafana in GitHub. When enabled, the check for a new version runs every ten minutes. It notifies, via the UI, when a new version is available. The check itself doesn’t cause automatic updates of the Grafana software, nor does it send any sensitive information.

check_for_plugin_updates

Set to false to disable checking for new versions of installed plugins from https://grafana.com. When enabled, the check for a new plugin runs every ten minutes. It notifies, via the UI, when a new plugin update exists. The check itself doesn’t cause any automatic updates of any plugins, nor does it send any sensitive information.

google_analytics_ua_id

If you want to track Grafana usage with Google Analytics specify your Universal Analytics ID here. By default this feature is disabled.

google_analytics_4_id

If you want to track Grafana usage with Google Analytics 4 specify your GA4 ID here. By default this feature is disabled.

google_tag_manager_id

Google Tag Manager ID, only enabled if you enter an ID here.

rudderstack_write_key

If you want to track Grafana usage via RudderStack specify your RudderStack Write Key here. The rudderstack_data_plane_url must also be provided for this feature to be enabled. By default this feature is disabled.

rudderstack_data_plane_url

RudderStack data plane URL to receive RudderStack events. You must also provide the rudderstack_write_key to enable this feature.

rudderstack_sdk_url

Optional. If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack SDK.

rudderstack_v3_sdk_url

Optional. This is mirroring the old configuration option, which will be deprecated. If rudderstack_sdk_url and rudderstack_v3_sdk_url are both set, the v3 SDK is loaded.

rudderstack_config_url

Optional. If tracking with RudderStack is enabled, you can provide a custom URL to load the RudderStack configuration.

rudderstack_integrations_url

Optional. If tracking with RudderStack is enabled, you can provide a custom URL to load the SDK for destinations running in device mode. This setting is only valid for RudderStack version 1.1 and higher.

application_insights_connection_string

If you want to track Grafana usage via Azure Application Insights, then specify your Application Insights connection string. Since the connection string contains semicolons, you need to wrap it in backticks (`). By default, tracking usage is disabled.

application_insights_endpoint_url

Optionally, use this option to override the default endpoint address for Application Insights data collecting. For details, refer to the Azure documentation.