Configure security on Grafana Labs

Configure database encryption

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

Configure database encryption

Grafana’s database contains secrets, which are used to query data sources, send alert notifications, and perform other functions within Grafana.

Grafana encrypts these secrets before they are written to the database, by using a symmetric-key encryption algorithm called Advanced Encryption Standard (AES). These secrets are signed using a secret key that you can change when you configure a new Grafana instance.

Note
Grafana v9.0 and newer use envelope encryption by default, which adds a layer of indirection to the encryption process that introduces an implicit breaking change for older versions of Grafana.

For further details about how to operate a Grafana instance with envelope encryption, see the Operational work section.

Note
In Grafana Enterprise, you can also encrypt secrets in AES-GCM (Galois/Counter Mode) instead of the default AES-CFB (Cipher FeedBack mode).

Envelope encryption

Note
Since Grafana v9.0, you can turn envelope encryption off by adding the feature toggle disableEnvelopeEncryption to your Grafana configuration.

Instead of encrypting all secrets with a single key, Grafana uses a set of keys called data encryption keys (DEKs) to encrypt them. These data encryption keys are themselves encrypted with a single key encryption key (KEK), configured through the secret_key attribute in your Grafana configuration or by Encrypting your database with a key from a key management service (KMS).

Implicit breaking change

Envelope encryption introduces an implicit breaking change to versions of Grafana prior to v9.0, because it changes how secrets stored in the Grafana database are encrypted. Grafana administrators can upgrade to Grafana v9.0 with no action required from the database encryption perspective, but must be extremely careful if they need to roll an upgrade back to Grafana v8.5 or earlier because secrets created or modified after upgrading to Grafana v9.0 can’t be decrypted by previous versions.

Grafana v8.5 implemented envelope encryption behind an optional feature toggle. Grafana administrators who need to downgrade to Grafana v8.5 can enable envelope encryption as a workaround by adding the feature toggle envelopeEncryption to the Grafana configuration.

Operational work

From the database encryption perspective, Grafana administrators can:

Re-encrypt secrets: re-encrypt secrets with envelope encryption and a fresh data key.
Roll back secrets: decrypt secrets encrypted with envelope encryption and re-encrypt them with legacy encryption.
Re-encrypt data keys: re-encrypt data keys with a fresh key encryption key and a KMS integration.
Rotate data keys: disable active data keys and stop using them for encryption in favor of a fresh one.

Re-encrypt secrets

You can re-encrypt secrets in order to:

Move already existing secrets’ encryption forward from legacy to envelope encryption.
Re-encrypt secrets after a data keys rotation.

To re-encrypt secrets, use the Grafana CLI by running the grafana cli admin secrets-migration re-encrypt command or the /encryption/reencrypt-secrets endpoint of the Grafana Admin API. It’s safe to run more than once, more recommended under maintenance mode.

Roll back secrets

You can roll back secrets encrypted with envelope encryption to legacy encryption. This might be necessary to downgrade to Grafana versions prior to v9.0 after an unsuccessful upgrade.

To roll back secrets, use the Grafana CLI by running the grafana cli admin secrets-migration rollback command or the /encryption/rollback-secrets endpoint of the Grafana Admin API. It’s safe to run more than once, more recommended under maintenance mode.

Re-encrypt data keys

You can re-encrypt data keys encrypted with a specific key encryption key (KEK). This allows you to either re-encrypt existing data keys with a new KEK version or to re-encrypt them with a completely different KEK.

To re-encrypt data keys, use the Grafana CLI by running the grafana cli admin secrets-migration re-encrypt-data-keys command or the /encryption/reencrypt-data-keys endpoint of the Grafana Admin API. It’s safe to run more than once, more recommended under maintenance mode.

Rotate data keys

You can rotate data keys to disable the active data key and therefore stop using them for encryption operations. For high-availability setups, you might need to wait until the data keys cache’s time-to-live (TTL) expires to ensure that all rotated data keys are no longer being used for encryption operations.

New data keys for encryption operations are generated on demand.

Note
Data key rotation does not implicitly re-encrypt secrets. Grafana will continue to use rotated data keys to decrypt secrets still encrypted with them. To completely stop using rotated data keys for both encryption and decryption, see secrets re-encryption.

To rotate data keys, use the /encryption/rotate-data-keys endpoint of the Grafana Admin API. It’s safe to call more than once, more recommended under maintenance mode.

Encrypting your database with a key from a key management service (KMS)

If you are using Grafana Enterprise, you can integrate with a key management service (KMS) provider, and change Grafana’s cryptographic mode of operation from AES-CFB to AES-GCM.

You can choose to encrypt secrets stored in the Grafana database using a key from a KMS, which is a secure central storage location that is designed to help you to create and manage cryptographic keys and control their use across many services. When you integrate with a KMS, Grafana does not directly store your encryption key. Instead, Grafana stores KMS credentials and the identifier of the key, which Grafana uses to encrypt the database.

Grafana integrates with the following key management services:

Changing your encryption mode to AES-GCM

