Skip to main content

​
Sqlquery Receiver

Status Available in: contrib Maintainers: @dmitryax, @crobert-1 Source: opentelemetry-collector-contrib

​
Supported Telemetry

Logs Metrics

​
Overview

:construction: This receiver is in ALPHA. Behavior, configuration fields, and log or metric data model are subject to change.

​
Configuration

Connection Configuration (choose one approach): Option 1: Individual connection parameters (cannot be used when datasource is set):
  • host (required): The hostname or IP address of the database server.
    • For the sqlserver driver, an instance appended to the hostname (e.g. hostname1/instance1) will be parsed properly into this connection string: sqlserver://username:password@host:port/instance.
  • port (required, except optional for sqlserver): The port number of the database server.
  • database (required): The name of the database to connect to.
  • username (optional): The username for database authentication.
    • The username will be properly escaped and securely handled when building the connection string. Special characters (such as #, @, %, etc.) are automatically URL-encoded to ensure proper connection string formatting.
    • For mysql: No URL encoding is applied
  • password (optional): The password for database authentication. Supports environment variable substitution.
    • The password field supports sensitive value handling through environment variables or other secure value sources. Special characters (such as #, @, %, etc.) are automatically URL-encoded to ensure proper connection string formatting.
    • For mysql: No URL encoding is applied
  • additional_params (optional): Additional driver-specific connection parameters.
Option 2: Datasource string:
  • datasource (required): The datasource value passed to sql.Open. This value is used instead of the individual connection parameters listed above and does not perform any special character escaping. This is a driver-specific string usually consisting of at least a database name and connection information. This is sometimes referred to as the “connection string” in driver documentation. Examples:
    • clickhouse - clickhouse://username:userpassword@localhost:9000/default?dial_timeout=200ms&read_timeout=30s&max_execution_time=60
    • hdb - hdb://<USER>:<PASSWORD>@something.hanacloud.ondemand.com:443?TLSServerName=something.hanacloud.ondemand.com
    • mysql - username:user_password@tcp(localhost:3306)/db_name
    • oracle - oracle://username:user_password@localhost:1521/FREEPDB1
    • postgres - host=localhost port=5432 user=username password=user_password sslmode=disable
    • snowflake - username[:password]@<account_identifier>/dbname/schemaname[?param1=value&...&paramN=valueN]
    • sqlserver - sqlserver://username:user_password@localhost:1433?database=db_name
    • tds - tds://username:user_password@localhost:5000/db_name
Other configuration fields:
  • driver (required): The name of the database driver: one of postgres, mysql, snowflake, sqlserver, hdb (SAP HANA), oracle (Oracle DB), tds (SapASE/Sybase), clickhouse.
  • queries (required): A list of queries, where a query is a sql statement and one or more logs and/or metrics sections (details below).
  • collection_interval(optional): The time interval between query executions. Defaults to 10s.
  • initial_delay (default = 1s): defines how long this receiver waits before starting.
  • storage (optional, default ""): The ID of a storage extension to be used to track processed results.
  • telemetry (optional) Defines settings for the component’s own telemetry - logs, metrics or traces.
    • telemetry.logs (optional) Defines settings for the component’s own logs.
      • telemetry.logs.query (optional, default false) If set to true, every time a SQL query is run, the text of the query and the values of its parameters will be logged together with the debug log "Running query".
  • max_open_conn (optional, default 0): The maximumn number of open connections to the sql server. <= 0 means unlimited

​
Queries

A query consists of a sql statement and one or more logs and/or metrics section. At least one logs or one metrics section is required. Note that technically you can put both logs and metrics sections in a single query section, but it’s probably not a real world use case, as the requirements for logs and metrics queries are quite different. Additionally, each query section supports the following properties:
  • tracking_column (optional, default "") Applies only to logs. In case of a parameterized query, defines the column to retrieve the value of the parameter on subsequent query runs. See the below section Tracking processed results.
  • tracking_start_value (optional, default "") Applies only to logs. In case of a parameterized query, defines the initial value for the parameter. See the below section Tracking processed results.
  • attribute_columns(optional): a list of column names in the returned dataset used to set attributes on the signal. These attributes may be case-sensitive, depending on the driver (e.g. Oracle DB).

​
Example using datasource:

receivers:
  sqlquery:
    driver: postgres
    datasource: "host=localhost port=5432 user=postgres password=s3cr3t sslmode=disable"
    queries:
      - sql: "select * from my_logs where log_id > $$1"
        tracking_start_value: "10000"
        tracking_column: log_id
        logs:
          - body_column: log_body
      - sql: "select count(*) as count, genre from movie group by genre"
        metrics:
          - metric_name: movie.genres
            value_column: "count"

​
Example without using datasource:

receivers:
  sqlquery:
    driver: postgres
    host: localhost
    port: 5432
    user: postgres
    password: s3cr3t
    additional_params:
      sslmode: disable
    queries:
      - sql: "select * from my_logs where log_id > $$1"
        tracking_start_value: "10000"
        tracking_column: log_id
        logs:
          - body_column: log_body
      - sql: "select count(*) as count, genre from movie group by genre"
        metrics:
          - metric_name: movie.genres
            value_column: "count"

​
SQL Server example without using datasource:

receivers:
  sqlquery:
    driver: sqlserver
    host: localhost/instance
    user: sql_server
    password: s3cr3t
    additional_params:
      sslmode: disable
    queries:
      - sql: "select * from my_logs where log_id > $$1"
        tracking_start_value: "10000"
        tracking_column: log_id
        logs:
          - body_column: log_body
      - sql: "select count(*) as count, genre from movie group by genre"
        metrics:
          - metric_name: movie.genres
            value_column: "count"

​
Logs Queries

The logs section is in development.
  • body_column (required) defines the column to use as the log record’s body.
Tracking processed results
With the default configuration and a non-parameterized logs query like select * from my_logs, the receiver will run the same query every collection interval, which can cause reading the same rows over and over again, unless there’s an external actor removing the old rows from the my_logs table. To prevent reading the same rows on every collection interval, use a parameterized query like select * from my_logs where id_column > ?, together with the tracking_start_value and tracking_column configuration properties. The receiver will use the configured tracking_start_value as the value for the query parameter when running the query for the first time. After each query run, the receiver will store the value of the tracking_column from the last row of the result set and use it as the value for the query parameter on next collection interval. To prevent duplicate log downloads, make sure to sort the query results in ascending order by the tracking_column value. Note that the notation for the parameter depends on the database backend. For example in MySQL this is ?, in PostgreSQL this is $1, in Oracle this is any string identifier starting with a colon :, for example :my_parameter. Use the storage configuration property of the receiver to persist the tracking value across collector restarts.

​
Metrics queries

Each metrics section consists of a metric_name, a value_column, and additional optional fields. Each metric in the configuration will produce one OTel metric per row returned from its sql query.
  • metric_name(required): the name assigned to the OTel metric.
  • value_column(required): the column name in the returned dataset used to set the value of the metric’s datapoint. This may be case-sensitive, depending on the driver (e.g. Oracle DB).
  • data_type (optional): can be gauge or sum; defaults to gauge.
  • value_type (optional): can be int or double; defaults to int.
  • monotonic (optional): boolean; whether a cumulative sum’s value is monotonically increasing (i.e. never rolls over or resets); defaults to false.
  • aggregation (optional): only applicable for data_type=sum; can be cumulative or delta; defaults to cumulative.
  • description (optional): the description applied to the metric.
  • unit (optional): the units applied to the metric.
  • static_attributes (optional): static attributes applied to the metrics.
  • start_ts_column (optional): the name of the column containing the start timestamp, the value of which is applied to the metric’s start timestamp (otherwise the current time is used). Only applies if the metric is of type cumulative sum.
  • ts_column (optional): the name of the column containing the timestamp, the value of which is applied to the metric’s timestamp. This can be current timestamp depending upon the time of last recorded metric’s datapoint.
  • row_condition (optional): when set, only rows where the specified column equals the specified value are used to produce this metric. Rows that do not match are silently skipped. This is useful for pivot-style result sets where each row encodes a different metric (e.g. SHOW LISTS in pgbouncer).
    • column (required): the column name to evaluate.
    • value (required): the expected string value the column must equal for the row to be included.

​
Example

receivers:
  sqlquery:
    driver: postgres
    datasource: "host=localhost port=5432 user=postgres password=s3cr3t sslmode=disable"
    storage: file_storage
    queries:
      - sql: "select * from my_logs where log_id > $$1"
        tracking_start_value: "10000"
        tracking_column: log_id
        logs:
          - body_column: log_body
            attribute_columns: ["log_attribute_1", "log_attribute_2"]
      - sql: "select count(*) as count, genre from movie group by genre"
        metrics:
          - metric_name: movie.genres
            value_column: "count"
            attribute_columns: ["genre"]
            static_attributes:
              dbinstance: mydbinstance
Given a movie table with three rows:
namegenre
E.T.sci-fi
Star Warssci-fi
Die Hardaction
If there are two rows returned from the query select count(*) as count, genre from movie group by genre:
countgenre
2sci-fi
1action
then the above config will produce two metrics at each collection interval: 
Metric #0
Descriptor:
     -> Name: movie.genres
     -> DataType: Gauge
NumberDataPoints #0
Data point attributes:
     -> genre: STRING(sci-fi)
     -> dbinstance: STRING(mydbinstance)
Value: 2

Metric #1
Descriptor:
     -> Name: movie.genres
     -> DataType: Gauge
NumberDataPoints #0
Data point attributes:
     -> genre: STRING(action)
     -> dbinstance: STRING(mydbinstance)
Value: 1

​
Row Condition Example

Some databases expose pivot-style views where each row represents a different metric, identified by a name column. For example, pgbouncer’s SHOW LISTS command returns: 
     list      | items
---------------+-------
 databases     |     8
 pools         |     4
 users         |     2
 free_clients  |    25
 used_servers  |     5
Use row_condition to extract a single row as a dedicated metric: 
receivers:
  sqlquery:
    driver: postgres
    datasource: "host=pgbouncer port=5432 user=pgbouncer dbname=pgbouncer sslmode=disable"
    queries:
      - sql: "SHOW LISTS"
        metrics:
          - metric_name: pgbouncer.lists.pools
            value_column: items
            value_type: int
            row_condition:
              column: list
              value: pools
          - metric_name: pgbouncer.lists.databases
            value_column: items
            value_type: int
            row_condition:
              column: list
              value: databases
          - metric_name: pgbouncer.lists.users
            value_column: items
            value_type: int
            row_condition:
              column: list
              value: users
This produces three separate metrics (pgbouncer.lists.pools, pgbouncer.lists.databases, pgbouncer.lists.users), each sourced from the matching row only.

​
NULL values

Avoid queries that produce any NULL values. If a query produces a NULL value, a warning will be logged. Furthermore, if a configuration references the column that produces a NULL value, an additional error will be logged. However, in either case, the receiver will continue to operate.

​
Oracle DB Driver Example

Refer to the config file provided for an example of using the Oracle DB driver to connect and query the same table schema and contents as the example above. The Oracle DB driver documentation can be found here.

​
MySQL Datasource Format Example

The datasource format for MySQL works as follows:
user:password@tcp(host:port)/databasename

​
Configuration

​
Example Configuration

sqlquery:
  collection_interval: 10s
  driver: postgres
  datasource: "host=localhost port=5432 user=me password=s3cr3t sslmode=disable"
  queries:
    - sql: "select count(*) as count, type from mytable group by type"
      metrics:
        - metric_name: val.count
          value_column: "count"
          attribute_columns: ["type"]
          data_type: sum
          value_type: int
          monotonic: false
          aggregation: cumulative
          static_attributes:
            foo: bar
Last generated: 2026-04-13