integration_test/third_party_apps_test/applications/mysql/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 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: |-
  The `mysql` receiver connects by default to a local MySQL
  server using a Unix socket and Unix authentication as the `root` user.
minimum_supported_agent_version:
  metrics: 2.32.0
  logging: 2.5.0
supported_operating_systems: linux
platforms_to_skip:
  # MySQL is not currently supported on various distros.
  - debian-cloud:debian-12
  - debian-cloud:debian-12-arm64
  - suse-cloud:sles-12
  - suse-cloud:sles-15-arm64
  - suse-sap-cloud:sles-12-sp5-sap
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
  - type: workload.googleapis.com/mysql.buffer_pool_limit
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - 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
  - type: workload.googleapis.com/mysql.buffer_pool_page_flushes
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
  - 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
  - type: workload.googleapis.com/mysql.buffer_pool_size
    value_type: DOUBLE
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: clean|dirty
  - type: workload.googleapis.com/mysql.commands
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: command
        value_regex: delete|insert|select|update
  - type: workload.googleapis.com/mysql.double_writes
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: writes|pages_written
  - 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
  - type: workload.googleapis.com/mysql.locks
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: immediate|waited
  - type: workload.googleapis.com/mysql.log_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: requests|waits|writes
  - type: workload.googleapis.com/mysql.operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: fsyncs|reads|writes
  - type: workload.googleapis.com/mysql.page_operations
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: operation
        value_regex: created|read|written
  - type: workload.googleapis.com/mysql.replica.time_behind_source
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/mysql.replica.sql_delay
    value_type: INT64
    kind: GAUGE
    monitored_resources: [gce_instance]
  - type: workload.googleapis.com/mysql.row_locks
    value_type: INT64
    kind: CUMULATIVE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: time|waits
  - 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
  - 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
  - type: workload.googleapis.com/mysql.threads
    value_type: DOUBLE
    kind: GAUGE
    monitored_resources: [gce_instance]
    labels:
      - name: kind
        value_regex: cached|connected|created|running
    representative: true
expected_logs:
  - 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: jsonPayload.errorNumber
        type: number
        description: 'The statement error number, or 0 if no error occurred'
        notes:
          - &log_slow_extra_note These fields are only provided if the `log_slow_extra` system variable is set to `'ON'`. This variable is available as of MySQL 8.0.14.
      - name: jsonPayload.killed
        type: number
        description: 'If the statement was terminated, the error number indicating why, or 0 if the statement terminated normally'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.bytesReceived
        type: number
        description: 'The number of bytes received from all clients'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.bytesSent
        type: number
        description: 'The number of bytes sent to all clients'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readFirst
        type: number
        description: 'The number of times the first entry in an index was read'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readLast
        type: number
        description: 'The number of requests to read the last key in an index'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readKey
        type: number
        description: 'The number of requests to read a row based on a key'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readNext
        type: number
        description: 'The number of requests to read the next row in key order'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readPrev
        type: number
        description: 'The number of requests to read the previous row in key order'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readRnd
        type: number
        description: 'The number of requests to read a row based on a fixed position'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.readRndNext
        type: number
        description: 'The number of requests to read the next row in the data file'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.sortMergePasses
        type: number
        description: 'The number of merge passes that the sort algorithm has had to do'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.sortRangeCount
        type: number
        description: 'The number of sorts that were done using ranges'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.sortRows
        type: number
        description: 'The number of sorted rows'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.sortScanCount
        type: number
        description: 'The number of sorts that were done by scanning the table'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.createdTmpDiskTables
        type: number
        description: 'The number of internal on-disk temporary tables created by the server'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.createdTmpTables
        type: number
        description: 'The number of internal temporary tables created by the server'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.startTime
        type: string
        description: 'The statement execution start time'
        notes:
          - *log_slow_extra_note
      - name: jsonPayload.endTime
        type: string
        description: 'The statement execution end time'
        notes:
          - *log_slow_extra_note
      - name: severity
        type: string
        description: ''
      - name: jsonPayload.level
        type: string
        description: Log entry level
        optional: true
    notes:
      - For information about these fields, refer to the [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/slow-query-log.html).
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`.