---
title: "Set up self-managed MySQL | Database Observability documentation"
description: "Set up Database Observability for MySQL using Grafana Alloy and send telemetry to Grafana Cloud."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Set up self-managed MySQL

Set up Database Observability with Grafana Cloud to collect telemetry from MySQL using Grafana Alloy. You configure your database and Alloy to forward telemetry to Grafana Cloud.

If you already use the MySQL integration, Database Observability extends it with query-level telemetry collected by the `database_observability.mysql` Alloy component.

## What you’ll achieve

In this article, you:

- Configure MySQL for monitoring.
- Configure Grafana Alloy with the Database Observability components.
- Forward telemetry to Grafana Cloud.
- Verify that telemetry appears in Database Observability.

## Setup steps

Setting up Database Observability for self-managed MySQL has three steps:

1. [**Set up your database**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#set-up-your-database): Prepare MySQL so Alloy can collect from it.
2. [**Configure Grafana Alloy**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#configure-grafana-alloy): Configure how Alloy collects telemetry and sends it to Grafana Cloud. Self-managed MySQL supports a few methods to choose from.
3. [**Verify telemetry in Grafana Cloud**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#verify-telemetry-in-grafana-cloud): Check telemetry status and confirm that query metrics appear in Database Observability.

## Before you begin

To complete this setup, you need:

- A self-managed MySQL 8.0 or later database.
- Permission to modify your MySQL configuration.
- Permission to restart MySQL if configuration changes require it.
- A MySQL admin user that can create users and grant privileges.
- A planned [Grafana Alloy](https://grafana.com/docs/grafana-cloud/send-data/alloy/) deployment location with network access to the MySQL host.

Estimated setup time: 20-40 minutes, excluding any required maintenance window for restarting MySQL.

> Note
> 
> Alloy should connect directly to the database host. Avoid connecting Alloy to the database through a load balancer or connection pooler as it would limit Alloy’s ability to collect accurate telemetry.

## Set up your database

In this step, you’ll prepare MySQL for monitoring by enabling Performance Schema, creating a monitoring user, and granting the permissions Database Observability needs.

Complete this before configuring Alloy. Without it, Alloy can connect to your database, but it won’t be able to collect the telemetry required for Database Observability.

### Configure MySQL settings

Enable Performance Schema and related query capture settings in your MySQL configuration. How you configure these values depends on your MySQL deployment and operating system. If you change a startup-only variable, restart MySQL before continuing.

#### Required settings

Expand table

| Setting                                  | Value  | Notes                         |
|------------------------------------------|--------|-------------------------------|
| `performance_schema`                     | `ON`   | Requires restart when changed |
| `max_digest_length`                      | `4096` | Requires restart when changed |
| `performance_schema_max_digest_length`   | `4096` | Requires restart when changed |
| `performance_schema_max_sql_text_length` | `4096` | Requires restart when changed |

#### Update MySQL configuration

Add or update these settings in your MySQL server configuration file, for example, `my.cnf` or `mysqld.cnf`:

ini ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```ini
[mysqld]
performance-schema=ON
max-digest-length=4096
performance-schema-max-digest-length=4096
performance-schema-max-sql-text-length=4096
```

### Create a monitoring user and grant required privileges

Create the `db-o11y` user and grant base privileges:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
CREATE USER 'db-o11y'@'%' IDENTIFIED BY '<DB_O11Y_PASSWORD>';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'db-o11y'@'%';
GRANT SELECT ON performance_schema.* TO 'db-o11y'@'%';
```

Replace *&lt;DB\_O11Y\_PASSWORD&gt;* with a secure password for the `db-o11y` MySQL user.

Alloy must connect as this same user. If you use a name other than `db-o11y`, replace it in every later step, including the disable-tracking SQL.

#### Grant object privileges

Grant access to specific schemas when you want detailed information:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
GRANT SELECT, SHOW VIEW ON <SCHEMA_NAME>.* TO 'db-o11y'@'%';
```

Replace *&lt;SCHEMA\_NAME&gt;* with the name of the schema you want to monitor.

Alternatively, if you’re unsure which specific schemas need access, grant broader read access to all schemas:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
GRANT SELECT, SHOW VIEW ON *.* TO 'db-o11y'@'%';
```

### Enable Performance Schema consumers

Database Observability uses `Performance Schema` consumers to collect CPU time, query samples, and wait events. These consumers must be enabled before Alloy can collect complete query telemetry.

Choose one of the following:

#### Option 1: Let Alloy manage consumers automatically (recommended)

Use this method if you want to prepare the database so Alloy can automatically re-enable the required `Performance Schema` consumers after your database restarts.

To prepare the database for this method, grant the monitoring user permission to update `Performance Schema` consumers:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
GRANT UPDATE ON performance_schema.setup_consumers TO 'db-o11y'@'%';
```

Later, when you configure Alloy, enable automatic `Performance Schema` consumer management in the Alloy configuration.

#### Option 2: Enable consumers manually

Use this method if you don’t want Alloy to modify `Performance Schema` settings.

Check whether the required consumers are enabled:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SELECT NAME, ENABLED
FROM performance_schema.setup_consumers
WHERE NAME IN (
  'events_statements_cpu',
  'events_waits_current',
  'events_waits_history'
);
```

Enable any disabled consumers:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
UPDATE performance_schema.setup_consumers
SET ENABLED = 'YES'
WHERE NAME IN (
  'events_statements_cpu',
  'events_waits_current',
  'events_waits_history'
);
```

These consumers disable when your database restarts. If you use this method, re-enable them after each restart.

### Disable tracking of monitoring user queries

Database Observability uses `Performance Schema` to collect query telemetry. If `Performance Schema` tracks the `db-o11y` monitoring user, Alloy’s own collection queries can appear in Database Observability as database workload.

Choose one of the following:

#### Option 1: Let Alloy manage actor tracking automatically (recommended)

Use this method if you want to prepare the database so Alloy can automatically disable tracking for the monitoring user after MySQL restarts.

To prepare the database for this method, grant the monitoring user permission to update `Performance Schema` actors:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
GRANT INSERT, UPDATE ON performance_schema.setup_actors TO 'db-o11y'@'%';
```

Later, when you configure Alloy, enable automatic `Performance Schema` actor management in the Alloy configuration.

#### Option 2: Disable tracking manually

Use this method if you don’t want Alloy to modify `Performance Schema` actor settings.

Check whether a `setup_actors` row already exists for the monitoring user:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SELECT *
FROM performance_schema.setup_actors
WHERE USER = 'db-o11y';
```

If no row is returned, add one:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
INSERT INTO performance_schema.setup_actors
  (HOST, USER, ROLE, ENABLED, HISTORY)
VALUES
  ('%', 'db-o11y', '%', 'NO', 'NO');
```

If a row exists, disable instrumentation and history for it:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
UPDATE performance_schema.setup_actors
SET ENABLED = 'NO', HISTORY = 'NO'
WHERE USER = 'db-o11y';
```

`setup_actors` settings reset when MySQL restarts. If you use this method, re-apply this configuration after each restart.

> Tip
> 
> If you disable tracking or enable consumers manually on self-managed MySQL, you can automate re-applying them after each restart with MySQL’s `init_file` startup option.

### Verify user privileges

Verify that the user exists and has the expected privileges:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SHOW GRANTS FOR 'db-o11y'@'%';
```

Confirm the output includes grants equivalent to:

- `PROCESS, REPLICATION CLIENT ON *.*`
- `SELECT ON performance_schema.*`
- `SELECT, SHOW VIEW ON <SCHEMA_NAME>.*`, or `SELECT, SHOW VIEW ON *.*` if you granted broader read access
- `UPDATE ON performance_schema.setup_consumers`, if you chose Alloy-managed `Performance Schema` consumers
- `INSERT, UPDATE ON performance_schema.setup_actors`, if you chose Alloy-managed `Performance Schema` actor tracking

### Verify MySQL settings

Verify that the settings were applied correctly:

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SHOW VARIABLES LIKE 'performance_schema';
```

Expected result: Value is `ON`.

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SHOW VARIABLES LIKE 'performance_schema_max_digest_length';
```

Expected result: Value is `4096`.

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SHOW VARIABLES LIKE 'performance_schema_max_sql_text_length';
```

Expected result: Value is `4096`.

SQL ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```sql
SHOW VARIABLES LIKE 'max_digest_length';
```

Expected result: Value is `4096`.

### Database setup checkpoint

Continue to Alloy configuration only after these conditions are true:

- `performance_schema` is `ON`.
- `performance_schema_max_digest_length`, `performance_schema_max_sql_text_length`, and `max_digest_length` are set to `4096`.
- `SHOW GRANTS FOR 'db-o11y'@'%';` includes the required monitoring and object privileges, plus the optional `Performance Schema` grants for any settings you chose Alloy to manage.
- The required `Performance Schema` consumers are enabled, or Alloy has privileges to manage them automatically.
- Tracking is disabled for the `db-o11y` monitoring user, or Alloy has privileges to manage actor tracking automatically.
- The `db-o11y` monitoring user can connect from the network where Alloy will run.
- Any configuration changes that required a restart have been applied and the MySQL restart is complete.

After these checks pass, MySQL is ready for Database Observability. Next, configure Alloy so it can collect telemetry from the database and send it to Grafana Cloud.

## Configure Grafana Alloy

After you set up your database, choose how to configure Alloy.

**Pick one:**

1. [**Configuration page (recommended)**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#option-1-configure-alloy-from-the-database-observability-configuration-page-recommended): Database Observability generates the Alloy configuration for you. Choose **Fleet Management** or **Manual configuration**, then select **Standalone Alloy** or **Kubernetes Monitoring Helm chart**. Best for most teams.
2. [**Kubernetes Monitoring Helm chart**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#option-2-configure-the-grafana-kubernetes-monitoring-helm-chart-manually): Set `databaseObservability.enabled` in your `values.yaml` yourself.
3. [**Custom configuration file (advanced)**](https://grafana.com/docs/grafana-cloud/observe-and-act/monitor-infrastructure/database-observability/set-up/mysql/mysql/#option-3-write-a-custom-alloy-configuration-file-advanced): Write the Alloy configuration yourself. Best for full control, custom components or relabeling, or environments the other paths don’t cover.

### Make sure you’re on a supported Alloy version

Alloy `1.17.0` or later is required for Database Observability. Find the latest stable version on [Docker Hub](https://hub.docker.com/r/grafana/alloy/tags). To update, refer to the [Alloy release notes](https://github.com/grafana/alloy/releases).

> Note
> 
> Grafana Alloy is an open source collector that sends your data to Grafana Cloud. Database Observability needs it to collect metrics and query telemetry from your database.
> 
> If you don’t have it installed, go to **Connections &gt; Collector Setup** in Grafana Cloud, open the **Install** tab, and choose **Alloy**. For more detail, refer to [Get started with Fleet Management and Grafana Alloy](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/get-started/alloy/).

### Option 1: Configure Alloy from the Database Observability Configuration page (recommended)

Start here for most deployments. The Configuration page (**Configuration** &gt; **Setup**) generates the configuration for you.

Choose how to manage the configuration:

- **Fleet Management**: Grafana Cloud applies and manages the configuration on enrolled Alloy collectors. Refer to [Introduction to Fleet Management](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/introduction/).
- **Manual configuration**: Generate the configuration and deploy it yourself with your own tools.

Then choose where Alloy runs: **Standalone Alloy** or **Kubernetes Monitoring Helm chart**. Both platforms support Fleet Management and manual configuration. For manual configuration, the wizard generates an Alloy configuration file for standalone Alloy or Helm values for Kubernetes.

To start the guided setup flow:

1. Open **Database Observability** in Grafana Cloud.
2. Go to **Configuration**.
3. Open **Setup**.
4. Click **Add database**.
5. Select **MySQL** as the database engine and **Self-managed or other** as the hosting option.
6. Choose **Fleet Management** or **Manual configuration**, then select **Standalone Alloy** or **Kubernetes Monitoring Helm chart**.

For an overview of setup methods and what appears in the **Setup** tab, refer to [Configure Alloy from the Configuration page](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/configure/fleet-management-integration/).

### Option 2: Configure the Grafana Kubernetes Monitoring Helm chart manually

Use this method to write the Kubernetes Monitoring Helm chart values yourself instead of generating them from the Configuration page.

Extend your `values.yaml` and set `databaseObservability.enabled` to `true` within the MySQL integration.

> Tip
> 
> If you chose Alloy-managed Performance Schema consumers or actor tracking during database setup, add the optional management values shown after the main example.

YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
integrations:
  collector: alloy-singleton
  mysql:
    instances:
      - name: <INSTANCE_NAME>
        jobLabel: integrations/db-o11y
        exporter:
          enabled: true
          collectors:
            perfSchemaEventsStatements:
              enabled: true
          dataSource:
            host: <DB_HOST>
            auth:
              usernameKey: <DB_USERNAME_SECRET_KEY>
              passwordKey: <DB_PASSWORD_SECRET_KEY>
        databaseObservability:
          enabled: true
        secret:
          create: false
          name: <INSTANCE_NAME>
          namespace: mysql
        logs:
          enabled: true
          labelSelectors:
            app.kubernetes.io/instance: <INSTANCE_NAME>
```

Replace the placeholders:

- `INSTANCE_NAME`: Name for this database instance in Kubernetes.
- `DB_HOST`: Hostname or IP address of the database.
- `DB_USERNAME_SECRET_KEY`: Kubernetes secret key that holds the database username, for example, `username`. The value must be the monitoring user you created and granted privileges to, for example, `db-o11y`.
- `DB_PASSWORD_SECRET_KEY`: Kubernetes secret key containing database password.

To let Alloy keep the required Performance Schema consumers enabled and disable tracking of the monitoring user automatically, add these values to the same `databaseObservability` block:

YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
        databaseObservability:
          # ...
          allowUpdatePerformanceSchemaSettings: true
          collectors:
            querySamples:
              autoEnableSetupConsumers: true
            setupActors:
              autoUpdateSetupActors: true
```

To see the full set of values, refer to the k8s-monitoring Helm chart [documentation](https://github.com/grafana/k8s-monitoring-helm/blob/main/charts/k8s-monitoring/charts/feature-integrations/docs/integrations/mysql.md#database-observability) or the [example configuration](https://github.com/grafana/k8s-monitoring-helm/tree/main/charts/k8s-monitoring/docs/examples/features/database-observability/mysql).

### Option 3: Write a custom Alloy configuration file (advanced)

Use this method to write the Alloy configuration yourself instead of generating it from the Configuration page.

#### Add the MySQL configuration blocks

Add these blocks to Alloy. Replace *&lt;DB\_NAME&gt;*. Create a `local.file` with the data source name string, for example, `<DB_O11Y_USER>:<DB_O11Y_PASSWORD>@tcp(<DB_HOST>:<DB_PORT>)/`.

Use the configuration for the version of Alloy you run:

Alloy 1.22.0 or laterAlloy 1.17.0 to 1.21.3

Alloy 1.22.0 or later Alloy 1.17.0 to 1.21.3

With Alloy 1.22.0 and later, `database_observability.mysql` runs the exporter itself, so you don’t add a `prometheus.exporter.mysql` component or set `targets`. The exporter uses the component’s `exclude_schemas`, whose defaults already cover the system schemas of the managed database services.

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file "mysql_secret_<DB_NAME>" {
  filename  = "/var/lib/alloy/mysql_secret_<DB_NAME>"
  is_secret = true
}

database_observability.mysql "mysql_<DB_NAME>" {
  data_source_name = local.file.mysql_secret_<DB_NAME>.content
  forward_to       = [loki.relabel.database_observability_mysql_<DB_NAME>.receiver]

  // OPTIONAL: enable these settings if you chose Alloy-managed Performance
  // Schema consumers or actor tracking during database setup.
  allow_update_performance_schema_settings = true

  // Requires UPDATE on performance_schema.setup_consumers.
  query_samples {
    auto_enable_setup_consumers = true
  }

  // Requires INSERT and UPDATE on performance_schema.setup_actors.
  setup_actors {
    auto_update_setup_actors = true
  }

  // OPTIONAL: provide additional information specific to the cloud provider
  // that hosts the database to enable infrastructure observability features.
  // For Azure and Google Cloud SQL examples, refer to the platform setup guides.
  cloud_provider {
    aws {
      arn = "<AWS_RDS_DB_ARN>"
    }
  }
}

loki.relabel "database_observability_mysql_<DB_NAME>" {
  forward_to = [loki.write.grafana_cloud_loki.receiver]

  // OPTIONAL: add any additional relabeling rules
  // (must be consistent with rules in "discovery.relabel")
  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
  rule {
    target_label = "<CUSTOM_LABEL_1>"
    replacement  = "<CUSTOM_VALUE_1>"
  }
}

discovery.relabel "database_observability_mysql_<DB_NAME>" {
  targets = database_observability.mysql.mysql_<DB_NAME>.targets

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }

  // OPTIONAL: add any additional relabeling rules
  // (must be consistent with rules in "loki.relabel")
  // OPTIONAL: relabel `instance` to `dsn` before overwriting `instance`;
  // the `dsn` label is used in the integration with the knowledge graph
  rule {
    source_labels = ["instance"]
    target_label  = "dsn"
  }
  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
  rule {
    target_label = "<CUSTOM_LABEL_1>"
    replacement  = "<CUSTOM_VALUE_1>"
  }
}

prometheus.scrape "database_observability_mysql_<DB_NAME>" {
  targets    = discovery.relabel.database_observability_mysql_<DB_NAME>.output
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}
```

Before Alloy 1.22.0, a `prometheus.exporter.mysql` component is required.

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
local.file "mysql_secret_<DB_NAME>" {
  filename  = "/var/lib/alloy/mysql_secret_<DB_NAME>"
  is_secret = true
}

prometheus.exporter.mysql "mysql_<DB_NAME>" {
  data_source_name  = local.file.mysql_secret_<DB_NAME>.content
  enable_collectors = ["perf_schema.eventsstatements"]
  perf_schema.eventsstatements {
    limit      = 100
    text_limit = 0
  }
}

database_observability.mysql "mysql_<DB_NAME>" {
  data_source_name  = local.file.mysql_secret_<DB_NAME>.content
  forward_to        = [loki.relabel.database_observability_mysql_<DB_NAME>.receiver]
  targets           = prometheus.exporter.mysql.mysql_<DB_NAME>.targets

  // OPTIONAL: enable these settings if you chose Alloy-managed Performance
  // Schema consumers or actor tracking during database setup.
  allow_update_performance_schema_settings = true

  // Requires UPDATE on performance_schema.setup_consumers.
  query_samples {
    auto_enable_setup_consumers = true
  }

  // Requires INSERT and UPDATE on performance_schema.setup_actors.
  setup_actors {
    auto_update_setup_actors = true
  }

  // OPTIONAL: provide additional information specific to the cloud provider
  // that hosts the database to enable infrastructure observability features.
  // For Azure and Google Cloud SQL examples, refer to the platform setup guides.
  cloud_provider {
    aws {
      arn = "<AWS_RDS_DB_ARN>"
    }
  }
}

loki.relabel "database_observability_mysql_<DB_NAME>" {
  forward_to = [loki.write.grafana_cloud_loki.receiver]

  // OPTIONAL: add any additional relabeling rules
  // (must be consistent with rules in "discovery.relabel")
  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
  rule {
    target_label = "<CUSTOM_LABEL_1>"
    replacement  = "<CUSTOM_VALUE_1>"
  }
}

discovery.relabel "database_observability_mysql_<DB_NAME>" {
  targets = database_observability.mysql.mysql_<DB_NAME>.targets

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }

  // OPTIONAL: add any additional relabeling rules
  // (must be consistent with rules in "loki.relabel")
  // OPTIONAL: relabel `instance` to `dsn` before overwriting `instance`;
  // the `dsn` label is used in the integration with the knowledge graph
  rule {
    source_labels = ["instance"]
    target_label  = "dsn"
  }
  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
  rule {
    target_label = "<CUSTOM_LABEL_1>"
    replacement  = "<CUSTOM_VALUE_1>"
  }
}

prometheus.scrape "database_observability_mysql_<DB_NAME>" {
  targets    = discovery.relabel.database_observability_mysql_<DB_NAME>.output
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}
```

Replace the placeholders:

- `DB_NAME`: Database name Alloy uses in component identifiers (appears in component names and secret filenames).
- `AWS_RDS_DB_ARN`: Amazon RDS database ARN for cloud provider integration (optional). For Azure or Google Cloud SQL, refer to the [Azure MySQL](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/set-up/mysql/azure/) or [Cloud SQL MySQL](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/set-up/mysql/cloudsql/) setup guides.
- `INSTANCE_LABEL`: Value that sets the `instance` label on logs and metrics (optional).
- `CUSTOM_LABEL_1`, `CUSTOM_VALUE_1`: Optional custom label key and value you attach to logs and metrics.
- Secret file content DSN example: `<DB_O11Y_USER>:<DB_O11Y_PASSWORD>@tcp(<DB_HOST>:<DB_PORT>)/`.
  
  - `DB_O11Y_USER`: The monitoring user you created and granted privileges to, for example, `db-o11y`. Don’t connect as a different administrator or application user.
  - `DB_O11Y_PASSWORD`: Password for the database user.
  - `DB_HOST`: Hostname or IP address of the database.
  - `DB_PORT`: Database port number.

Find more about the options supported by the `database_observability.mysql` component in the [reference](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/) documentation.

#### Add Prometheus and Loki write configuration

Add the Prometheus remote write and Loki write configuration. From Grafana Cloud, open your stack to get the URLs and generate API tokens:

Alloy ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
prometheus.remote_write "metrics_service" {
  endpoint {
    url = sys.env("GCLOUD_HOSTED_METRICS_URL")

    basic_auth {
      password = sys.env("GCLOUD_RW_API_KEY")
      username = sys.env("GCLOUD_HOSTED_METRICS_ID")
    }
  }
}

loki.write "grafana_cloud_loki" {
  endpoint {
    url = sys.env("GCLOUD_HOSTED_LOGS_URL")

    basic_auth {
      password = sys.env("GCLOUD_RW_API_KEY")
      username = sys.env("GCLOUD_HOSTED_LOGS_ID")
    }
  }
}
```

Replace the placeholders:

- `GCLOUD_HOSTED_METRICS_URL`: Your Grafana Cloud Prometheus remote write URL.
- `GCLOUD_HOSTED_METRICS_ID`: Your Grafana Cloud Prometheus instance ID (username).
- `GCLOUD_HOSTED_LOGS_URL`: Your Grafana Cloud Loki write URL.
- `GCLOUD_HOSTED_LOGS_ID`: Your Grafana Cloud Loki instance ID (username).
- `GCLOUD_RW_API_KEY`: Grafana Cloud API token with write permissions.

## Verify telemetry in Grafana Cloud

After Alloy starts, verify that Database Observability is receiving telemetry.

1. In Grafana Cloud, open **Database Observability**.
2. Go to **Configuration**.
3. Select **Telemetry status**.
4. Select your database instance.
5. Confirm that telemetry status checks pass.
6. Open **Queries overview** and confirm that query metrics appear.

After telemetry appears, the database instance should be visible and Queries overview should show query metrics. Additional data such as query samples, wait events, schema details, and explain plans becomes available as Alloy collects it and as the database engine supports it.

Telemetry can take a few minutes to appear. For detailed status checks, refer to [Verify telemetry status](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/configure/verify-telemetry-status/).

## Troubleshoot first-run issues

If data doesn’t appear after setup:

- If the database instance doesn’t appear in Database Observability, check Alloy connectivity and labels.
- If telemetry status checks fail, use the Configuration page to identify the failed requirement.
- If query metrics appear but samples, wait events, or explain plans are missing, check database privileges and Performance Schema settings.
- If Alloy can’t connect to the database, check network and firewall settings, DNS, and the monitoring user’s host restrictions.

For detailed guidance, refer to [Troubleshoot Alloy](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/alloy/) or [Troubleshoot MySQL](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/mysql/).

## Next steps

- [View query performance](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/monitor/view-query-performance/)
- [Find your application’s queries](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/monitor/find-application-queries/)
- [Link traces and queries](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/monitor/link-traces/)
- [Analyze explain plans](https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/investigate/analyze-explain-plans/)
