Query Exporter uses YAML configuration files to define databases, metrics, and queries. The configuration is modular and supports multiple files that can be merged together.
Configuration File Structure The configuration file consists of four main sections:
databases : Define database connectionsmetrics : Define Prometheus metricsqueries : Define SQL queries to executebuiltin-metrics : Configure built-in metrics (optional)
Complete Example Here’s a complete configuration file demonstrating all sections:
databases : db1 : dsn : sqlite:// connect-sql : - PRAGMA application_id = 123 - PRAGMA auto_vacuum = 1 labels : region : us1 app : app1 db2 : dsn : postgresql://user:password@localhost:5432/mydb connection-pool : size : 5 max-overflow : 10 labels : region : us2 app : app1 metrics : metric1 : type : gauge description : A sample gauge metric2 : type : summary description : A sample summary labels : [ l1 , l2 ] expiration : 24h metric3 : type : histogram description : A sample histogram buckets : [ 10 , 20 , 50 , 100 , 1000 ] metric4 : type : enum description : A sample enum states : [ foo , bar , baz ] queries : query1 : interval : 5 databases : [ db1 ] metrics : [ metric1 ] sql : SELECT random() / 1000000000000000 AS metric1 query2 : interval : 20 timeout : 0.5 databases : [ db1 , db2 ] metrics : [ metric2 , metric3 ] sql : | SELECT abs(random() / 1000000000000000) AS metric2, abs(random() / 10000000000000000) AS metric3, "value1" AS l1, "value2" AS l2 query3 : schedule : "*/5 * * * *" databases : [ db2 ] metrics : [ metric4 ] sql : SELECT 'foo' AS metric4 builtin-metrics : query_latency : buckets : [ 0.1 , 0.5 , 1.0 , 5.0 ]
Query Exporter supports special YAML tags to make configuration more flexible and modular:
!include Include the content of another YAML file. This allows modularizing configuration across multiple files.
databases : !include databases.yaml metrics : !include metrics.yaml queries : !include queries.yaml
If the specified path is not absolute, it’s considered relative to the including file.
!file Include the text content of a file as a string. This is useful for including SQL queries from separate files.
queries : my_query : databases : [ db1 ] metrics : [ metric1 ] sql : !file queries/my_query.sql
If the specified path is not absolute, it’s considered relative to the including file.
!env Expand to the value of the specified environment variable.
databases : production : dsn : !env DATABASE_DSN
The value of the variable is interpreted as YAML (and thus JSON), allowing for specifying values other than strings (e.g. integers/floats). The specified variable must be set or an error will occur.
Example with different types: databases : db1 : dsn : !env DB_DSN connection-pool : size : !env POOL_SIZE # Can be an integer from environment
Multiple Configuration Files You can split your configuration across multiple files and load them together:
query-exporter --config databases.yaml --config metrics.yaml --config queries.yaml
Or using the environment variable:
export QE_CONFIG = "databases.yaml,metrics.yaml,queries.yaml" query-exporter
The resulting configuration will be the merge of the content of each top-level section (databases, metrics, queries).
Duplicate entries across configuration files will cause an error. Each database, metric, and query name must be unique across all configuration files.
Next Steps
Database Configuration Learn how to configure database connections
Metrics Configuration Define Prometheus metrics
Queries Configuration Set up SQL queries
Built-in Metrics Configure built-in metrics