Add MySQL DBI config translator and pipeline orchestrator by Klarsen04 · Pull Request #2196 · aws/amazon-cloudwatch-agent

Klarsen04 · 2026-07-10T15:43:35Z

Summary

Add component translators and pipeline orchestrator for MySQL database monitoring via the OpenTelemetry pipeline, enabling the opentelemetry.collect.database_insights.mysql[] config section.

Continuation of #2176

Changes

Component translators:

MySQL receiver translator with functional options (endpoint, username, passfile, TLS, localhost detection)
Connectors: count/dbi_dbload_mysql (active session metrics) and signaltometrics/dbi_topsql_mysql (top query metrics)
Processor: transform/dbi_fix_start_time_mysql (timestamp correction)
Registers mysqlreceiver and adds JSON schema validation for mysql config

Pipeline orchestrator:

Generates per-instance metrics, log-to-metrics, raw events, and server logs pipelines from JSON config
MySQL-specific resource attributes, log group paths, and monitor user exclusion

Bug fix (new in this PR):

DB Load connector condition changed from processlist_command == "Query" to session.status != "idle" to correctly count prepared statement executions (Execute command) used by sysbench, ORMs, and JDBC applications

Tests

Unit tests for receiver translator, connector/processor creation, pipeline wiring
Golden YAML integration test
make build and make lint pass

Create the core MySQL receiver translator with functional options pattern: - translator.go with endpoint, username, passfile, TLS, localhost detection - translator_test.go with unit tests for all option functions - Register mysqlreceiver.NewFactory() in defaultcomponents - Add MySQLKey and MySQL DBI component name constants to common.go - Add go.mod dependency on mysqlreceiver

Add YAML configs and translator wiring for MySQL DBI pipelines: - dbi_dbload_mysql.yaml: count connector for active sessions by wait/user/db/sql/host - dbi_topsql_mysql.yaml: signaltometrics connector for top query metrics - transform_dbi_fix_start_time_mysql.yaml: transform processor for MySQL timestamps - Update count, signaltometrics, and transform translators to handle MySQL component names - Add unit tests for MySQL connector/processor creation

Add mysql[] array schema to database_insights in schema.json: - endpoint, instance_name, username, password_file - tls.ca_file for TLS configuration - logs.file_path for server log ingestion

Extend the DBI pipeline orchestrator to support MySQL instances: - Add translator_mysql.go with dbiMysqlTranslator implementing 4 pipeline types: - metrics/dbi_mysql_N: counter metrics + DBLoad/TopSQL from connectors - logs/dbi_mysql_N: log-to-metrics via count + signaltometrics connectors - logs/dbi_mysql_rawevents_N: raw query sample/top query events - logs/dbi_mysql_serverlogs_N: MySQL server log file ingestion - Add parseDbiMysqlInstances() to parse mysql[] config array - MySQL-specific resource attributes (db.system.name = "mysql") - MySQL-specific log group paths and monitor user exclusion filter - Unit tests for pipeline wiring with single/multiple instances

Add end-to-end config translation test for MySQL DBI: - dbi_mysql_config_linux.conf: input agent config fixture - dbi_mysql_config_linux.json: parsed JSON intermediate fixture - dbi_mysql_config_linux.yaml: golden YAML output (full OTel pipeline) - .mysql_credentials: test passfile for credential loading - Register TestMySQLDbiConfig in tocwconfig_unix_test.go

- Unify the DBI pipeline translator: merge translator_mysql.go into a single dbiTranslator that branches by engine (carried on the instance config), instead of maintaining a separate MySQL translator. - Make component naming consistent across engines using an engine suffix: count/dbi_dbload_<engine>, signaltometrics/dbi_topsql_<engine>, transform/dbi_fix_start_time_<engine>, and per-instance dbi_resource_<engine>_N, dbi_scope_<engine>_N, dbi_logs_<engine>_<dest>_N, dbi_exclude_monitor_<engine>_N. PostgreSQL components now carry the _postgresql suffix for consistency. - Rename engine-specific connector/processor YAMLs for symmetry (dbi_dbload_postgresql.yaml, dbi_topsql_postgresql.yaml, transform_dbi_fix_start_time_postgresql.yaml); the connector and transform translators select the config by engine. - Add the dbi_scope transform processor (cloudwatch.source/solution) to all MySQL pipelines, matching the PostgreSQL implementation. - Use the shared named resourcedetection/opentelemetry processor. - Add the validateOttlSafe check to the unified Translate() so username and instance_name are validated for both engines. - Fix the host metrics process scraper to match the mysqld process (mysqld.*) when MySQL DBI is configured. - Remove TLS/ca_file from the MySQL schema and receiver; MySQL DBI is localhost-only and always connects with TLS disabled. - Fix the MySQL passfile test fixture to the pgpass-style format (host:port:database:username:password) and assert all seven DB Load metrics. - Regenerate golden YAMLs (mysql, postgres, combined configs).

