Documentation Grafana Cloud Monitor applications Database Observability Get started MySQL Google CloudSQL

Set up Google CloudSQL MySQL

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

What you’ll achieve

In this article, you:

• Configure CloudSQL MySQL database flags for monitoring.
• Create monitoring users with required privileges.
• Configure Alloy with the Database Observability components.
• Forward telemetry to Grafana Cloud.

Before you begin

Review these requirements:

• CloudSQL MySQL 8.0 or later.
• Access to modify CloudSQL instance database flags.
• Grafana Alloy deployed and accessible to your CloudSQL instance.
• Network connectivity between Alloy and your CloudSQL instance (via private IP, public IP with authorized networks, or Cloud SQL Auth Proxy).

For general MySQL setup concepts, refer to Set up MySQL.

Configure database flags

Enable Performance Schema and related instrumentation by adding database flags to your CloudSQL MySQL instance. These flags require an instance restart to take effect.

Required database flags

Using the Google Cloud Console

1. Open the Cloud Console and navigate to Instances
2. Select your CloudSQL MySQL instance.
3. Click Edit.
4. Expand Flags and parameters section.
5. Click Add a database flag for each flag listed above.
6. Set the flag name and value as specified in the table.
7. Click Save to apply the changes.
8. The instance restarts automatically to apply the new flags.

For detailed console instructions, refer to Configure database flags in the Google Cloud documentation.

Using Terraform

Using Terraform with google_sql_database_instance:

hcl Copy

resource "google_sql_database_instance" "instance" {
  database_version = "MYSQL_8_0"
  name             = "<INSTANCE_NAME>"
  region           = "<REGION>"
  settings {
    database_flags {
      name  = "performance_schema"
      value = "on"
    }
    database_flags {
      name  = "performance_schema_max_digest_length"
      value = "4096"
    }
    database_flags {
      name  = "performance_schema_max_sql_text_length"
      value = "4096"
    }
    database_flags {
      name  = "max_digest_length"
      value = "4096"
    }
  }
}

Replace the placeholders:

• INSTANCE_NAME: Your CloudSQL instance name.
• REGION: GCP region where the instance is deployed.

Alternatively, configure flags using the gcloud CLI:

Bash Copy

gcloud sql instances patch <INSTANCE_NAME> \
  --database-flags=performance_schema=on,performance_schema_max_digest_length=4096,performance_schema_max_sql_text_length=4096,
  max_digest_length=4096

Create a monitoring user and grant required privileges

Connect to your CloudSQL MySQL instance and create the monitoring user:

SQL Copy

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 <DB_O11Y_PASSWORD> with a secure password for the db-o11y MySQL user.

Disable tracking of monitoring user queries

Prevent tracking of queries executed by the monitoring user itself:

SQL Copy

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

Alternatively, grant privileges to the monitoring user to let Alloy automatically disable the setup_actors setting on your behalf (useful for large fleets):

SQL Copy

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

Then, enable the Alloy options allow_update_performance_schema_settings (see docs) and setup_actors.auto_update_setup_actors (see docs) as detailed in the documentation of the database_observability.mysql component.

Grant object privileges for detailed data

Grant access to specific schemas when you want detailed information:

SQL Copy

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

Replace <SCHEMA_NAME> 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

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

Grant privileges to auto-enable consumers

Grant update privileges for Performance Schema consumers if you want Alloy to auto-enable them:

SQL Copy

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

Then, enable the Alloy option allow_update_performance_schema_settings as described in the reference documentation of the database_observability.mysql component.

Alternatively, enable consumers manually as described in the Set up MySQL guide.

Verify user privileges

Verify that the user exists and has the expected privileges:

SQL Copy

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

Expected output:

Copy

+------------------------------------------------------------------------------+
| Grants for db-o11y@%                                                         |
+------------------------------------------------------------------------------+
| GRANT PROCESS, REPLICATION CLIENT ON *.* TO `db-o11y`@`%`                    |
| GRANT SELECT, SHOW VIEW ON *.* TO `db-o11y`@`%`                              |
| GRANT SELECT ON `performance_schema`.* TO `db-o11y`@`%`                      |
| GRANT INSERT, UPDATE ON `performance_schema`.`setup_actors` TO `db-o11y`@`%` |
+------------------------------------------------------------------------------+

Verify database flag settings

Verify that the database flags were applied correctly after the instance restarts:

SQL Copy

SHOW VARIABLES LIKE 'performance_schema';

Expected result: Value is ON.

SQL Copy

SHOW VARIABLES LIKE 'performance_schema_max_digest_length';

Expected result: Value is 4096.

SQL Copy

SHOW VARIABLES LIKE 'performance_schema_max_sql_text_length';