Grafana encrypts secrets using Advanced Encryption Standard in Cipher FeedBack mode (AES-CFB). You might prefer to use AES in Galois/Counter Mode (AES-GCM) instead, to meet your company’s security requirements or in order to maintain consistency with other services.

To change your encryption mode, update the algorithm value in the [security.encryption] section of your Grafana configuration file. For further details, refer to Enterprise configuration.

Audit a Grafana instance

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

Audit a Grafana instance

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.

Note
To enable sending Grafana Cloud audit logs to your Grafana Cloud Logs instance, please file a support ticket. Note that standard ingest and retention rates apply for ingesting these audit logs.

Only API requests or UI actions that trigger an API request generate an audit log.

Note
Available in Grafana Enterprise and Grafana Cloud.

Audit logs

Audit logs are JSON objects representing user actions like:

Modifications to resources such as dashboards and data sources.
A user failing to log in.

Format

Audit logs contain the following fields. The fields followed by * are always available, the others depend on the type of action logged.

Field name	Type	Description
`timestamp`*	string	The date and time the request was made, in coordinated universal time (UTC) using the RFC3339 format.
`user`*	object	Information about the user that made the request. Either one of the `UserID` or `ApiKeyID` fields will contain content if `isAnonymous=false`.
`user.userId`	number	ID of the Grafana user that made the request.
`user.orgId`*	number	Current organization of the user that made the request.
`user.orgRole`	string	Current role of the user that made the request.
`user.name`	string	Name of the Grafana user that made the request.
`user.authTokenId`	number	ID of the user authentication token.
`user.apiKeyId`	number	ID of the Grafana API key used to make the request.
`user.isAnonymous`*	boolean	If an anonymous user made the request, `true`. Otherwise, `false`.
`action`*	string	The request action. For example, `create`, `update`, or `manage-permissions`.
`request`*	object	Information about the HTTP request.
`request.params`	object	Request’s path parameters.
`request.query`	object	Request’s query parameters.
`request.body`	string	Request’s body. Filled with `<non-marshalable format>` when it isn’t a valid JSON.
`result`*	object	Information about the HTTP response.
`result.statusType`	string	If the request action was successful, `success`. Otherwise, `failure`.
`result.statusCode`	number	HTTP status of the request.
`result.failureMessage`	string	HTTP error message.
`result.body`	string	Response body. Filled with `<non-marshalable format>` when it isn’t a valid JSON.
`resources`	array	Information about the resources that the request action affected. This field can be null for non-resource actions such as `login` or `logout`.
`resources[x].id`*	number	ID of the resource.
`resources[x].type`*	string	The type of the resource that was logged: `alert`, `alert-notification`, `annotation`, `api-key`, `auth-token`, `dashboard`, `datasource`, `folder`, `org`, `panel`, `playlist`, `report`, `team`, `user`, or `version`.
`requestUri`*	string	Request URI.
`ipAddress`*	string	IP address that the request was made from.
`userAgent`*	string	Agent through which the request was made.
`grafanaVersion`*	string	Current version of Grafana when this log is created.
`additionalData`	object	Additional information that can be provided about the request.

The additionalData field can contain the following information:

Field name	Action	Description
`loginUsername`	`login`	Login used in the Grafana authentication form.
`extUserInfo`	`login`	User information provided by the external system that was used to log in.
`authTokenCount`	`login`	Number of active authentication tokens for the user that logged in.
`terminationReason`	`logout`	The reason why the user logged out, such as a manual logout or a token expiring.
`billing_role`	`billing-information`	The billing role associated with the billing information being sent.

Recorded actions

The audit logs include records about the following categories of actions. Each action is distinguished by the action and resources[...].type fields in the JSON record.

For example, creating an API key produces an audit log like this:

{
  "action": "create",
  "resources": [
    {
      "id": 1,
      "type": "api-key"
    }
  ],
  "timestamp": "2021-11-12T22:12:36.144795692Z",
  "user": {
    "userId": 1,
    "orgId": 1,
    "orgRole": "Admin",
    "username": "admin",
    "isAnonymous": false,
    "authTokenId": 1
  },
  "request": {
    "body": "{\"name\":\"example\",\"role\":\"Viewer\",\"secondsToLive\":null}"
  },
  "result": {
    "statusType": "success",
    "statusCode": 200,
    "responseBody": "{\"id\":1,\"name\":\"example\"}"
  },
  "resources": [
    {
      "id": 1,
      "type": "api-key"
    }
  ],
  "requestUri": "/api/auth/keys",
  "ipAddress": "127.0.0.1:54652",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64; rv:94.0) Gecko/20100101 Firefox/94.0",
  "grafanaVersion": "8.3.0-pre"
}

Some actions can only be distinguished by their requestUri fields. For those actions, the relevant pattern of the requestUri field is given.

Note that almost all these recorded actions are actions that correspond to API requests or UI actions that trigger an API request. Therefore, the action {"action": "email", "resources": [{"type": "report"}]} corresponds to the action when the user requests a report’s preview to be sent through email, and not the scheduled ones.

