---
title: "Tune Alloy collection | Database Observability documentation"
description: "Adjust Grafana Alloy collector settings for optimal performance and data volume."
---

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

# Tune Alloy collection

Grafana Alloy collects metrics and logs from your databases through configurable collectors. This guide helps you tune collection for your specific environment, whether you need more detailed data or reduced overhead. For complete parameter reference, refer to the Alloy component docs for [`database_observability.mysql`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/) and [`database_observability.postgres`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/).

## Collectors overview

Database Observability uses several collectors, each responsible for different data. The following table shows how each collector maps to Database Observability features and which database engines it applies to.

Expand table

| Collector         | Database Observability feature     | Engines                                                                                                                                                                                                                                                                                          | Default state |
|-------------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| query\_details    | Overview metrics, query list       | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-query_details-collector), [`PostgreSQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-query_details-collector)   | Enabled       |
| query\_samples    | Query Samples tab, Wait Events tab | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-query_samples-collector), [`PostgreSQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-query_samples-collector)   | Enabled       |
| schema\_details   | Table Schema Details tab           | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-schema_details-collector), [`PostgreSQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-schema_details-collector) | Enabled       |
| explain\_plans    | Explain Plan tab                   | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-explain_plans-collector), [`PostgreSQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-explain_plans-collector)   | Enabled       |
| setup\_consumers  | Query Samples Tab                  | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-setup_consumers-collector)                                                                                                                                                      | Enabled       |
| setup\_actors     | Query Samples Tab                  | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-setup_actors-collector)                                                                                                                                                         | Enabled       |
| locks             | Locks insights                     | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-locks-collector)                                                                                                                                                                | Disabled      |
| `health_check`    | Configuration page                 | [`MySQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#mysql-health_check-collector), [`PostgreSQL`](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-health_check-collector)     | Always on     |
| `connection_info` | Instance metadata labels           | MySQL, PostgreSQL                                                                                                                                                                                                                                                                                | Always on     |
| `logs`            | Error metrics                      | PostgreSQL                                                                                                                                                                                                                                                                                       | Always on     |

Collectors with the **Enabled** or **Disabled** default state can be toggled using `enable_collectors` and `disable_collectors`. Collectors marked **Always on** run unconditionally and cannot be disabled.

For complete parameter reference for each collector, refer to the Alloy component docs:

- [`database_observability.mysql`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/)
- [`database_observability.postgres`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/)

## MySQL collector tuning

For complete configuration options, refer to the [`database_observability.mysql`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/) Alloy component reference.

### MySQL `query_details` collector

Controls collection of query statistics from `Performance Schema`. For all parameters, refer to the [`query_details` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#query_details) in the Alloy reference.

**Tuning guidance:**

- Increase `collect_interval` to reduce database load
- Decrease `statements_limit` in high volume environments
- Recommended settings work well for most environments

### MySQL `query_samples` collector

Captures individual query executions from `Performance Schema`. For all parameters, refer to the [`query_samples` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#query_samples) in the Alloy reference.

**Tuning guidance:**

- Shorter `collect_interval` captures more samples but increases load and telemetry volume
- Enable `auto_enable_setup_consumers` to automatically maintain `Performance Schema` configuration
- Only disable redaction (`disable_query_redaction = true`) in non-production or when parameters don’t contain sensitive data
- Use `sample_min_duration` and `wait_event_min_duration` to filter out short-running queries and wait events, reducing telemetry volume while keeping focus on slower operations

### MySQL `schema_details` collector

Collects table and column metadata. For all parameters, refer to the [`schema_details` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#schema_details) in the Alloy reference.

**Tuning guidance:**

- Tune cache parameters to reduce repeated metadata queries
- Increase `cache_size` for databases with many schemas and tables
- Reduce `cache_ttl` if schema changes frequently

### MySQL `explain_plans` collector

Captures query execution plans. For all parameters, refer to the [`explain_plans` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#explain_plans) in the Alloy reference.

**Tuning guidance:**

- Reduce `per_collect_ratio` to decrease explain plan overhead (for example, `0.5` for 50%)
- Increase `initial_lookback` if you need explain plans for older queries at Alloy startup
- Explain plans run `EXPLAIN`, not `EXPLAIN ANALYZE`, so overhead is minimal

### MySQL `locks` collector

Captures active lock information (disabled by default). For all parameters, refer to the [`locks` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#locks) in the Alloy reference.

> Note
> 
> This collector is disabled by default. Features that use lock information aren’t yet available.

### MySQL `setup_consumers` collector

Monitors `Performance Schema` consumers status. For all parameters, refer to the [`setup_consumers` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#setup_consumers) in the Alloy reference.

### MySQL `setup_actors` collector

Monitors and optionally manages `Performance Schema` actors settings. For all parameters, refer to the [`setup_actors` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#setup_actors) in the Alloy reference.

**Tuning guidance:**

- Enable `auto_update_setup_actors` to prevent the monitoring user’s queries from appearing in dashboards, reducing noise and telemetry volume.

### MySQL `health_check` collector

Verifies database connectivity. For all parameters, refer to the [`health_check` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#health_checks) in the Alloy reference.

## PostgreSQL collector tuning

For complete configuration options, refer to the [`database_observability.postgres`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/) Alloy component reference.

### PostgreSQL `query_details` collector

Controls collection of query statistics from `pg_stat_statements`. For all parameters, refer to the [`query_details` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#query_details) in the Alloy reference.

**Tuning guidance:**

- Increase `collect_interval` to reduce database load
- Decrease `statements_limit` in high volume environments
- Recommended settings work well for most environments

### PostgreSQL `query_samples` collector

Captures individual query executions from `pg_stat_activity`. For all parameters, refer to the [`query_samples` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#query_samples) in the Alloy reference.

**Tuning guidance:**

- Shorter `collect_interval` captures more samples but increases load and telemetry volume
- Keep `exclude_current_user = true` to avoid capturing samples of monitoring queries generated by Grafana Alloy
- Only disable redaction (`disable_query_redaction = true`) in non-production or when parameters don’t contain sensitive data

### PostgreSQL `schema_details` collector

Collects table and column metadata. Configuration is identical to MySQL. For all parameters, refer to the [`schema_details` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#schema_details) in the Alloy reference.

**Tuning guidance:**

- Tune cache parameters to reduce repeated metadata queries
- Increase `cache_size` for databases with many schemas and tables
- Reduce `cache_ttl` if schema changes frequently

### PostgreSQL `explain_plans` collector

Captures query execution plans. Configuration is similar to MySQL, without `initial_lookback`. For all parameters, refer to the [`explain_plans` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#explain_plans) in the Alloy reference.

**Tuning guidance:**

- Reduce `per_collect_ratio` to decrease explain plan overhead (for example, `0.5` for 50%)
- Increase `initial_lookback` if you need explain plans for older queries at Alloy startup
- Explain plans run `EXPLAIN`, not `EXPLAIN ANALYZE`, so overhead is minimal

### PostgreSQL `health_check` collector

Verifies database connectivity. For all parameters, refer to the [`health_check` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#health_check) in the Alloy reference.

## Enable and disable collectors

Use these steps to control which collectors run.

### Enable additional collectors

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

```alloy
database_observability.mysql "default" {
  enable_collectors = ["explain_plans"]  // Add explain_plans collector
}
```

### Disable collectors

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

```alloy
database_observability.mysql "default" {
  disable_collectors = ["explain_plans", "schema_details"]
}
```

## Exclude schemas, databases, and users

Use these filters to reduce noise and limit collection scope.

### MySQL: Exclude schemas

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

```alloy
database_observability.mysql "default" {
  exclude_schemas = ["rdsadmin"]

  // ...
}

prometheus.exporter.mysql "default" {
  perf_schema.eventsstatements {
    exclude_schemas = ["rdsadmin"]
  }

  // ...
}
```

Use `exclude_schemas` to filter out management schemas or other application schemas.

Make sure that the lists of excluded schemas match across all settings.

### PostgreSQL: Exclude databases and users

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

```alloy
database_observability.postgres "default" {
  exclude_databases = ["rdsadmin"]
  exclude_users     = ["replication_user"]

  // ...
}

prometheus.exporter.postgres "default" {
  autodiscovery {
    database_denylist = ["rdsadmin"]
    enabled           = true
  }

  stat_statements {
    exclude_databases = ["rdsadmin"]
    exclude_users     = ["replication_user"]
  }

  // ...
}
```

Use `exclude_users` to filter out queries from service accounts or replication users that add noise to your monitoring data. Use `exclude_databases` to filter out management databases or other application databases.

Make sure that the lists of excluded users and databases match across all settings.

### Exclude the monitoring user

The database user that Alloy connects with generates its own queries against the database. To prevent these from appearing in your dashboards:

**MySQL**

- Make sure that the monitoring user has the correct settings in the `setup_actors` table to exclude tracking its queries in `Performance Schema`. Refer to [Troubleshoot MySQL guide](/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/mysql/#check-that-tracking-of-monitoring-user-queries-is-disabled) to review the setting.
- Enable `auto_update_setup_actors` in the [`setup_actors` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/#setup_actors) to let Alloy automatically check and disable `Performance Schema` instrumentation for the monitoring user. This also requires setting `allow_update_performance_schema_settings = true` at the component level. Refer to [Performance Schema settings](#performance-schema-settings) for the required permissions.

**PostgreSQL**

- Make sure that the monitoring user has the correct setting for `pg_stat_statements.track = none` to exclude tracking its queries. Refer to [Troubleshoot PostgreSQL guide](/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/postgres/#check-that-tracking-of-monitoring-user-queries-is-disabled) to review the setting.
- Add the monitoring user to the `exclude_users` configuration setting both in the `prometheus.exporter.postgres` and `database_observability.postgres` blocks. Refer to the [Exclude databases and users](/docs/grafana-cloud/monitor-applications/database-observability/configure/tune-alloy-collection/#postgresql-exclude-databases-and-users) section for a complete configuration example.
- The `exclude_current_user` parameter in the [`query_samples` block](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/#query_samples) is `true` by default, so the monitoring user’s queries are automatically excluded from samples.

## Environment-specific configurations

Use these examples to tune collection for different workloads.

### High-volume environment

For databases with many unique queries and high traffic. The main goals are reducing per-collection overhead and filtering out noise from system schemas.

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

```alloy
database_observability.mysql "default" {
  // Skip system schemas to reduce noise
  exclude_schemas = ["rdsadmin"]

  // Collect digests less frequently; capture less unique queries per cycle
  // (defaults: collect_interval = "1m", statements_limit = 250)
  query_details {
    collect_interval = "5m"
    statements_limit = 30
  }

  // Reduce sample frequency and filter short-running queries
  // (defaults: collect_interval = "10s", sample_min_duration = "0s",
  //  wait_event_min_duration = "1us")
  query_samples {
    collect_interval        = "30s"
    sample_min_duration     = "100ms"
    wait_event_min_duration = "1ms"
  }

  // Run EXPLAIN on fewer queries, less often
  // (defaults: collect_interval = "1m", per_collect_ratio = 1.0)
  explain_plans {
    collect_interval  = "5m"
    per_collect_ratio = 0.5
  }

  // Increase collect interval and cache lifetime
  // (defaults: collect_interval = "1m", cache_ttl = "10m")
  schema_details {
    collect_interval = "5m"
    cache_ttl        = "30m"
  }
}
```

### Low-resource environment

For environments where minimizing database overhead is critical. This configuration disables the most expensive collectors and reduces collection frequency across the board.

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

```alloy
database_observability.mysql "default" {
  // Skip system schemas
  exclude_schemas = ["rdsadmin"]

  // Disable the most expensive collectors
  // (explain_plans runs EXPLAIN queries; schema_details queries information_schema)
  disable_collectors = ["explain_plans", "schema_details"]

  // Collect digests less often with a smaller limit
  // (defaults: collect_interval = "1m", statements_limit = 250)
  query_details {
    collect_interval = "5m"
    statements_limit = 30
  }

  // Reduce sample frequency and filter short-running queries
  // (defaults: collect_interval = "10s", sample_min_duration = "0s",
  //  wait_event_min_duration = "1us")
  query_samples {
    collect_interval        = "60s"
    sample_min_duration     = "500ms"
    wait_event_min_duration = "10ms"
  }
}
```

### Development environment

For development where you want maximum visibility and minimal setup friction. Only use `disable_query_redaction` when query parameters don’t contain sensitive data.

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

```alloy
database_observability.mysql "default" {
  // More frequent samples with full query text
  // (defaults: collect_interval = "10s", disable_query_redaction = false)
  query_samples {
    collect_interval        = "5s"
    disable_query_redaction = true
  }

  // Short collection interval for rapidly changing schemas (default: "1m")
  schema_details {
    collect_interval = "30s"
  }
}
```

## Performance Schema settings

For MySQL, you can allow Alloy to automatically manage certain `Performance Schema` settings:

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

```alloy
database_observability.mysql "default" {
  // Allow Alloy to enable required consumers
  allow_update_performance_schema_settings = true

  query_samples {
    // Automatically check and enable consumers to
    // allow capturing CPU usage stats for wait events
    auto_enable_setup_consumers    = true
    setup_consumers_check_interval = "1h"
  }

  setup_actors {
    // Automatically check and disable tracking for monitoring user
    auto_update_setup_actors = true
  }
}
```

As an additional precaution to avoid unwanted settings updates, `allow_update_performance_schema_settings` must be enabled for `auto_enable_setup_consumers` and `auto_update_setup_actors` to work. Refer to the Alloy component docs for [`database_observability.mysql`](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/) for more details.

**Permissions required:**

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

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

## Monitor collection health

Use these checks to verify collectors are healthy and exporting data.

### Use the Configuration page

The Configuration page provides at-a-glance status checks for each database instance:

1. Navigate to **Database Observability** > **Configuration**.
2. Select your instance from the **Instance** dropdown.
3. Review the status check tiles for any failed checks (shown with red warnings).

For details on each status check and what it validates, refer to [Verify telemetry status](/docs/grafana-cloud/monitor-applications/database-observability/configure/verify-telemetry-status/).

### View Alloy logs

View Alloy logs to verify collection is working:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
# Look for collection errors
journalctl -u alloy | grep -i "database_observability"

# Or in Docker
docker logs alloy 2>&1 | grep -i "database_observability"
```

### Verify data in Grafana

1. Navigate to **Database Observability**.
2. Check that queries appear in the Overview.
3. Verify all tabs have data (Samples, Wait Events, Schema, Explain Plans).

### View collection metrics

Alloy exposes metrics about its own operation:

promql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```promql
# Collection success rate
rate(alloy_component_controller_evaluations_total{health="healthy"}[5m])

# Collection errors
rate(alloy_component_controller_evaluations_total{health="unhealthy"}[5m])
```

## Troubleshoot collection issues

Start by checking the [Configuration page](/docs/grafana-cloud/monitor-applications/database-observability/configure/verify-telemetry-status/) for failed status checks, which can identify common issues like missing permissions or disabled features.

### No data appearing

1. Check Alloy is running and connected to database
2. Verify network connectivity
3. Check database permissions
4. Review Alloy logs for errors

### Partial data

1. Verify specific collector is enabled
2. Check permissions for that collector’s data source
3. Ensure schema/database isn’t excluded

### High database load from collection

1. Increase collection intervals
2. Enable caching for schema details
3. Reduce `per_collect_ratio` for explain plans
4. Disable collectors you don’t need

## Related documentation

- [`database_observability.mysql` Alloy component reference](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.mysql/): Complete MySQL collector parameters and defaults
- [`database_observability.postgres` Alloy component reference](/docs/grafana-cloud/send-data/alloy/reference/components/database_observability/database_observability.postgres/): Complete PostgreSQL collector parameters and defaults
- [Verify telemetry status](/docs/grafana-cloud/monitor-applications/database-observability/configure/verify-telemetry-status/): Check configuration health per database
- [Monitor multiple databases](/docs/grafana-cloud/monitor-applications/database-observability/configure/monitor-multiple-databases/): Scale to many databases
- [Requirements and overhead](/docs/grafana-cloud/monitor-applications/database-observability/set-up/requirements-overhead/): Resource planning