metadata.yaml

# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

public_url: "https://cloud.google.com/stackdriver/docs/solutions/agents/ops-agent/third-party/mysql"
app_url: "http://www.mysql.com/"
short_name: MySQL
long_name: MySQL
logo_path: /images/launcher/logos/mysql.png # supplied by google technical writer
description: |-
  The MySQL/MariaDB integration collects performance metrics related to
  InnoDB, the buffer pool, and various other operations. It also collects general,
  error, and slow-query logs and parses them into a JSON payload. Error logs are
  parsed for their error code and subsystem. Slow-query logs are parsed into
  key-value pairs that describe the performance of a query, including query time
  and rows examined.
configure_integration: |-
  MariaDB is a community-developed, commercially supported fork of the MySQL
  relational database management system (RDBMS). To collect logs and metrics for
  MariaDB, use the `mysql` receivers.

  The `mysql` receiver connects by default to a local MySQL/MariaDB
  server using a Unix socket and Unix authentication as the `root` user.
minimum_supported_agent_version:
  metrics: 2.33.0
  logging: 2.33.0
supported_operating_systems: linux
platforms_to_skip:
  # MySQL5.7 is not supported on various distros.
  - suse-cloud:sles-12
  - suse-cloud:sles-15
  - suse-cloud:sles-15-arm64
  - suse-sap-cloud:sles-12-sp5-sap
  - rocky-linux-cloud:rocky-linux-8
  - rocky-linux-cloud:rocky-linux-8-optimized-gcp
  - rocky-linux-cloud:rocky-linux-8-optimized-gcp-arm64
  - rocky-linux-cloud:rocky-linux-9
  - rocky-linux-cloud:rocky-linux-9-optimized-gcp
  - rocky-linux-cloud:rocky-linux-9-arm64
  - rocky-linux-cloud:rocky-linux-9-optimized-gcp-arm64
  - debian-cloud:debian-11
  - debian-cloud:debian-12
  - debian-cloud:debian-12-arm64
  - ml-images:common-gpu-debian-11-py310
  - ubuntu-os-cloud:ubuntu-2004-lts
  - ubuntu-os-cloud:ubuntu-2004-lts-arm64
  - ubuntu-os-cloud:ubuntu-2204-lts
  - ubuntu-os-cloud:ubuntu-2204-lts-arm64
  - ubuntu-os-cloud:ubuntu-2404-lts-amd64
  - ubuntu-os-cloud:ubuntu-2404-lts-arm64
  - ubuntu-os-cloud:ubuntu-2410-amd64
  - ubuntu-os-cloud:ubuntu-minimal-2410-amd64
  - ubuntu-os-cloud:ubuntu-2410-arm64
  - ubuntu-os-cloud:ubuntu-minimal-2410-arm64
  - ubuntu-os-cloud:ubuntu-2504-lts-amd64
  - ubuntu-os-cloud:ubuntu-2504-lts-arm64
supported_app_version: ["5.7", "8.0"]
expected_metrics:
  - type: workload.googleapis.com/mysql.buffer_pool_data_pages
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: status
        value_regex: dirty|clean
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.buffer_pool_limit
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.buffer_pool_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: read_ahead|read_ahead_evicted|read_ahead_rnd|read_requests|reads|wait_free|write_requests
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.buffer_pool_page_flushes
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.buffer_pool_pages
    value_type: DOUBLE
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: data|free|misc
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.buffer_pool_size
    value_type: DOUBLE
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: clean|dirty
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.commands
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: command
        value_regex: delete|insert|select|update
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.double_writes
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: writes|pages_written
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.handlers
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: commit|delete|discover|lock|mrr_init|prepare|read_first|read_key|read_last|read_next|read_prev|read_rnd|read_rnd_next|rollback|savepoint|savepoint_rollback|update|write
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.locks
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: immediate|waited
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.log_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: requests|waits|writes
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: fsyncs|reads|writes
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.page_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: created|read|written
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.replica.time_behind_source
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.replica.sql_delay
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.row_locks
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: time|waits
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.row_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: deleted|inserted|read|updated
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.sorts
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: merge_passes|range|rows|scan
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
  - type: workload.googleapis.com/mysql.threads
    value_type: DOUBLE
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: cached|connected|created|running
      - name: instrumentation_source
        value_regex: agent.googleapis.com/mysql
    representative: true
