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 DB O11y features and which database engines it applies to.

Collectors with the Enabled 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.

query_details

Controls collection of query statistics from Performance Schema. For all parameters, refer to the query_details block in the Alloy reference.

Tuning guidance:

• Increase statements_limit if you have many unique queries
• Increase collect_interval to reduce database load
• Default settings work well for most environments

query_samples

Captures individual query executions from Performance Schema. For all parameters, refer to the query_samples block in the Alloy reference.

Tuning guidance:

• Shorter intervals capture more samples but increase load
• Enable auto_enable_setup_consumers to automatically maintain Performance Schema configuration
• Only disable redaction in non-production or when parameters don’t contain sensitive data

schema_details

Collects table and column metadata. For all parameters, refer to the schema_details block in the Alloy reference.

Tuning guidance:

• Enable caching to reduce repeated metadata queries
• Increase cache_size for databases with many schemas
• Reduce cache_ttl if schema changes frequently

explain_plans

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
• Explain plans run EXPLAIN, not EXPLAIN ANALYZE, so overhead is minimal

locks

Captures active lock information (disabled by default). For all parameters, refer to the locks block in the Alloy reference.

setup_consumers

Monitors Performance Schema consumer status. For all parameters, refer to the setup_consumers block in the Alloy reference.

setup_actors

Monitors and optionally manages Performance Schema actor settings. For all parameters, refer to the setup_actors block in the Alloy reference.

Note: Enabling auto_update_setup_actors prevents the monitoring user’s queries from appearing in dashboards, reducing noise and telemetry volume.

health_check

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.

query_details

Controls collection of query statistics from pg_stat_statements. For all parameters, refer to the query_details block in the Alloy reference.

query_samples

Captures individual query executions from pg_stat_activity. For all parameters, refer to the query_samples block in the Alloy reference.

Tuning guidance:

• Keep exclude_current_user = true to avoid capturing monitoring queries generated by Grafana Alloy
• Default 15s interval balances detail with overhead

schema_details

Collects table and column metadata. Configuration is identical to MySQL. For all parameters, refer to the schema_details block in the Alloy reference.

explain_plans

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.

health_check

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 = ["locks"]  // Add locks 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 = [
    "information_schema",
    "performance_schema",
    "mysql",
    "sys"
  ]
}

PostgreSQL: Exclude databases and users

Alloy Copy

database_observability.postgres "default" {
  exclude_databases = [
    "template0",
    "template1",
    "postgres"
  ]

  exclude_users = [
    "replication_user"
  ]
}

Use exclude_users to filter out queries from service accounts or replication users that add noise to your monitoring data.

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:

• PostgreSQL: 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.
• MySQL: Enable auto_update_setup_actors in the setup_actors block to disable Performance Schema instrumentation for the monitoring user entirely. This also requires setting allow_update_performance_schema_settings = true at the component level. Refer to Performance Schema settings for the required permissions.

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 (default: none excluded)
  exclude_schemas = [
    "information_schema",
    "performance_schema",
    "mysql",
    "sys"
  ]

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

  // Reduce sample frequency (default: "10s")
  query_samples {
    collect_interval = "30s"
  }

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

  // Increase cache capacity and lifetime
  // (defaults: cache_size = 256, cache_ttl = "10m")
  schema_details {
    cache_size = 512
    cache_ttl  = "15m"
  }
}

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 = [
    "information_schema",
    "performance_schema",
    "mysql",
    "sys"
  ]

  // 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 = 100
  }

  // Reduce sample frequency (default: "10s")
  query_samples {
    collect_interval = "30s"
  }
}

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" {
  // Allow Alloy to manage Performance Schema automatically
  allow_update_performance_schema_settings = true

  // Enable all optional collectors
  enable_collectors = ["locks"]

  // More frequent samples with full query text and auto-configured consumers
  // (defaults: collect_interval = "10s", disable_query_redaction = false,
  //  auto_enable_setup_consumers = false)
  query_samples {
    collect_interval            = "5s"
    disable_query_redaction     = true
    auto_enable_setup_consumers = true
  }

  // Short cache lifetime for rapidly changing schemas (default: "10m")
  schema_details {
    cache_ttl = "1m"
  }
}

Performance Schema settings

For MySQL, you can allow Alloy to manage Performance Schema:

Alloy Copy

database_observability.mysql "default" {
  // Allow Alloy to enable required consumers
  allow_update_performance_schema_settings = true
  
  query_samples {
    auto_enable_setup_consumers    = true
    setup_consumers_check_interval = "1h"
  }
  
  setup_actors {
    auto_update_setup_actors = true  // Disable tracking for monitoring user
  }
}

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