Documentation Grafana Cloud Monitor applications Database Observability Configure Alloy collection

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 and 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.

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
• database_observability.postgres

MySQL collector tuning

For complete configuration options, refer to the 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 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 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 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 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 in the Alloy reference.

MySQL setup_consumers collector

Monitors Performance Schema consumers status. For all parameters, refer to the setup_consumers block 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 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 in the Alloy reference.

PostgreSQL collector tuning

For complete configuration options, refer to the 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 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 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 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 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 in the Alloy reference.

Enable and disable collectors

Use these steps to control which collectors run.

Enable additional collectors

Alloy Copy

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

Disable collectors

Alloy Copy

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

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

  // ...
}

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

PostgreSQL: Exclude databases and users

Alloy Copy

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 to review the setting.

• Enable auto_update_setup_actors in the setup_actors block 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 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 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 section for a complete configuration example.

• The exclude_current_user parameter in the query_samples block 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

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

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

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

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 for more details.

Permissions required:

SQL Copy

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.

View Alloy logs

View Alloy logs to verify collection is working:

Bash Copy

# 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

# 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 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: Complete MySQL collector parameters and defaults
• database_observability.postgres Alloy component reference: Complete PostgreSQL collector parameters and defaults
• Verify telemetry status: Check configuration health per database
• Monitor multiple databases: Scale to many databases
• Requirements and overhead: Resource planning