…upport The CloudWatch Console (Cinch) creates separate SSM parameters for each workload configuration (e.g. one for database-insights-postgres and one for database-insights-mysql). When the agent loads multiple config files from the .d/ directory, the config merger needs to deep-merge the database_insights section so that both postgresql and mysql arrays coexist. Without this rule, the agent treats database_insights from two separate config sources as conflicting values and drops one, causing missing log groups in CloudWatch. Register database_insights as a SectionMergeRule under the collect rule, matching the existing pattern for opentelemetry and collect.

- Move the complete 14-metric Top SQL connector config (dbi_topsql_mysql.yaml) into this PR. The full metric set was previously committed in the MySQL workload-detection PR by mistake, which left this PR's embedded config with only 2 metrics while the golden YAML had 14 (mismatch that failed the translation unit tests). All 14 metrics match what the mysqlreceiver publishes on db.server.top_query events. - Remove the user.name attribute from all Top SQL metrics: top queries come from events_statements_summary_by_digest, aggregated by digest and schema, so the receiver does not publish user.name on top_query events (validated against the forked mysqlreceiver RecordDbServerTopQueryEvent). - Remove the duplicate dbiMysqlKey variable in favor of the shared common.DatabaseInsightsMysqlKey. - Regenerate the MySQL golden YAML.

Update the test credential file to use the MySQL-native INI format (Option C) with required host, port, user, and password fields.

Points to amazon-contributing/opentelemetry-collector-contrib PR #577 which replaces pgpass format with .my.cnf INI format for MySQL DBI credential files.

The DB Load connector condition only matched processlist_command == "Query", missing prepared statement executions ("Execute") used by sysbench, ORMs, JDBC, and most real-world applications. This caused DB Load metrics to undercount active sessions. Replace the command-based filter with session.status != "idle" to match all active sessions regardless of command type.

…rics Add sum_rows_affected, sum_select_range_check, sum_sort_merge_passes, and sum_sort_range to dbi_topsql_mysql.yaml signaltometrics connector config. Top SQL metrics now emit 18 metrics per digest (was 14). Regenerated golden YAML test fixture.

# Conflicts: # go.mod # go.sum # translator/tocwconfig/sampleConfig/opentelemetry/combined_v1_v2_ec2_config.yaml # translator/tocwconfig/sampleConfig/opentelemetry/combined_v1_v2_eks_config.yaml # translator/tocwconfig/sampleConfig/opentelemetry/dbi_postgresql_config_linux.yaml # translator/tocwconfig/tocwconfig_unix_test.go # translator/translate/otel/common/common.go # translator/translate/otel/pipeline/opentelemetry/databaseinsights/translator.go # translator/translate/otel/pipeline/opentelemetry/databaseinsights/translator_test.go # translator/translate/otel/pipeline/opentelemetry/databaseinsights/translators.go # translator/translate/otel/pipeline/opentelemetry/databaseinsights/translators_test.go # translator/translate/otel/pipeline/opentelemetry/hostmetrics/translator_test.go # translator/translate/otel/processor/transformprocessor/translate.go

The mysql DBI translator relied on the receiver's default metric enablement, which leaves mysql.table.size, mysql.replica.sql_delay, and mysql.replica.time_behind_source disabled. Enable them explicitly in the translator (matching the postgres translator pattern) so Database Insights collects table size and replication lag. Regenerated the dbi_mysql golden config accordingly.

…severity

Point the mysqlreceiver replace at the DBI metric-additions build and enable the DBI-required MySQL metrics in the translator: - mysql.deadlocks - mysql.connection.count, mysql.connection.errors, mysql.max_used_connections, mysql.commands, mysql.query.count - mysql.history_list_length, mysql.active_transactions - process.threads (DBI hostmetrics process scraper) Regenerated affected golden configs.

Add MySQL database_insights configuration alongside PostgreSQL in the combined sample configs to ensure both engines are represented in multi-feature configs: - Add mysql instance config to combined_v1_v2_ec2_config.json - Add mysql instance config to combined_v1_v2_eks_config.json - Regenerate golden YAML files with all MySQL components: - Receivers: mysql/metrics_0, mysql/events_0, filelog/mysql_0 - Connectors: count/dbi_dbload_mysql, signaltometrics/dbi_topsql_mysql - Processors: filter, transform, scope processors for mysql - Pipelines: logs/dbi_mysql_*, metrics/dbi_mysql_0 - Hostmetrics: process scraper now includes mysqld.* Both combined configs now demonstrate complete dual-engine DBI setups.

changelog references