Sessions

Action	Distinguishing fields
Log in	`{"action": "login-AUTH-MODULE"}` *
Log out **	`{"action": "logout"}`
Force logout for user	`{"action": "logout-user"}`
Remove user authentication token	`{"action": "revoke-auth-token", "resources": [{"type": "auth-token"}, {"type": "user"}]}`
Create API key	`{"action": "create", "resources": [{"type": "api-key"}]}`
Delete API key	`{"action": "delete", "resources": [{"type": "api-key"}]}`

* Where AUTH-MODULE is the name of the authentication module: grafana, saml, ldap, etc.
** Includes manual log out, token expired/revoked, and SAML Single Logout.

Service accounts

Action	Distinguishing fields
Create service account	`{"action": "create", "resources": [{"type": "service-account"}]}`
Update service account	`{"action": "update", "resources": [{"type": "service-account"}]}`
Delete service account	`{"action": "delete", "resources": [{"type": "service-account"}]}`
Create service account token	`{"action": "create", "resources": [{"type": "service-account"}, {"type": "service-account-token"}]}`
Delete service account token	`{"action": "delete", "resources": [{"type": "service-account"}, {"type": "service-account-token"}]}`
Hide API keys	`{"action": "hide-api-keys"}`
Migrate API keys	`{"action": "migrate-api-keys"}`
Migrate API key	`{"action": "migrate-api-keys"}, "resources": [{"type": "api-key"}]}`

Access control

Action	Distinguishing fields
Create role	`{"action": "create", "resources": [{"type": "role"}]}`
Update role	`{"action": "update", "resources": [{"type": "role"}]}`
Delete role	`{"action": "delete", "resources": [{"type": "role"}]}`
Assign built-in role	`{"action": "assign-builtin-role", "resources": [{"type": "role"}, {"type": "builtin-role"}]}`
Remove built-in role	`{"action": "remove-builtin-role", "resources": [{"type": "role"}, {"type": "builtin-role"}]}`
Grant team role	`{"action": "grant-team-role", "resources": [{"type": "team"}]}`
Set team roles	`{"action": "set-team-roles", "resources": [{"type": "team"}]}`
Revoke team role	`{"action": "revoke-team-role", "resources": [{"type": "role"}, {"type": "team"}]}`
Grant user role	`{"action": "grant-user-role", "resources": [{"type": "role"}, {"type": "user"}]}`
Set user roles	`{"action": "set-user-roles", "resources": [{"type": "user"}]}`
Revoke user role	`{"action": "revoke-user-role", "resources": [{"type": "role"}, {"type": "user"}]}`
Set user permissions on folder	`{"action": "set-user-permissions-on-folder", "resources": [{"type": "folder"}, {"type": "user"}]}`
Set team permissions on folder	`{"action": "set-team-permissions-on-folder", "resources": [{"type": "folder"}, {"type": "team"}]}`
Set basic role permissions on folder	`{"action": "set-basic-role-permissions-on-folder", "resources": [{"type": "folder"}, {"type": "builtin-role"}]}`
Set user permissions on dashboard	`{"action": "set-user-permissions-on-dashboards", "resources": [{"type": "dashboard"}, {"type": "user"}]}`
Set team permissions on dashboard	`{"action": "set-team-permissions-on-dashboards", "resources": [{"type": "dashboard"}, {"type": "team"}]}`
Set basic role permissions on dashboard	`{"action": "set-basic-role-permissions-on-dashboards", "resources": [{"type": "dashboard"}, {"type": "builtin-role"}]}`
Set user permissions on team	`{"action": "set-user-permissions-on-teams", "resources": [{"type": "teams"}, {"type": "user"}]}`
Set user permissions on service account	`{"action": "set-user-permissions-on-service-accounts", "resources": [{"type": "service-account"}, {"type": "user"}]}`
Set user permissions on datasource	`{"action": "set-user-permissions-on-data-sources", "resources": [{"type": "datasource"}, {"type": "user"}]}`
Set team permissions on datasource	`{"action": "set-team-permissions-on-data-sources", "resources": [{"type": "datasource"}, {"type": "team"}]}`
Set basic role permissions on datasource	`{"action": "set-basic-role-permissions-on-data-sources", "resources": [{"type": "datasource"}, {"type": "builtin-role"}]}`

User management

Action	Distinguishing fields
Create user	`{"action": "create", "resources": [{"type": "user"}]}`
Update user	`{"action": "update", "resources": [{"type": "user"}]}`
Delete user	`{"action": "delete", "resources": [{"type": "user"}]}`
Disable user	`{"action": "disable", "resources": [{"type": "user"}]}`
Enable user	`{"action": "enable", "resources": [{"type": "user"}]}`
Update password	`{"action": "update-password", "resources": [{"type": "user"}]}`
Send password reset email	`{"action": "send-reset-email"}`
Reset password	`{"action": "reset-password"}`
Update permissions	`{"action": "update-permissions", "resources": [{"type": "user"}]}`
Send signup email	`{"action": "signup-email"}`
Click signup link	`{"action": "signup"}`
Reload LDAP configuration	`{"action": "ldap-reload"}`
Get user in LDAP	`{"action": "ldap-search"}`
Sync user with LDAP	`{"action": "ldap-sync", "resources": [{"type": "user"}]`

