conf.yaml.example

## All options defined here are available to all instances.
#
init_config:

    ## @param global_custom_queries - list of mappings - optional
    ## See `custom_queries` defined below.
    ##
    ## Global custom queries can be applied to all instances using the
    ## `use_global_custom_queries` setting at the instance level.
    #
    # global_custom_queries:
    #   - query: <QUERY>
    #     columns: <COLUMNS>
    #     tags: <TAGS>

    ## @param service - string - optional
    ## Attach the tag `service:<SERVICE>` to every metric, event, and service check emitted by this integration.
    ##
    ## Additionally, this sets the default `service` for every log source.
    #
    # service: <SERVICE>

## Every instance is scheduled independently of the others.
#
instances:

    ## @param server - string - required
    ## The hostname used to connect to the system.
    #
  - server: <SERVER>

    ## @param port - integer - optional - default: 8123
    ## The port used to connect to the system.
    ## This integration uses the HTTP interface, so the default is 8123 (HTTP port).
    ## Note: Port 9000 is for ClickHouse's native TCP protocol, which is not used by this integration.
    #
    # port: 8123

    ## @param username - string - optional - default: default
    ## The database user to authenticate as.
    #
    # username: default

    ## @param password - string - optional - default: 
    ## The password of `username`.
    #
    # password: <PASSWORD>

    ## @param db - string - optional - default: default
    ## The database to connect to.
    #
    # db: <DB>

    ## @param connect_timeout - integer - optional - default: 10
    ## The timeout for connecting to the `server`.
    #
    # connect_timeout: 10

    ## @param read_timeout - integer - optional - default: 10
    ## The timeout for reading from the `server`.
    #
    # read_timeout: 10

    ## @param compression - string - optional
    ## The compression algorithm to use. The default is no compression.
    ## If br is specified, the brotli library must be installed separately.
    ##
    ## Valid values are:
    ##   - lz4
    ##   - zstd
    ##   - br
    ##   - gzip
    #
    # compression: <COMPRESSION>

    ## @param tls_ca_cert - string - optional
    ## The path to the CA certificate file.
    #
    # tls_ca_cert: <TLS_CA_CERT>

    ## @param tls_verify - boolean - optional - default: false
    ## Whether or not to connect securely using TLS. The server must also support this.
    #
    # tls_verify: false

    ## @param verify - boolean - optional - default: true
    ## Indicates if a certificate is required and if it will be validated after a connection is established.
    #
    # verify: true

    ## @param dbm - boolean - optional - default: false
    ## Enable Database Monitoring (DBM) to collect query samples, metrics, and completions.
    ## This feature provides deep observability into query performance.
    #
    # dbm: false

    ## Controls how the database is identified. Each unique value of this identifier will appear in DBM as a separate
    ## billable instance.
    ##
    ## The default value is "$server:$port:$db" which uniquely identifies a ClickHouse database by its server, port,
    ## and database name.
    ##
    ## This value will be used as-is for the display name of the instance but will be normalized
    ## when applied as the `database_instance` tag. Please see https://docs.datadoghq.com/getting_started/tagging/
    ## for more details on Datadog tag normalization.
    #
    # database_identifier:

        ## @param template - string - optional - default: $server:$port:$db
        ## The template string for the database identifier. Supports variable substitution using $variable syntax.
        ## Available variables: $server, $port, $db, plus any custom tags (e.g., $env, $region).
        #
        # template: $env-$server:$port:$db

    ## @param single_endpoint_mode - boolean - optional - default: false
    ## Set to `true` when connecting through a single endpoint for ClickHouse Cloud.
    #
    # single_endpoint_mode: false

    ## Configure collection of database samples snapshots from system.processes
    #
    # query_samples:

        ## @param enabled - boolean - optional - default: true
        ## Enable collection of database samples snapshots. Requires `dbm: true`.
        ## Samples snapshots show currently executing queries and connection counts.
        #
        # enabled: true

        ## @param collection_interval - number - optional - default: 1
        ## Set the samples snapshot collection interval (in seconds). Each collection involves a single query to
        ## `system.processes` to capture currently executing queries.
        #
        # collection_interval: 1

        ## @param payload_row_limit - integer - optional - default: 1000
        ## Set the maximum number of active sessions to include in each samples snapshot.
        #
        # payload_row_limit: 1000

    ## Configure collection of query metrics
    #
    # query_metrics:

        ## @param enabled - boolean - optional - default: true
        ## Enable collection of query metrics. Requires `dbm: true`.
        #
        # enabled: true

        ## @param collection_interval - number - optional - default: 10
        ## Set the query metric collection interval (in seconds). Each collection involves a single query to
        ## `system.query_log`. If a non-default value is chosen then that exact same value must be used for *every*
        ## check instance. Running different instances with different collection intervals is not supported.
        #
        # collection_interval: 10

    ## Configure collection of query completions from system.query_log
    #
    # query_completions:

        ## @param enabled - boolean - optional - default: true
        ## Enable collection of query completions. Requires `dbm: true`.
        ## These samples represent individual completed queries and appear on the DBM Query Samples page.
        #
        # enabled: true

        ## @param collection_interval - number - optional - default: 10
        ## Set the query completions collection interval (in seconds).
        ## Lower values show more recent queries but increase collection overhead.
        #
        # collection_interval: 10

        ## @param samples_per_hour_per_query - number - optional - default: 15
        ## Set the maximum number of samples to collect per hour per unique query signature.
        ## This rate limiting prevents excessive data collection for frequently executed queries.
        #
        # samples_per_hour_per_query: 15

    ## Configure collection of query errors from system.query_log
    #
    # query_errors:

        ## @param enabled - boolean - optional - default: true
        ## Enable collection of query errors. Requires `dbm: true`.
        ## Collects ExceptionBeforeStart and ExceptionWhileProcessing events, which include
        ## exception message, error code, and stack trace.
        #
        # enabled: true

        ## @param collection_interval - number - optional - default: 10
        ## Set the query errors collection interval (in seconds).
        #
        # collection_interval: 10

        ## @param samples_per_hour_per_query - number - optional - default: 60
        ## Set the maximum number of error samples to collect per hour per unique query signature.
        #
        # samples_per_hour_per_query: 60

    ## @param only_custom_queries - boolean - optional - default: false
    ## Set this parameter to `true` if you want to skip the integration's default metrics collection.
    ## Only metrics specified in `custom_queries` will be collected.
    #
    # only_custom_queries: false

    ## @param use_global_custom_queries - string - optional - default: true
    ## How `global_custom_queries` should be used for this instance. There are 3 options:
    ##
    ## 1. true - `global_custom_queries` override `custom_queries`.
    ## 2. false - `custom_queries` override `global_custom_queries`.
    ## 3. extend - `global_custom_queries` are used in addition to any `custom_queries`.
    #
    # use_global_custom_queries: 'true'

    ## @param custom_queries - list of mappings - optional
    ## Each query must have 2 fields, and can have a third optional field:
    ##
    ## 1. query - The SQL to execute. It can be a simple statement or a multi-line script.
    ##     Use the pipe `|` if you require a multi-line script.
    ## 2. columns - The list representing each column, ordered sequentially from left to right.
    ##     The number of columns must equal the number of columns returned in the query.
    ##     There are 2 required pieces of data:
    ##       1. name - The suffix to append to `<INTEGRATION>.` to form
    ##           the full metric name. If `type` is a `tag` type, this column is considered a tag and applied
    ##           to every metric collected by this particular query.
    ##       2. type - The submission method (gauge, monotonic_count, etc.).
    ##           This can also be set to the following `tag` types to tag each metric in the row with the name
    ##           and value of the item in this column:
    ##             1. tag - This is the default tag type
    ##             2. tag_list - This allows multiple values to be attached to the tag name. For example: 
    ##                 ```
    ##                 query = {
    ##                   "name": "example",
    ##                   "query": "...",
    ##                   "columns": [
    ##                     {"name": "server_tag", "type": "tag_list"},
    ##                     {"name": "foo", "type": "gauge"},
    ##                   ]
    ##                 }
    ##                 ```
    ##                 May result in:
    ##                 ```
    ##                 gauge("foo", tags=["server_tag:us", "server_tag:primary", "server_tag:default"])
    ##                 gauge("foo", tags=["server_tag:eu"])
    ##                 gauge("foo", tags=["server_tag:eu", "server_tag:primary"])
    ##                 ```
    ##             3. tag_not_null - This only sets tags in the metric if the value is not null
    ##           You can use the `count` type to perform aggregation for queries that return multiple rows with
    ##           the same or no tags.
    ##     Columns without a name are ignored. To skip a column, enter:
    ##     ```
    ##       - {}
    ##     ```
    ## 3. tags (optional) - A list of tags to apply to each metric.
    ## 4. collection_interval (optional) - The frequency at which to collect the metrics.
    ##     If collection_interval is not set, the query will be run every check run.
    ##     If the collection interval is less than check collection interval, the query will be run every check
    ##     run.
    ##     If the collection interval is greater than check collection interval, the query will NOT BE RUN
    ##     exactly at the collection interval.
    ##     The query will be run at the next check run after the collection interval has passed.
    ## 5. metric_prefix (optional) - The prefix to apply to each metric.
    #
    # custom_queries:
    #   - query: SELECT foo, COUNT(*) FROM table.events GROUP BY foo
    #     columns:
    #     - name: foo
    #       type: tag
    #     - name: event.total
    #       type: gauge
    #     tags:
    #     - test:clickhouse
    #     metric_prefix: clickhouse

    ## @param tags - list of strings - optional
    ## A list of tags to attach to every metric and service check emitted by this instance.
    ##
    ## Learn more about tagging at https://docs.datadoghq.com/tagging
    #
    # tags:
    #   - <KEY_1>:<VALUE_1>
    #   - <KEY_2>:<VALUE_2>

    ## @param service - string - optional
    ## Attach the tag `service:<SERVICE>` to every metric, event, and service check emitted by this integration.
    ##
    ## Overrides any `service` defined in the `init_config` section.
    #
    # service: <SERVICE>

    ## @param min_collection_interval - number - optional - default: 15
    ## This changes the collection interval of the check. For more information, see:
    ## https://docs.datadoghq.com/developers/write_agent_check/#collection-interval
    #
    # min_collection_interval: 15

    ## @param empty_default_hostname - boolean - optional - default: false
    ## This forces the check to send metrics with no hostname.
    ##
    ## This is useful for cluster-level checks.
    #
    # empty_default_hostname: false

    ## @param metric_patterns - mapping - optional
    ## A mapping of metrics to include or exclude, with each entry being a regular expression.
    ##
    ## Metrics defined in `exclude` will take precedence in case of overlap.
    #
    # metric_patterns:
    #   include:
    #   - <INCLUDE_REGEX>
    #   exclude:
    #   - <EXCLUDE_REGEX>

## Log Section
##
## type - required - Type of log input source (tcp / udp / file / windows_event).
## port / path / channel_path - required - Set port if type is tcp or udp.
##                                         Set path if type is file.
##                                         Set channel_path if type is windows_event.
## source  - required - Attribute that defines which integration sent the logs.
## encoding - optional - For file specifies the file encoding. Default is utf-8. Other
##                       possible values are utf-16-le and utf-16-be.
## service - optional - The name of the service that generates the log.
##                      Overrides any `service` defined in the `init_config` section.
## tags - optional - Add tags to the collected logs.
##
## Discover Datadog log collection: https://docs.datadoghq.com/logs/log_collection/
#
# logs:
#   - source: clickhouse
#     type: file
#     path: /var/log/clickhouse-server/clickhouse-server.log
#     log_processing_rules:
#     - type: multi_line
#       name: log_start_with_date
#       pattern: \d{4}\.\d{2}\.\d{2}
#   - source: clickhouse
#     type: file
#     path: /var/log/clickhouse-server/clickhouse-server.err.log
#     log_processing_rules:
#     - type: multi_line
#       name: log_start_with_date
#       pattern: \d{4}\.\d{2}\.\d{2}