…tests The MySQL receiver validates that passfiles have 0600 or 0400 permissions for security. Git doesn't preserve file permissions beyond the executable bit, so checked-out files default to 0644 in CI, causing test failures. Add os.Chmod(0600) calls in TestCombinedV1V2EC2Config and TestCombinedV1V2EKSConfig before config translation to ensure the .mysql_credentials testdata file has the required restrictive permissions. This matches the existing fix in TestDBIMySQLConfigLinux and ensures tests pass reliably in CI and local development environments.

Adjust MySQL query sample configuration to optimize resource usage: - Increase MaxRowsPerQuery from 500 to 5000 (aligns with PostgreSQL) - Decrease MaxQuerySampleCount from 5000 to 1000 (conservative limit) This balances query plan collection with CloudWatch Logs limits.

…e-translator

…386b) Update go.mod to point to the latest commit on the upstream dbi-mysql branch which includes PR #617 (InnoDB deadlocks and transaction metrics).

…erySampleCollection.MaxRowsPerQuery from 5000 to 500 to match PostgreSQL - Change TopQueryCollection.MaxQuerySampleCount from 1000 to 5000 to match PostgreSQL - Make TopQueryCollection.CollectionInterval configurable via WithTopQueryInterval option - Set 60s interval for 'events' receiver - Add test for custom interval configuration

- Log decode errors to stderr for visibility when MySQL config is malformed - Return empty slice instead of nil to allow PostgreSQL instances to still be processed - Addresses PR review feedback about error handling

This merge brings in updates from main and resolves conflicts: - Updated MySQL DBI pipeline translator to support both MySQL and PostgreSQL engines - Fixed translateMetrics() to use engine-specific receiver logic - Fixed translateLogToMetrics() and translateRawEvents() for MySQL support - Resolved duplicate receivers in combined_v1_v2_eks_config.yaml - Fixed syntax error in translators_test.go (missing closing brace) - Updated go.mod and go.sum with latest dependencies All tests pass and lint is clean.

…e-translator

…mysql-pipeline-translator

Run make fmt fmt-sh to fix formatting issues detected by CI.

github-actions · 2026-08-11T17:09:35Z

Binary Size Report

linux/amd64

Binary	PR	vs `main` (`486f0c6`)	vs `v1.300072.0`
amazon-cloudwatch-agent	195.9 MB	${\color{red}▲}$ +2.7 MB (+1.4%)	${\color{red}▲}$ +2.7 MB (+1.4%)
amazon-cloudwatch-agent-config-wizard	2.0 MB	+0 B	+0 B
config-downloader	2.0 MB	+0 B	+0 B
config-translator	2.0 MB	+0 B	+0 B
start-amazon-cloudwatch-agent	2.5 MB	+0 B	+0 B
workload-discovery	3.0 MB	+0 B	+0 B
Total	207.5 MB	${\color{red}▲}$ +2.7 MB (+1.3%)	${\color{red}▲}$ +2.7 MB (+1.3%)

linux/amd64 amazon-cloudwatch-agent (last 9 main commits + this PR)

 196 ┤                                        
     ┤                                    ███ 
     ┤                                    ███ 
     ┤                                    ███ 
     ┤                                    ███ 
     ┤                                    ███ 
     ┤                                    ███ 
     ┤                                    ███ 
 193 ┤▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ▄▄▄ ███ 
 MB  └────────────────────────────────────────
      2167834                 v1.300072.0 PR

Notable changes:

+2.7 MB at PR

linux/arm64

Binary	PR	vs `main` (`486f0c6`)	vs `v1.300072.0`
amazon-cloudwatch-agent	179.7 MB	${\color{red}▲}$ +2.6 MB (+1.5%)	${\color{red}▲}$ +2.6 MB (+1.5%)
amazon-cloudwatch-agent-config-wizard	2.0 MB	+0 B	+0 B
config-downloader	2.0 MB	+0 B	+0 B
config-translator	2.0 MB	+0 B	+0 B
start-amazon-cloudwatch-agent	2.4 MB	+0 B	+0 B
workload-discovery	2.9 MB	+0 B	+0 B
Total	191.0 MB	${\color{red}▲}$ +2.6 MB (+1.4%)	${\color{red}▲}$ +2.6 MB (+1.4%)

windows/amd64

Binary	PR	vs `main` (`486f0c6`)	vs `v1.300072.0`
amazon-cloudwatch-agent.exe	197.3 MB	${\color{red}▲}$ +1.2 MB (+0.6%)	${\color{red}▲}$ +1.2 MB (+0.6%)
amazon-cloudwatch-agent-config-wizard.exe	2.1 MB	+0 B	+0 B
config-downloader.exe	2.1 MB	+0 B	+0 B
config-translator.exe	2.1 MB	+0 B	+0 B
start-amazon-cloudwatch-agent.exe	2.3 MB	+0 B	+0 B
workload-discovery.exe	2.9 MB	+0 B	+0 B
Total	209.0 MB	${\color{red}▲}$ +1.2 MB (+0.6%)	${\color{red}▲}$ +1.2 MB (+0.6%)