Team and organization management

Action	Distinguishing fields
Add team	`{"action": "create", "requestUri": "/api/teams"}`
Update team	`{"action": "update", "requestUri": "/api/teams/TEAM-ID"}`*
Delete team	`{"action": "delete", "requestUri": "/api/teams/TEAM-ID"}`*
Add external group for team	`{"action": "create", "requestUri": "/api/teams/TEAM-ID/groups"}`*
Remove external group for team	`{"action": "delete", "requestUri": "/api/teams/TEAM-ID/groups/GROUP-ID"}`*
Add user to team	`{"action": "create", "resources": [{"type": "user"}, {"type": "team"}]}`
Update team member permissions	`{"action": "update", "resources": [{"type": "user"}, {"type": "team"}]}`
Remove user from team	`{"action": "delete", "resources": [{"type": "user"}, {"type": "team"}]}`
Create organization	`{"action": "create", "resources": [{"type": "org"}]}`
Update organization	`{"action": "update", "resources": [{"type": "org"}]}`
Delete organization	`{"action": "delete", "resources": [{"type": "org"}]}`
Add user to organization	`{"action": "create", "resources": [{"type": "org"}, {"type": "user"}]}`
Change user role in organization	`{"action": "update", "resources": [{"type": "user"}, {"type": "org"}]}`
Remove user from organization	`{"action": "delete", "resources": [{"type": "user"}, {"type": "org"}]}`
Invite external user to organization	`{"action": "org-invite", "resources": [{"type": "org"}, {"type": "user"}]}`
Revoke invitation	`{"action": "revoke-org-invite", "resources": [{"type": "org"}]}`

* Where TEAM-ID is the ID of the affected team, and GROUP-ID (if present) is the ID of the external group.

Folder and dashboard management

Action	Distinguishing fields
Create folder	`{"action": "create", "resources": [{"type": "folder"}]}`
Update folder	`{"action": "update", "resources": [{"type": "folder"}]}`
Update folder permissions	`{"action": "manage-permissions", "resources": [{"type": "folder"}]}`
Delete folder	`{"action": "delete", "resources": [{"type": "folder"}]}`
Create/update dashboard	`{"action": "create-update", "resources": [{"type": "dashboard"}]}`
Import dashboard	`{"action": "create", "resources": [{"type": "dashboard"}]}`
Update dashboard permissions	`{"action": "manage-permissions", "resources": [{"type": "dashboard"}]}`
Restore old dashboard version	`{"action": "restore", "resources": [{"type": "dashboard"}]}`
Delete dashboard	`{"action": "delete", "resources": [{"type": "dashboard"}]}`

Library elements management

Action	Distinguishing fields
Create library element	`{"action": "create", "resources": [{"type": "library-element"}]}`
Update library element	`{"action": "update", "resources": [{"type": "library-element"}]}`
Delete library element	`{"action": "delete", "resources": [{"type": "library-element"}]}`

Data sources management

Action	Distinguishing fields
Create datasource	`{"action": "create", "resources": [{"type": "datasource"}]}`
Update datasource	`{"action": "update", "resources": [{"type": "datasource"}]}`
Delete datasource	`{"action": "delete", "resources": [{"type": "datasource"}]}`
Enable permissions for datasource	`{"action": "enable-permissions", "resources": [{"type": "datasource"}]}`
Disable permissions for datasource	`{"action": "disable-permissions", "resources": [{"type": "datasource"}]}`
Grant datasource permission to role, team, or user	`{"action": "create", "resources": [{"type": "datasource"}, {"type": "dspermission"}]}`*
Remove datasource permission	`{"action": "delete", "resources": [{"type": "datasource"}, {"type": "dspermission"}]}`
Enable caching for datasource	`{"action": "enable-cache", "resources": [{"type": "datasource"}]}`
Disable caching for datasource	`{"action": "disable-cache", "resources": [{"type": "datasource"}]}`
Update datasource caching configuration	`{"action": "update", "resources": [{"type": "datasource"}]}`

* resources may also contain a third item with "type": set to "user" or "team".

Data source query

Action	Distinguishing fields
Query datasource	`{"action": "query", "resources": [{"type": "datasource"}]}`

Reporting

Action	Distinguishing fields
Create report	`{"action": "create", "resources": [{"type": "report"}, {"type": "dashboard"}]}`
Update report	`{"action": "update", "resources": [{"type": "report"}, {"type": "dashboard"}]}`
Delete report	`{"action": "delete", "resources": [{"type": "report"}]}`
Send report by email	`{"action": "email", "resources": [{"type": "report"}]}`
Update reporting settings	`{"action": "change-settings"}`

Annotations, playlists and snapshots management

