This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Set up Configure security Audit a Grafana instance

Audit a Grafana instance

Auditing allows you to track important changes to your Grafana instance. Depending on your deployment, you can send audit logs to a file, a Loki-compatible endpoint, or the Grafana default logger.

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

• Grafana Enterprise supports all three exporters: file, Loki, and console.
• Grafana Cloud uses the Loki exporter. To enable audit logs for your Grafana Cloud instance, file a support ticket. Standard ingest and retention rates apply.

Understand 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.

Review the audit log format

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

The additionalData field can contain the following information:

Identify 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:

JSON Copy

{
  "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.

Almost all recorded actions correspond to API requests or UI actions that trigger an API request. For example, the action {"action": "email", "resources": [{"type": "report"}]} corresponds to a user-initiated email preview of a report, not a scheduled send.

Sessions

* 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

Access control

User management

Team and organization management

* 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

Library elements management

Data sources management

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

Data source query

Reporting

Annotations, playlists and snapshots management

Provisioning

Plugins management

Miscellaneous

Cloud migration management

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.

You can also record GET requests. Refer to Configure audit logging to enable this.

Configure audit logging

Audit logs can be saved into files, sent to a Loki-compatible endpoint, or sent to the Grafana default logger. 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.

Not all exporters are available in every deployment:

By default, dashboard content doesn’t appear in audit logs because it can significantly increase log size. To include dashboard content, enable the log_dashboard_content option.

Data source query request and response bodies are also excluded by default. Enabling log_datasource_query_request_body or log_datasource_query_response_body significantly increases log volume and may expose sensitive data such as query parameters, credentials, or personally identifiable information.

ini Copy

[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. Disabled by default.
log_datasource_query_request_body = false
# Whether to record data source queries' response body. This can significantly increase the size of your logs. Disabled by default.
log_datasource_query_response_body = false
# 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.

ini Copy

[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-compatible endpoint through HTTP or gRPC. You can use this exporter to send logs to Grafana Cloud Logs, a self-hosted Loki instance, or any other service that accepts the Loki push API.

ini Copy

[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 =
# Only available for the HTTP client. Disabled by default.
# How long to wait before sending a request to Loki with the batch of events. Uses duration format, for example, 5s, 1m
# Whichever threshold is hit first between `batch_wait_duration` and `batch_size_bytes` triggers the batch to be sent to Loki.
# If the wait duration is very long and the `batch_size_bytes` is very high, events might take a long time to be sent.
# To enable batching, you must also set the `batch_size_bytes` configuration option.
batch_wait_duration =
# Only available for the HTTP client. Disabled by default.
# How many events, in bytes, to accumulate in a single batch before sending it to Loki.
# Whichever threshold is hit first between `batch_wait_duration` and `batch_size_bytes` triggers the batch to be sent to Loki.
# If you want to always wait for the `batch_wait_duration`, set `batch_size_bytes` to a very high number.
# To enable batching, you must also set the `batch_wait_duration` configuration option.
batch_size_bytes =

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

If your Loki instance requires basic authentication, specify credentials in the URL field. For example:

ini Copy

# 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. To learn how to enable debug logging, refer to the log configuration section. Accessing the audit logs in this way isn’t recommended for production use.