Docs: Grafana Enterprise auditing feature (#28356)

* Docs: add auditing documentation

* Docs: improve wording

* Update docs/sources/enterprise/_index.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update docs/sources/enterprise/auditing.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Docs: apply PR feedback

* Docs: add auditing in menu

* Docs: auditing PR feedback

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/enterprise/_index.md

@@ -53,6 +53,7 @@ With Grafana Enterprise, you get access to new features, including:
 - [White labeling]({{< relref "white-labeling.md" >}}) to customize Grafana from the brand and logo to the footer links.
 - [Usage insights]({{< relref "usage-insights.md" >}}) to understand how your Grafana instance is used.
 - [Vault integration]({{< relref "vault.md" >}}) to manage your configuration or provisioning secrets with Vault.
+- [Auditing]({{< relref "auditing.md" >}}) tracks important changes to your Grafana instance to help you manage and mitigate suspicious activity and meet compliance requirements.
 
 ## Enterprise plugins
 

docs/sources/enterprise/auditing.md

++++
+title = "Auditing"
+description = "Auditing"
+keywords = ["grafana", "auditing", "audit", "logs"]
+type = "docs"
+[menu.docs]
+parent = "enterprise"
+weight = 700
++++
+
+# Auditing
+
+> **Note:** Only available in Grafana Enterprise v7.3+.
+
+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.
+
+## Audit logs
+
+Audit logs are JSON objects representing user actions like:
+- Modifications ro 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 depends 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](https://tools.ietf.org/html/rfc3339#section-5.6) format. |
+| `user`\* | object | Information about the user that made the request. At least one of the `UserID` / `ApiKeyID` fields will not be empty 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.apiKeyId` | number | ID of the Grafana API key used to make the request. |
+| `user.isAnonymous`\* | boolean | `true` if an anonymous user made the request, `false` otherwise. |
+| `action`\* | string | The request action (eg. `create`, `update`, `manage-permissions`). |
+| `request`\* | object | Information about the HTTP request. |
+| `request.params` | object | Request path parameters. |
+| `request.query` | object | Request query parameters. |
+| `request.body` | string | Request body. |
+| `result`\* | object | Information about the HTTP response. |
+| `result.statusType`\* | string | `success` if the request action was successful, `failure` otherwise. |
+| `result.statusCode` | number | HTTP status of the request. |
+| `result.failureMessage` | string | HTTP error message. |
+| `result.body` | string | Response body. |
+| `resources` | array | Information about the resources that the request action impacted. Can be null for non-resource actions like `login` and `logout`. |
+| `resources[x].id`\* | number | ID of the resource. |
+| `resources[x].type`\* | string | Type of the resource (logged resources are: `alert`, `alert-notification`, `annotation`, `api-key`, `auth-token`, `dashboard`, `datasource`, `folder`, `org`, `panel`, `playlist`, `report`, `team`, `user`, `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 | Grafana current version when this log is created. |
+| `additionalData` | object | Provide additional information on the request. For now, it's only used in `login` actions to log external user information if an external system was used to log in. |
+
+### Recorded actions
+
+The audit logs include records about the following categories of actions:
+
+**Sessions**
+
+- Log in.
+- Log out.
+- Revoke a user authentication token.
+- Create or delete an API key.
+
+**User management**
+
+- Create, update, or delete a user.
+- Enable or disable a user.
+- Manage user role and permissions.
+- LDAP sync or information access.
+
+**Team and organization management**
+
+- Create, update, or delete a team or organization.
+- Add or remove a member of a team or organization.
+- Manage organization members roles.
+- Manage team members permissions.
+- Invite an external member to an organization.
+- Revoke a pending invitation to an organization.
+- Add or remove an external group to sync with a team.
+
+**Folder and dashboard management**
+
+- Create, update, or delete a folder.
+- Manage folder permissions.
+- Create, import, update, or delete a dashboard.
+- Restore an old dashboard version.
+- Manage dashboard permissions.
+
+**Data sources management**
+
+- Create, update, or delete a data source.
+- Manage data source permissions.
+
+**Alerts and notification channels management**
+
+- Create, update, or delete a notification channel.
+- Test an alert or a notification channel.
+- Pause an alert.
+
+**Reporting**
+
+- Create, update, or delete a report.
+- Update reporting settings.
+- Send reporting email.
+
+**Annotations, playlists and snapshots management**
+
+- Create, update, or delete an annotation.
+- Create, update, or delete a playlist.
+- Create or delete a snapshot.
+
+## 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]({{< relref "../administration/configuration.md" >}}).
+
+Options are `file`, `loki`, and `console`. Use spaces to separate multiple modes, such as `file loki`.
+
+By default, when a user create or update 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.
+
+```ini
+[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
+```
+
+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
+[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](/oss/loki/) service.
+
+```ini
+[auditing.logs.loki]
+# Set the URL for writing logs to Loki
+url = localhost:9095
+# Defaults to true. If true, it establishes a secure connection to Loki
+tls = true
+```
+
+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:
+
+- **host** - OS hostname on which the Grafana instance is running.
+- **grafana_instance** - Application URL.
+- **kind** - `auditing`
+
+### 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]({{< relref "../administration/configuration.md#log" >}}) section of the documentation. Accessing the audit logs in this way is not recommended for production use.

docs/sources/enterprise/enterprise-configuration.md

@@ -101,6 +101,46 @@ Maximum number of concurrent calls to the rendering service.
 
 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.
 
+## [auditing]
+
+[Auditing]({{< relref "auditing.md" >}}) 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.
+
+## [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.
+
 ## [auth.saml]
 
 ### enabled

docs/sources/enterprise/license-expiration.md

@@ -17,10 +17,12 @@ If your license has expired most of Grafana keeps working as normal. Some enterp
 ## Update your license
 
 1. Locate your current `license.jwt` file. In a standard installation it is stored inside Grafana's data directory, which on a typical Linux installation is in `/var/lib/grafana/data`. This location might be overridden in the ini file [Configuration](https://grafana.com/docs/grafana/latest/administration/configuration/).
+
    ```ini
    [enterprise]
    license_path = /path/to/your/license.jwt
    ```
+
    The configuration file's location may also be overridden by the `GF_ENTERPRISE_LICENSE_PATH` environment variable.
 
 1. Log in to your [Grafana Cloud Account](https://grafana.com/login) and make sure you're in the correct organization in the dropdown at the top of the page.
@@ -65,3 +67,7 @@ All the usage insights features are turned off, meaning that you won't be able t
 ### Vault integration
 
 Vault integration is not affected by an expired license.
+
+### Auditing
+
+Auditing is not affected by an expired license.

docs/sources/menu.yaml

@@ -407,6 +407,8 @@
       link: /enterprise/
     - name: Activate license
       link: /enterprise/activate-license/
+    - name: Auditing
+      link: /enterprise/auditing/
     - name: Configuration
       link: /enterprise/enterprise-configuration/
     - name: Data source permissions

public/app/features/admin/UpgradePage.tsx

@@ -129,6 +129,7 @@ const FeatureListing: React.FC = () => {
       <Item title="Enhanced LDAP Integration" />
       <Item title="Team Sync">LDAP, GitHub OAuth, Auth Proxy, Okta</Item>
       <Item title="White labeling" />
+      <Item title="Auditing" />
       <Item title="Grafana usage insights">
         <List nested={true}>
           <Item title="Sort dashboards by popularity in search" />