Action	Distinguishing fields
Create annotation	`{"action": "create", "resources": [{"type": "annotation"}]}`
Create Graphite annotation	`{"action": "create-graphite", "resources": [{"type": "annotation"}]}`
Update annotation	`{"action": "update", "resources": [{"type": "annotation"}]}`
Patch annotation	`{"action": "patch", "resources": [{"type": "annotation"}]}`
Delete annotation	`{"action": "delete", "resources": [{"type": "annotation"}]}`
Delete all annotations from panel	`{"action": "mass-delete", "resources": [{"type": "dashboard"}, {"type": "panel"}]}`
Create playlist	`{"action": "create", "resources": [{"type": "playlist"}]}`
Update playlist	`{"action": "update", "resources": [{"type": "playlist"}]}`
Delete playlist	`{"action": "delete", "resources": [{"type": "playlist"}]}`
Create a snapshot	`{"action": "create", "resources": [{"type": "dashboard"}, {"type": "snapshot"}]}`
Delete a snapshot	`{"action": "delete", "resources": [{"type": "snapshot"}]}`
Delete a snapshot by delete key	`{"action": "delete", "resources": [{"type": "snapshot"}]}`

Provisioning

Action	Distinguishing fields
Reload provisioned dashboards	`{"action": "provisioning-dashboards"}`
Reload provisioned datasources	`{"action": "provisioning-datasources"}`
Reload provisioned plugins	`{"action": "provisioning-plugins"}`
Reload provisioned alerts	`{"action": "provisioning-alerts"}`
Reload provisioned access control	`{"action": "provisioning-accesscontrol"}`

Plugins management

Action	Distinguishing fields
Install plugin	`{"action": "install"}`
Uninstall plugin	`{"action": "uninstall"}`

Miscellaneous

Action	Distinguishing fields
Set licensing token	`{"action": "create", "requestUri": "/api/licensing/token"}`
Save billing information	`{"action": "billing-information"}`

Cloud migration management

Action	Distinguishing fields
Connect to a cloud instance	`{"action": "connect-instance"}`
Disconnect from a cloud instance	`{"action": "disconnect-instance"}`
Build a snapshot	`{"action": "build", "resources": [{"type": "snapshot"}]}`
Upload a snapshot	`{"action": "upload", "resources": [{"type": "snapshot"}]}`

Generic actions

In addition to the actions listed above, any HTTP request (POST, PATCH, PUT, and DELETE) against the API is recorded with one of the following generic actions.

Furthermore, you can also record GET requests. See below how to configure it.

Action	Distinguishing fields
POST request	`{"action": "post-action"}`
PATCH request	`{"action": "partial-update"}`
PUT request	`{"action": "update"}`
DELETE request	`{"action": "delete"}`
GET request	`{"action": "retrieve"}`

Configuration

Note
The auditing feature is disabled by default.

Audit logs can be saved into files, sent to a Loki instance or sent to the Grafana default logger. By default, only the file exporter is enabled. You can choose which exporter to use in the configuration file.

Options are file, loki, and logger. Use spaces to separate multiple modes, such as file loki.

By default, when a user creates or updates a dashboard, its content will not appear in the logs as it can significantly increase the size of your logs. If this is important information for you and you can handle the amount of data generated, then you can enable this option in the configuration.

[auditing]
# Enable the auditing feature
enabled = false
# List of enabled loggers
loggers = file
# Keep dashboard content in the logs (request or response fields); this can significantly increase the size of your logs.
log_dashboard_content = false
# Whether to record data source queries' request body. This can significantly increase the size of your logs. Enabled by default.
log_datasource_query_request_body = true
# Whether to record data source queries' response body. This can significantly increase the size of your logs. Enabled by default.
log_datasource_query_response_body = true
# Keep requests and responses body; this can significantly increase the size of your logs.
verbose = false
# Write an audit log for every status code.
# By default it only logs the following ones: 2XX, 3XX, 401, 403 and 500.
log_all_status_codes = false
# Maximum response body (in bytes) to be audited; 500KiB by default.
# May help reducing the memory footprint caused by auditing.
max_response_size_bytes = 512000

Each exporter has its own configuration fields.

File exporter

Audit logs are saved into files. You can configure the folder to use to save these files. Logs are rotated when the file size is exceeded and at the start of a new day.

[auditing.logs.file]
# Path to logs folder
path = data/log
# Maximum log files to keep
max_files = 5
# Max size in megabytes per log file
max_file_size_mb = 256

Loki exporter

Audit logs are sent to a Loki service, through HTTP or gRPC.

Note
The HTTP option for the Loki exporter is available only in Grafana Enterprise version 7.4 and later.

[auditing.logs.loki]
# Set the communication protocol to use with Loki (can be grpc or http)
type = grpc
# Set the address for writing logs to Loki
url = localhost:9095
# Defaults to true. If true, it establishes a secure connection to Loki
tls = true
# 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.
tenant_id =