Expected result: Value is 4096.

SQL Copy

SHOW VARIABLES LIKE 'max_digest_length';

Expected result: Value is 4096.

Run and configure Alloy

Run Alloy and add the Database Observability configuration for your CloudSQL instance.

Run the latest Alloy version

Run Alloy version 1.13.0 or later with the --stability.level=public-preview flag for the database_observability.mysql component. Find the latest stable version on Docker Hub.

Add the CloudSQL MySQL configuration blocks

Add these blocks to Alloy for CloudSQL MySQL. Replace <DB_NAME>. Create a local.file with the Data Source Name string, for example, <DB_USER>:<DB_PASSWORD>@tcp(<INSTANCE_IP>:<DB_PORT>)/:

Alloy Copy

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"]
}

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
  exclude_schemas   = ["cloudsqladmin"]
}

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

  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
}

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

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

  rule {
    target_label = "instance"
    replacement  = "<INSTANCE_LABEL>"
  }
}

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).
• INSTANCE_LABEL: Value that sets the instance label on logs and metrics (optional).
• Secret file content DSN example: DB_USER:DB_PASSWORD@tcp(INSTANCE_IP:DB_PORT)/.
  • DB_USER: Database user Alloy uses to connect (e.g. db-o11y).
  • DB_PASSWORD: Password for the database user.
  • INSTANCE_IP: CloudSQL instance IP address (private or public).
  • DB_PORT: Database port number (default: 3306).

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

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

Run and configure Alloy with the Grafana Kubernetes Monitoring Helm chart

Extend your values.yaml when you use the k8s-monitoring Helm chart and set databaseObservability.enabled to true within the MySQL integration.

YAML Copy

integrations:
  collector: alloy-singleton
  mysql:
    instances:
      - name: <INSTANCE_NAME>
        jobLabel: integrations/db-o11y
        exporter:
          enabled: true
          collectors:
            perfSchemaEventsStatements:
              enabled: true
          dataSource:
            host: <INSTANCE_IP>
            auth:
              usernameKey: username
              passwordKey: password
        databaseObservability:
          enabled: true
          allowUpdatePerformanceSchemaSettings: true
          extraConfig: |
            exclude_schemas = ["cloudsqladmin"]
        secret:
          create: false
          name: <SECRET_NAME>
          namespace: <NAMESPACE>
        logs:
          enabled: true
          labelSelectors:
            app.kubernetes.io/instance: <INSTANCE_NAME>

Replace the placeholders:

• INSTANCE_NAME: Name for this database instance in Kubernetes.
• INSTANCE_IP: CloudSQL instance IP address.
• SECRET_NAME: Name of the Kubernetes secret containing database credentials.
• NAMESPACE: Kubernetes namespace where the secret exists.

To see the full set of values, check out the k8s-monitoring Helm chart documentation or the example configuration.

Optional: Configure GCP Secret Manager and Kubernetes

If you use GCP Secret Manager with External Secrets Operator to manage database credentials, configure them as follows.

Secret path convention

Store monitoring credentials in GCP Secret Manager with a name following this convention:

Copy

cloudsql-<INSTANCE_NAME>-monitoring

MySQL secret format

Store the secret as JSON with the following format:

JSON Copy

{
  "username": "db-o11y",
  "password": "<DB_O11Y_PASSWORD>",
  "host": "<INSTANCE_IP>",
  "port": 3306
}

Replace the placeholders:

• DB_O11Y_PASSWORD: Password for the db-o11y MySQL user.
• INSTANCE_IP: CloudSQL instance IP address.
• INSTANCE_NAME: Your CloudSQL instance name.

Create the secret via gcloud CLI

Bash Copy

echo '{"username":"db-o11y","password":"<DB_O11Y_PASSWORD>","host":"<INSTANCE_IP>","port":3306}' | \
  gcloud secrets create cloudsql-<INSTANCE_NAME>-monitoring --data-file=-

Kubernetes External Secrets configuration

Use the External Secrets Operator to sync the GCP secret into Kubernetes:

YAML Copy

---
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: <INSTANCE_NAME>-db-monitoring-secretstore
spec:
  provider:
    gcpsm:
      projectID: <GCP_PROJECT_ID>
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: <INSTANCE_NAME>-db-monitoring-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: <INSTANCE_NAME>-db-monitoring-secretstore
  dataFrom:
    - extract:
        key: cloudsql-<INSTANCE_NAME>-monitoring

Replace the placeholders:

• INSTANCE_NAME: CloudSQL instance name.
• GCP_PROJECT_ID: Google Cloud project ID.

Next steps

For an overview of key concepts, refer to Introduction to Database Observability.

For troubleshooting during setup, refer to Troubleshoot.