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

Documentation Grafana Alloy Reference Components database_observability database_observability.mysql

database_observability.mysql

database_observability.mysql connects to a MySQL database and collects observability data from the performance_schema and information_schema. The component collects query details, schema information, explain plans, query samples, and lock information. It forwards this data as log entries to Loki receivers and exports targets for Prometheus scraping.

Usage

Alloy Copy

database_observability.mysql "<LABEL>" {
  data_source_name = <DATA_SOURCE_NAME>
  forward_to       = [<LOKI_RECEIVERS>]
}

Arguments

You can use the following arguments with database_observability.mysql:

The following collectors are configurable:

Blocks

You can use the following blocks with database_observability.mysql:

cloud_provider

The cloud_provider block has no attributes. It contains zero or one of the aws, azure, or gcp blocks. You use the cloud_provider block to provide information related to the cloud provider that hosts the database under observation. This information is appended as labels to the collected metrics. The labels make it easier for you to filter and group your metrics.

aws

The aws block supplies the ARN identifier for the database being monitored.

azure

The azure block supplies the identifying information for the database being monitored.

gcp

The gcp block supplies the identifying information for the GCP Cloud SQL database being monitored.

database_instance

The database_instance block defines one database server to monitor. Repeat the block to monitor several databases with a single component. The block label must be unique across database_instance blocks and identifies the database in the component’s metrics endpoint path. Each database_instance block must also point to a distinct server: two blocks that resolve to the same host, port, and database name are rejected.

Each database_instance block can also contain a [cloud_provider][cloud_provider] block that applies to that database only, and [rule][rule] blocks that relabel the metrics and logs of that database only.

The component always embeds a mysqld_exporter for each database_instance block and serves its metrics on the block’s metrics path. Use the [prometheus_exporter][prometheus_exporter] block to configure it. External exporter targets are only supported in the top-level single-DSN form.

When you define database_instance blocks, don’t set the top-level data_source_name, targets, and cloud_provider arguments. They’re mutually exclusive with database_instance blocks. All other arguments and blocks, such as collector settings and prometheus_exporter, apply to every configured database.

The metrics for each database are served on a separate /db/<LABEL>/metrics path under the component’s HTTP endpoint, and the exported targets point to the corresponding path. When you don’t define database_instance blocks, the component serves metrics on its historical /metrics path. The metrics endpoints are served exactly at those paths: requests to any other path under the component’s HTTP endpoint return HTTP 404.

For example:

Alloy Copy

database_observability.mysql "pool" {
  forward_to = [loki.write.logs_service.receiver]

  database_instance "orders" {
    data_source_name = sys.env("ORDERS_DSN")

    cloud_provider {
      aws {
        arn = "orders-rds-db-arn"
      }
    }

    rule {
      target_label = "environment"
      replacement  = "production"
    }
  }

  database_instance "billing" {
    data_source_name = sys.env("BILLING_DSN")

    rule {
      target_label = "environment"
      replacement  = "staging"
    }
  }
}

In this example, the metrics and logs of the orders database carry environment="production", and those of the billing database carry environment="staging".

rule

The rule block relabels the metrics and the logs of the database_instance block that contains it. Use it to tell the data of each monitored database apart, for example by environment, team, or tier.

clustering

When Alloy is using clustering, and enabled is set to true, then this database_observability.mysql component instance opts-in to distributing its configured databases between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file. All component instances opting in to clustering use the instance key of each configured database, <network>(<host>:<port>)/<dbname>, and a consistent hashing algorithm to determine ownership of each database between the cluster peers. Each peer then only collects from the subset of databases it’s responsible for, and only exports the targets of those databases, so prometheus.scrape components on the same node scrape exactly the databases the node owns. When a node joins or leaves the cluster, every peer recalculates ownership: expect a short gap or a brief duplicate collection for a database while its ownership moves. This includes the collectors that update performance_schema settings, such as setup_actors and setup_consumers, which can briefly run from two nodes during the move: their updates are idempotent. While the cluster isn’t yet ready to admit traffic, for example while it’s still forming and waiting for the minimum cluster size, the component doesn’t collect from any database.

Clustering is also useful with a single database: when several cluster nodes run an identical configuration, exactly one node collects from the database at a time, which gives you a highly available setup without duplicate collection.

If Alloy is not running in clustered mode, then the block is a no-op and database_observability.mysql collects from every configured database.

setup_consumers

query_details

schema_details

The cache_enabled, cache_size, and cache_ttl settings are deprecated: they are accepted for backward compatibility, but ignored.

explain_plans

locks

query_samples

setup_actors

health_check

prometheus_exporter

The prometheus_exporter block configures the embedded mysqld_exporter scrapers. The data_source_name is inherited from the parent block.

Refer to prometheus.exporter.mysql docs for the full list of supported arguments and sub-blocks.

Example

Alloy Copy

database_observability.mysql "orders_db" {
  data_source_name = "user:pass@tcp(mysql:3306)/"
  forward_to       = [loki.relabel.orders_db.receiver]
  targets          = prometheus.exporter.mysql.orders_db.targets

  enable_collectors = ["query_samples", "explain_plans"]

  cloud_provider {
    aws {
      arn = "your-rds-db-arn"
    }
  }
}

prometheus.exporter.mysql "orders_db" {
  data_source_name  = "user:pass@tcp(mysql:3306)/"
  enable_collectors = ["perf_schema.eventsstatements"]
}

loki.relabel "orders_db" {
  forward_to = [loki.write.logs_service.receiver]
  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }
  rule {
    target_label = "instance"
    replacement  = "orders_db"
  }
}

discovery.relabel "orders_db" {
  targets = database_observability.mysql.orders_db.targets

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

prometheus.scrape "orders_db" {
  targets    = discovery.relabel.orders_db.targets
  job_name   = "integrations/db-o11y"
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

prometheus.remote_write "metrics_service" {
  endpoint {
    url = sys.env("<GRAFANA_CLOUD_HOSTED_METRICS_URL>")
    basic_auth {
      username = sys.env("<GRAFANA_CLOUD_HOSTED_METRICS_ID>")
      password = sys.env("<GRAFANA_CLOUD_RW_API_KEY>")
    }
  }
}

loki.write "logs_service" {
  endpoint {
    url = sys.env("<GRAFANA_CLOUD_HOSTED_LOGS_URL>")
    basic_auth {
      username = sys.env("<GRAFANA_CLOUD_HOSTED_LOGS_ID>")
      password = sys.env("<GRAFANA_CLOUD_RW_API_KEY>")
    }
  }
}

Replace the following:

• <GRAFANA_CLOUD_HOSTED_METRICS_URL>: The URL for your Grafana Cloud hosted metrics.
• <GRAFANA_CLOUD_HOSTED_METRICS_ID>: The user ID for your Grafana Cloud hosted metrics.
• <GRAFANA_CLOUD_RW_API_KEY>: Your Grafana Cloud API key.
• <GRAFANA_CLOUD_HOSTED_LOGS_URL>: The URL for your Grafana Cloud hosted logs.
• <GRAFANA_CLOUD_HOSTED_LOGS_ID>: The user ID for your Grafana Cloud hosted logs.

Compatible components

database_observability.mysql can accept arguments from the following components:

• Components that export Targets
• Components that export Loki LogsReceiver

database_observability.mysql has exports that can be consumed by the following components:

• Components that consume Targets