If you have multiple Grafana instances sending logs to the same Loki service or if you are using Loki for non-audit logs, audit logs come with additional labels to help identifying them:

Label	Value
host	OS hostname on which the Grafana instance is running
grafana_instance	Application URL
kind	`auditing`

When basic authentication is needed to ingest logs in your Loki instance, you can specify credentials in the URL field. For example:

# Set the communication protocol to use with Loki (can be grpc or http)
type = http
# Set the address for writing logs to Loki
url = user:password@localhost:3000

Console exporter

Audit logs are sent to the Grafana default logger. The audit logs use the auditing.console logger and are logged on debug-level, learn how to enable debug logging in the log configuration section of the documentation. Accessing the audit logs in this way is not recommended for production use.

Export logs of usage insights

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

Export logs of usage insights

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team.

By exporting usage logs to Loki, 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. This configuration is done for you in Grafana Cloud, with provisioned dashboards. Read about them in the Grafana Cloud documentation.

Usage insights logs

Usage insights logs are JSON objects that represent certain user activities, such as:

A user opens a dashboard.
A query is sent to a data source.

Scope

A log is created every time:

A user opens a dashboard.
A query is sent to a data source in the dashboard view.
A query is performed via Explore.

Format

Logs of usage insights contain the following fields, where the fields followed by * are always available, and the others depend on the logged event:

Field name	Type	Description
`eventName`*	string	Type of the event, which can be either `data-request` or `dashboard-view`.
`folderName`*	string	Name of the dashboard folder.
`dashboardName`*	string	Name of the dashboard where the event happened.
`dashboardId`*	number	ID of the dashboard where the event happened.
`datasourceName`	string	Name of the data source that was queried.
`datasourceType`	string	Type of the data source that was queried. For example, `prometheus`, `elasticsearch`, or `loki`.
`datasourceId`	number	ID of the data source that was queried.
`panelId`	number	ID of the panel of the query.
`panelName`	string	Name of the panel of the query.
`error`	string	Error returned by the query.
`duration`	number	Duration of the query.
`source`	string	Source of the query. For example, `dashboard` or `explore`.
`orgId`*	number	ID of the user’s organization.
`orgName`*	string	Name of the user’s organization.
`timestamp`*	string	The date and time that the request was made, in Coordinated Universal Time (UTC) in RFC3339 format.
`tokenId`*	number	ID of the user’s authentication token.
`username`*	string	Name of the Grafana user that made the request.
`userId`*	number	ID of the Grafana user that made the request.
`totalQueries`*	number	Number of queries executed for the data request.
`cachedQueries`*	number	Number of fetched queries that came from the cache.

Configuration

To export your logs, enable the usage insights feature and configure an export location in the configuration file:

[usage_insights.export]
# Enable the usage insights export feature
enabled = true
# Storage type
storage = loki

The options for storage type are loki and logger (added in Grafana Enterprise 8.2).

If the storage type is set to loki you’ll need to also configure Grafana to export to a Loki ingestion server. To do this, you’ll need Loki installed. Refer to Install Loki for instructions on how to install Loki.

[usage_insights.export.storage.loki]
# Set the communication protocol to use with Loki (can be grpc or http)
type = grpc
# Set the address for writing logs to Loki (format must be host:port)
url = localhost:9095
# Defaults to true. If true, it establishes a secure connection to Loki
tls = true
# 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.
tenant_id =
# How long to wait before sending a request to Loki with the batch of events. Uses duration format: e.g. 5s, 1m
# 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_wait_duration = 5s
# How many events (in bytes) to accumulate in a single batch before sending it to Loki.
# 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.
batch_size_bytes = 102400 # 100KiB

Using logger will print usage insights to your Grafana server log. There is no option for configuring the logger storage type.

Visualize Loki usage insights in Grafana

If you export logs into Loki, you can build Grafana dashboards to understand your Grafana instance usage.

Add Loki as a data source. Refer to Grafana fundamentals tutorial.
Import one of the following dashboards:
- Usage insights
- Usage insights datasource details
Play with usage insights to understand them:
- In Explore, you can use the query {datasource="gdev-loki",kind="usage_insights"} to retrieve all logs related to your gdev-loki data source.
- In a dashboard, you can build a table panel with the query topk(10, sum by (error) (count_over_time({kind="usage_insights", datasource="gdev-prometheus"} | json | error != "" [$__interval]))) to display the 10 most common errors your users see using the gdev-prometheus data source.
- In a dashboard, you can build a graph panel with the queries sum by(host) (count_over_time({kind="usage_insights"} | json | eventName="data-request" | error != "" [$__interval])) and sum by(host) (count_over_time({kind="usage_insights"} | json | eventName="data-request" | error = "" [$__interval])) to show the evolution of the data request count over time. Using by (host) allows you to have more information for each Grafana server you have if you have set up Grafana for high availability.

Configure Grafana secret scanning and notifications

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

Configure Grafana secret scanning and notifications

With Grafana, you can use the GitHub Secret Scanning service to determine if your service account tokens have been leaked on GitHub.