expected_logs:
  # Mysql 5.7 error logs go to syslog by default
  # - log_name: mysql_error
  #   fields:
  #     - name: jsonPayload.level
  #       value_regex: System
  #       type: string
  #       description: 'Log entry level'
  #       optional: true
  #     - name: jsonPayload.message
  #       value_regex: .*InnoDB initialization has started.*
  #       type: string
  #       description: 'Log message'
  #     - name: jsonPayload.subsystem
  #       value_regex: InnoDB
  #       type: string
  #       description: 'MySQL subsystem where the log originated'
  #     - name: jsonPayload.tid
  #       type: number
  #       description: 'Thread ID where the log originated'
  #     - name: jsonPayload.errorCode
  #       type: string
  #       description: 'MySQL error code associated with the log'
  #     - name: severity
  #       type: string
  #       description: ''
  - log_name: mysql_general
    fields:
      - name: jsonPayload.message
        value_regex: .*select table_catalog, table_schema, table_name from information_schema.tables.*
        type: string
        description: 'Log of the database action'
      - name: jsonPayload.command
        value_regex: Query
        type: string
        description: 'Type of database action being logged'
      - name: jsonPayload.tid
        type: number
        description: 'Thread ID where the log originated'
      - name: severity
        type: string
        description: ''
  - log_name: mysql_slow
    fields:
      - name: jsonPayload.message
        value_regex: (?s).*select table_catalog, table_schema, table_name from information_schema.tables.* # The (?s) part will make the . match with newline as well. See https://github.com/google/re2/blob/main/doc/syntax.txt#L65,L68
        type: string
        description: 'Full text of the query'
      - name: jsonPayload.user
        value_regex: root
        type: string
        description: 'User that executed the query'
      - name: jsonPayload.database
        value_regex: root
        type: string
        description: 'Database where the query was executed'
      - name: jsonPayload.host
        value_regex: localhost
        type: string
        description: 'Host of the database instance'
      - name: jsonPayload.ipAddress
        type: string
        description: 'Address of the database instance'
        optional: true
      - name: jsonPayload.tid
        type: number
        description: 'Thread ID where the query was logged'
      - name: jsonPayload.queryTime
        type: number
        description: 'The statement execution time in seconds'
      - name: jsonPayload.lockTime
        type: number
        description: 'The time to acquire locks in seconds'
      - name: jsonPayload.rowsSent
        type: number
        description: 'The number of rows sent to the client'
      - name: jsonPayload.rowsExamined
        type: number
        description: 'The number of rows examined by the server layer'
      - name: severity
        type: string
        description: ''
      - name: jsonPayload.level
        type: string
        description: Log entry level
        optional: true
configuration_options:
  logs:
    - type: mysql_error
      fields:
        - name: type
          default: null
          description: This value must be `mysql_error`.
        - name: include_paths
          default: '[/var/log/mysqld.log, /var/log/mysql/mysqld.log, /var/log/mysql/error.log]'
          description: A list of filesystem paths to read by tailing each file. A wild card (`*`) can be used in the paths; for example, `/var/log/mysql/*.log`.
        - name: exclude_paths
          default: null
          description: A list of filesystem path patterns to exclude from the set matched by `include_paths`.
        - name: record_log_file_path
          default: false
          description: If set to `true`, then the path to the specific file from which the log record was obtained appears in the output log entry as the value of the `agent.googleapis.com/log_file_path` label. When using a wildcard, only the path of the file from which the record was obtained is recorded.
        - name: wildcard_refresh_interval
          default: 60s
          description: The interval at which wildcard file paths in `include_paths` are refreshed. Given as a [time duration](https://pkg.go.dev/time#ParseDuration), for example `30s` or `2m`. This property might be useful under high logging throughputs where log files are rotated faster than the default interval.
    - type: mysql_general
      fields:
        - name: type
          default: null
          description: This value must be `mysql_general`.
        - name: include_paths
          default: '[/var/lib/mysql/${HOSTNAME}.log]'
          description: A list of filesystem paths to read by tailing each file. A wild card (`*`) can be used in the paths.
        - name: exclude_paths
          default: null
          description: A list of filesystem path patterns to exclude from the set matched by `include_paths`.
        - name: record_log_file_path
          default: false
          description: If set to `true`, then the path to the specific file from which the log record was obtained appears in the output log entry as the value of the `agent.googleapis.com/log_file_path` label. When using a wildcard, only the path of the file from which the record was obtained is recorded.
        - name: wildcard_refresh_interval
          default: 60s
          description: The interval at which wildcard file paths in `include_paths` are refreshed. Given as a [time duration](https://pkg.go.dev/time#ParseDuration), for example `30s` or `2m`. This property might be useful under high logging throughputs where log files are rotated faster than the default interval.
    - type: mysql_slow
      fields:
        - name: type
          default: null
          description: This value must be `mysql_slow`.
        - name: include_paths
          default: '[/var/lib/mysql/${HOSTNAME}-slow.log]'
          description: A list of filesystem paths to read by tailing each file. A wild card (`*`) can be used in the paths.
        - name: exclude_paths
          default: null
          description: A list of filesystem path patterns to exclude from the set matched by `include_paths`.
        - name: record_log_file_path
          default: false
          description: If set to `true`, then the path to the specific file from which the log record was obtained appears in the output log entry as the value of the `agent.googleapis.com/log_file_path` label. When using a wildcard, only the path of the file from which the record was obtained is recorded.
        - name: wildcard_refresh_interval
          default: 60s
          description: The interval at which wildcard file paths in `include_paths` are refreshed. Given as a [time duration](https://pkg.go.dev/time#ParseDuration), for example `30s` or `2m`. This property might be useful under high logging throughputs where log files are rotated faster than the default interval.
  metrics:
    - type: mysql
      fields:
        - name: type
          default: null
          description: This value must be `mysql`.
        - name: endpoint
          default: /var/run/mysqld/mysqld.sock
          description: The `hostname:port` or Unix socket path starting with `/` used to connect to the MySQL server.
        - name: username
          default: root
          description: The username used to connect to the server.
        - name: password
          default: null
          description: The password used to connect to the server.
        - name: collection_interval
          default: 60s
          description: A [time duration](https://pkg.go.dev/time#ParseDuration) value, such as `30s` or `5m`.