Investigating size changes

Use go-size-analyzer to compare binaries:

GOEXPERIMENT=jsonv2 go install github.com/Zxilly/go-size-analyzer/cmd/gsa@latest
gsa diff --old <baseline-binary> --new <new-binary>

- Add error logging to PostgreSQL config decoder (similar to MySQL) - Fix receiver() function to properly handle PostgreSQL with conditional check - Remove duplicate combined_v1_v2_ec2_config_main.yaml file - Change instance name from 'pentest-mysql' to 'mysql-instance' in test configs - Keep per-instance scope processors for consistency and future flexibility

…fan-out The DBI count and signaltometrics connectors were created with engine-scoped IDs (count/dbi_dbload_<engine>), so all instances of an engine shared a single connector whose output was consumed by every per-instance metrics pipeline. Each pipeline unconditionally set db.instance.name, cross-tagging active_sessions/top-query datapoints with every configured instance name (a cartesian product across instances) for mysql and postgresql. Make the connector IDs per-instance (append the instance index) in both translateMetrics and translateLogToMetrics so each instance's stream is isolated end to end.

- Add MySQL-specific case in excludeMonitorFilter for consistency with PostgreSQL pattern - MySQL only checks user.name attribute (no separate role attribute like PostgreSQL) - Add test case TestDbiExcludeMonitorMySQL to verify MySQL filter condition - Filter condition: attributes["user.name"] == configured_username - This ensures MySQL monitoring sessions are filtered from DB Load metrics

These metrics are disabled by default in the upstream MySQL receiver but are needed for database insights. This change: - Enables both metrics in the MySQL translator - Updates golden YAML files (dbi_mysql_config_linux.yaml, combined_v1_v2_ec2_config.yaml, combined_v1_v2_eks_config.yaml) - Both metrics_0 and events_0 receivers now have these metrics enabled

Kirsty Larsen added 9 commits June 24, 2026 15:58

Add MySQL config schema definition

137120b

Add mysql[] array schema to database_insights in schema.json: - endpoint, instance_name, username, password_file - tls.ca_file for TLS configuration - logs.file_path for server log ingestion

test: Update .mysql_credentials test fixture to .my.cnf INI format

4c84ea5

Update the test credential file to use the MySQL-native INI format (Option C) with required host, port, user, and password fields.

Klarsen04 requested a review from a team as a code owner July 10, 2026 15:43

Klarsen04 added the ready for testing Indicates this PR is ready for integration tests to run label Jul 10, 2026

Klarsen04 force-pushed the larkirs/mysql-pipeline-translator branch 2 times, most recently from 28af3da to be7ef57 Compare July 14, 2026 19:10

Kirsty Larsen added 2 commits July 15, 2026 20:01

chore: Update mysqlreceiver replace to .my.cnf INI format commit

15156a6

Points to amazon-contributing/opentelemetry-collector-contrib PR #577 which replaces pgpass format with .my.cnf INI format for MySQL DBI credential files.

Klarsen04 force-pushed the larkirs/mysql-pipeline-translator branch from be7ef57 to f7367a8 Compare July 15, 2026 20:01

Kirsty Larsen added 5 commits July 20, 2026 20:06

chore: Update mysqlreceiver replace to latest commit c7001ee3110e

33f7e00

fix(dbi): parse MySQL server log lines for multiline, timestamp, and …

5f2550a

…severity

Klarsen04 force-pushed the larkirs/mysql-pipeline-translator branch from 190b830 to 5f2550a Compare July 23, 2026 15:52

aws deleted a comment from github-actions Bot Jul 23, 2026

Klarsen04 force-pushed the larkirs/mysql-pipeline-translator branch from c91ca57 to b944c8a Compare July 23, 2026 19:31

Klarsen04 force-pushed the larkirs/mysql-pipeline-translator branch from b944c8a to b3163f4 Compare July 23, 2026 22:09

aws deleted a comment from github-actions Bot Jul 23, 2026

Kirsty Larsen added 3 commits July 24, 2026 18:43

chore: update mysqlreceiver to latest commit (bed4560687ee) with PR #617

0ea2209

changelog references

Kirsty Larsen added 3 commits July 31, 2026 18:35

Merge remote-tracking branch 'origin/main' into larkirs/mysql-pipelin…

3660a9e

…e-translator

chore(dbi): update mysqlreceiver to latest dbi-mysql branch (83b5027c…

9a48cd1

…386b) Update go.mod to point to the latest commit on the upstream dbi-mysql branch which includes PR #617 (InnoDB deadlocks and transaction metrics).