When GitHub Secret Scanning detects a Grafana secret, its hash is stored in Grafana Labs’ secret scanning service.

Grafana instances, whether on-premises or on the cloud, can use this service to verify if a token generated by the instance has been made public. This verification is done by comparing the token’s hash with the exposed token’s hash.

If the service detects a leaked token, it immediately revokes it, making it useless, and logs the event.

Note
If the revoke option is disabled, the service only sends a notification to the configured webhook URL and logs the event. The token is not automatically revoked.

You can also configure the service to send an outgoing webhook notification to a webhook URL.

The notification includes a JSON payload that contains the following data:

{
  "alert_uid": "c9ce50a1-d66b-45e4-9b5d-175766cfc026",
  "link_to_upstream_details": <URL to token leak>,
  "message": "Token of type grafana_service_account_token with name
sa-the-toucans has been publicly exposed in <URL to token leak>.
Grafana has revoked this token",
  "state": "alerting",
  "title": "SecretScan Alert: Grafana Token leaked"
}

Note
Secret scanning is disabled by default. Outgoing connections are made once you enable it.

Before you begin

Ensure all your API keys have been migrated to service accounts. For more information about service account migration, refer to Migrate API keys to Grafana service accounts.

Configure secret scanning

Open the Grafana configuration file.
In the [secretscan] section, update the following parameters:

[secretscan]
# Enable secretscan feature
enabled = true

# Whether to revoke the token if a leak is detected or just send a notification
revoke = true

Save the configuration file and restart Grafana.

Configure outgoing webhook notifications

Create an oncall integration of the type Webhook and set up alerts. To learn how to create a Grafana OnCall integration, refer to Inbound Webhook integrations for Grafana OnCall.
Copy the webhook URL of the new integration.
Open the Grafana configuration file.
In the [secretscan] section, update the following parameters, replacing the URL with the webhook URL you copied in step 2.

[secretscan]
# URL to send a webhook payload in oncall format
oncall_url = https://example.url/integrations/v1/webhook/3a359nib9eweAd9lAAAETVdOx/

Save the configuration file and restart Grafana.

Configure request security

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

Configure request security

Request security allows you to limit requests from the Grafana server by targeting requests generated by users, such as data source metric queries and alert notifications.

This can be used to limit access to internal systems that the server Grafana runs on can access but that users of Grafana should not be able to access. This feature does not affect traffic from the Grafana users browser.

Note
Available in Grafana Enterprise and to users on select Grafana Cloud account plans. For pricing information, visit our pricing page or contact our sales team.

Note
Although request security works with backend plugins, you can create a backend plugin that bypasses this security.

IP and hostname blocking

You can limit requests based on a hostname, an IP address, or both.

Deny list

Grafana blocks any request to a hostname or IP address on the deny list.

Allow list

If there is at least one entry on the list, then any request to a hostname or IP address not on the list is denied.

For example:

[security.egress]
# A list of hostnames or IP addresses separated by spaces for which requests are blocked.
host_deny_list = supersecret.internal 192.168.1.10
# a list of hostnames or IP addresses separated by spaces for which requests will be allowed, all other requests will be blocked
host_allow_list = prometheus.internal

Drop headers and cookies

You can set a list of cookies or headers that are to be dropped from outgoing requests.

Example:

[security.egress]
# a list of headers that will be stripped from outgoing datasource and alerting requests
header_drop_list = user
# a list of cookies that will be stripped from outgoing datasource requests (case sensitive)
cookie_drop_list = session_id

Configure security hardening

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

Configure security hardening

Security hardening enables you to apply additional security, which can help stop certain vulnerabilities from being exploited by a malicious attacker.

Note
These settings are available in the grafana.ini configuration file. To apply changes to the configuration file, restart the Grafana server.

Additional security for cookies

If Grafana uses HTTPS, you can further secure the cookie that the system uses to authenticate access to the web UI. By applying additional security to the cookie, you might mitigate certain attacks that result from an attacker obtaining the cookie value.

Note
Grafana must use HTTPS for the following configurations to work properly.

Add a secure attribute to cookies

To provide mitigation against some MITM attacks, add the Secure attribute to the cookie that is used to authenticate users. This attribute forces users only to send the cookie over a valid HTTPS secure connection.

Example:

[security]
# Set to true if you host Grafana behind HTTPS. The default value is false.
cookie_secure = true

Add a SameSite attribute to cookies

To mitigate almost all CSRF-attacks, set the cookie_samesite option to strict. This setting prevents clients from sending the cookie in requests that are made cross-site, but only from the site that creates the cookie.

Example:

[security]
# set cookie SameSite attribute. defaults to `lax`. can be set to "lax", "strict", "none" and "disabled"
cookie_samesite = strict

Note
By setting the SameSite attribute to “strict,” only the user clicks within a Grafana instance work. The default option, “lax,” does not produce this behavior.

If you want to use OAuth/SAML for login, it is necessary to configure this attribute as lax.

You can further secure the cookie authentication by adding a Cookie Prefix. Cookies without a special prefix can be overwritten in a man-in-the-middle attack, even if the site uses HTTPS. A cookie prefix forces clients only to accept the cookie if certain criteria are met. Add a prefix to the current cookie name with either __Secure- or __Host- where the latter provides additional protection by only allowing the cookie to be created from the host that sent the Set-Cookie header.

Example:

[auth]
# Login cookie name
login_cookie_name = __Host-grafana_session

Security headers

Grafana includes a few additional headers that you can configure to help mitigate against certain attacks, such as XSS.

Add a Content Security Policy

A content security policy (CSP) is an HTTP response header that controls how the web browser handles content, such as allowing inline scripts to execute or loading images from certain domains. The default CSP template is already configured to provide sufficient protection against some attacks. This makes it more difficult for attackers to execute arbitrary JavaScript if such a vulnerability is present.

Example:

[security]
# Enable adding the Content-Security-Policy header to your requests.
# CSP enables you to control the resources the user agent can load and helps prevent XSS attacks.
content_security_policy = true

# Set the Content Security Policy template that is used when the Content-Security-Policy header is added to your requests.
# $NONCE in the template includes a random nonce.
# $ROOT_PATH is server.root_url without the protocol.
content_security_policy_template = """script-src 'self' 'unsafe-eval' 'unsafe-inline' 'strict-dynamic' $NONCE;object-src 'none';font-src 'self';style-src 'self' 'unsafe-inline' blob:;img-src * data:;base-uri 'self';connect-src 'self' grafana.com ws://$ROOT_PATH wss://$ROOT_PATH;manifest-src 'self';media-src 'none';form-action 'self';"""

Enable trusted types

Currently in development. Trusted types is an experimental Javascript API with limited browser support.

Trusted types reduce the risk of DOM XSS by enforcing developers to sanitize strings that are used in injection sinks, such as setting innerHTML on an element. Furthermore, when enabling trusted types, these injection sinks need to go through a policy that will sanitize, or leave the string intact and return it as “safe”. This provides some protection from client side injection vulnerabilities in third party libraries, such as jQuery, Angular and even third party plugins.

To enable trusted types in enforce mode, where injection sinks are automatically sanitized:

Enable content_security_policy in the configuration.
Add require-trusted-types-for 'script' to the content_security_policy_template in the configuration.

To enable trusted types in report mode, where inputs that have not been sanitized with trusted types will be logged to the console:

Enable content_security_policy_report_only in the configuration.
Add require-trusted-types-for 'script' to the content_security_policy_report_only_template in the configuration.

As this is a feature currently in development, things may break. If they do, or if you have any other feedback, feel free to open an issue.

Additional security hardening

The Grafana server has several built-in security features that you can opt-in to enhance security. This section describes additional techniques you can use to harden security.

Hide the version number

If set to true, the Grafana server hides the running version number for unauthenticated users. Version numbers might reveal if you are running an outdated and vulnerable version of Grafana.

Example:

[auth.anonymous]
# mask the Grafana version number for unauthenticated users
hide_version = true

Enable auth for metrics

By default, metrics from Grafana itself can be accessed without authentication. This can lead to information leakage.

Example:

[metrics]
# If both are set, basic auth will be required for the metrics endpoints
basic_auth_username =
basic_auth_password =

Enforce domain verification

If set to true, the Grafana server redirects requests that have a Host-header value that is mismatched to the actual domain. This might help to mitigate some DNS rebinding attacks.

Example:

[server]
# Redirect to correct domain if host header does not match domain
# Prevents DNS rebinding attacks
enforce_domain = true

Configure security on Grafana Labs

Configure database encryption

Configure database encryption

Envelope encryption

Implicit breaking change

Operational work

Re-encrypt secrets

Roll back secrets

Re-encrypt data keys

Rotate data keys

Encrypting your database with a key from a key management service (KMS)

Changing your encryption mode to AES-GCM

Audit a Grafana instance

Audit a Grafana instance

Audit logs

Format

Recorded actions

Sessions

Service accounts

Access control

User management

Team and organization management

Folder and dashboard management

Library elements management

Data sources management

Data source query

Reporting

Annotations, playlists and snapshots management

Provisioning

Plugins management

Miscellaneous

Cloud migration management

Generic actions

Configuration

File exporter

Loki exporter

Console exporter

Export logs of usage insights

Export logs of usage insights

Usage insights logs

Scope

Format

Configuration

Visualize Loki usage insights in Grafana

Configure Grafana secret scanning and notifications

Configure Grafana secret scanning and notifications

Before you begin

Configure secret scanning

Configure outgoing webhook notifications

Configure request security

Configure request security

IP and hostname blocking

Deny list

Allow list

Drop headers and cookies

Configure security hardening

Configure security hardening

Additional security for cookies

Add a secure attribute to cookies

Add a SameSite attribute to cookies

Add a prefix to cookie names

Security headers

Add a Content Security Policy

Enable trusted types

Additional security hardening

Hide the version number

Enable auth for metrics

Enforce domain verification