Help us shape the future of Go! Take the 2026 Go Developer Survey

sql_exporter

package module
v0.0.0-...-ace2f71 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 29 Imported by: 2

README

SQL Exporter for Prometheus

Docker Pulls Downloads Artifact HUB Audit Released Binary (linux/amd64)

Documentation · Configuration Reference

SQL Exporter is a flexible database-agnostic exporter that exposes metrics gathered from databases in Prometheus format.

Features

  • Database-agnostic with broad driver support
  • Scrape-synchronous collection with optional caching
  • Staggered cache warmup
  • Fully configuration-driven metrics
  • Flexible metric mapping
  • Multi-target (jobs) mode
  • Selective job scraping
  • Secret manager integration
  • TLS/BasicAuth support
  • Request rate limiting
  • Live reload of configuration without restart
  • Automatic metrics
  • Builtin validation and config check

Installation

Head over to the documentation website for installation instructions and configuration options.

Support

If you have an issue using sql_exporter, please check Discussions or closed Issues first. Chances are someone else has already encountered the same problem and there is a solution. If not, feel free to create a new discussion.

Special Thanks

  • @free for creating the original implementation;
  • @allanger for contributing the helm chart and the dev/release environment around it;
  • @itdesign-sponsoring for sponsoring the development of the project;
  • all the contributors who have helped improve this project over the years.

Documentation

Overview

Package sql_exporter provides a Prometheus exporter for SQL metrics. It gathers metrics from SQL databases and exposes them in a format suitable for Prometheus scraping. The package supports multiple targets, collectors, and queries, and allows for flexible configuration through YAML files.

Index

Constants

This section is empty.

Variables

View Source
var (
	SvcRegistry = prometheus.NewRegistry()
)

Functions

func OfBool

func OfBool(i bool) *bool

OfBool returns bool address.

func OpenConnection

func OpenConnection(ctx context.Context, logContext, dsn string, maxConns, maxIdleConns int, maxConnLifetime time.Duration) (*sql.DB, error)

OpenConnection parses a provided DSN, and opens a DB handle ensuring early termination if the context is closed (this is actually prevented by `database/sql` implementation), sets connection limits and returns the handle.

func PingDB

func PingDB(ctx context.Context, conn *sql.DB) error

PingDB is a wrapper around sql.DB.PingContext() that terminates as soon as the context is closed.

sql.DB does not actually pass along the context to the driver when opening a connection (which always happens if the database is down) and the driver uses an arbitrary timeout which may well be longer than ours. So we run the ping call in a goroutine and terminate immediately if the context is closed.

func Reload

func Reload(e Exporter, configFile *string) error

Reload function is used to reload the exporter configuration without restarting the exporter

func TrimMissingCtx

func TrimMissingCtx(logContext string) string

TrimMissingCtx trims the leading comma and space from the log context string. Leading comma appears when previous parameter is undefined, which is a side-effect of running in single target mode.

Types

type Collector

type Collector interface {
	// Collect is the equivalent of prometheus.Collector.Collect() but takes a context to run in and a database to run on.
	Collect(context.Context, *sql.DB, chan<- Metric)
	// Close releases any resources held by the collector (e.g. prepared statements).
	Close() error
}

Collector is a self-contained group of SQL queries and metric families to collect from a specific database. It is conceptually similar to a prometheus.Collector.

func NewCollector

func NewCollector(logContext string, cc *config.CollectorConfig, constLabels []*dto.LabelPair, enableQueryMetrics bool) (Collector, errors.WithContext)

NewCollector returns a new Collector with the given configuration and database. The metrics it creates will all have the provided const labels applied.

type Exporter

type Exporter interface {
	prometheus.Gatherer

	// WithContext returns a (single use) copy of the Exporter, which will use the provided context for Gather() calls.
	WithContext(context.Context) Exporter
	// Config returns the Exporter's underlying Config object.
	Config() *config.Config
	// Globals returns the current global settings. Scrapes read them while a reload may replace them, so they read
	// them here and not from Config().
	Globals() *config.GlobalConfig
	// UpdateGlobals replaces the global settings.
	UpdateGlobals(*config.GlobalConfig)
	// UpdateTarget updates the targets field
	UpdateTarget([]Target)
	// Targets returns the current list of targets.
	Targets() []Target
	// SetJobFilters sets the jobFilters field
	SetJobFilters([]string) error
	// DropErrorMetrics resets the scrape_errors_total metric
	DropErrorMetrics()
	// FilterScrapeErrorsTotal filters the scrape_errors_total metric family to only include metrics for the jobs in
	// the jobFilters list.
	FilterScrapeErrorsTotal([]*dto.MetricFamily) []*dto.MetricFamily
}

Exporter is a prometheus.Gatherer that gathers SQL metrics from targets and merges them with the custom registry.

func NewExporter

func NewExporter(configFile string, registry prometheus.Registerer) (Exporter, error)

NewExporter returns a new Exporter with the provided config.

type Job

type Job interface {
	Targets() []Target
}

Job is a collection of targets with the same collectors applied.

func NewJob

NewJob returns a new Job with the given configuration.

type Metric

type Metric interface {
	Desc() MetricDesc
	Write(out *dto.Metric) errors.WithContext
}

A Metric models a single sample value with its meta data being exported to Prometheus.

func NewInvalidMetric

func NewInvalidMetric(err errors.WithContext) Metric

NewInvalidMetric returns a metric whose Write method always returns the provided error.

func NewMetric

func NewMetric(desc MetricDesc, value float64, labelValues ...string) Metric

NewMetric returns a metric with one fixed value that cannot be changed.

NewMetric panics if the length of labelValues is not consistent with desc.labels().

func NewMetricWithTimestamp

func NewMetricWithTimestamp(t time.Time, m Metric) Metric

type MetricDesc

type MetricDesc interface {
	Name() string
	Help() string
	ValueType() prometheus.ValueType
	ConstLabels() []*dto.LabelPair
	Labels() []string
	LogContext() string
}

MetricDesc is a descriptor for a family of metrics, sharing the same name, help, labels, type.

func NewAutomaticMetricDesc

func NewAutomaticMetricDesc(
	logContext, name, help string, valueType prometheus.ValueType, constLabels []*dto.LabelPair, labels ...string,
) MetricDesc

NewAutomaticMetricDesc creates a MetricDesc for automatically generated metrics.

type MetricFamily

type MetricFamily struct {
	// contains filtered or unexported fields
}

MetricFamily implements MetricDesc for SQL metrics, with logic for populating its labels and values from sql.Rows.

func NewMetricFamily

func NewMetricFamily(logContext string, mc *config.MetricConfig, constLabels []*dto.LabelPair) (*MetricFamily, errors.WithContext)

NewMetricFamily creates a new MetricFamily with the given metric config and const labels (e.g. job and instance).

func (MetricFamily) Collect

func (mf MetricFamily) Collect(row map[string]any, ch chan<- Metric)

Collect is the equivalent of prometheus.Collector.Collect() but takes a Query output map to populate values from.

func (MetricFamily) ConstLabels

func (mf MetricFamily) ConstLabels() []*dto.LabelPair

ConstLabels implements MetricDesc.

func (MetricFamily) Help

func (mf MetricFamily) Help() string

Help implements MetricDesc.

func (MetricFamily) Labels

func (mf MetricFamily) Labels() []string

Labels implements MetricDesc.

func (MetricFamily) LogContext

func (mf MetricFamily) LogContext() string

LogContext implements MetricDesc.

func (MetricFamily) Name

func (mf MetricFamily) Name() string

Name implements MetricDesc.

func (MetricFamily) ValueType

func (mf MetricFamily) ValueType() prometheus.ValueType

ValueType implements MetricDesc.

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query wraps a sql.Stmt and all the metrics populated from it. It helps extract keys and values from result rows.

func NewQuery

func NewQuery(logContext string, qc *config.QueryConfig, constLabels []*dto.LabelPair, enableQueryMetrics bool, metricFamilies ...*MetricFamily) (*Query, errors.WithContext)

NewQuery returns a new Query that will populate the given metric families.

func (*Query) Close

func (q *Query) Close() error

Close releases the prepared statement if one was cached.

func (*Query) Collect

func (q *Query) Collect(ctx context.Context, conn *sql.DB, ch chan<- Metric)

Collect is the equivalent of prometheus.Collector.Collect() but takes a context to run in and a database to run on.

type Target

type Target interface {
	// Collect is the equivalent of prometheus.Collector.Collect(), but takes a context to run in.
	Collect(ctx context.Context, ch chan<- Metric)
	Close() error
	JobGroup() string
}

Target collects SQL metrics from a single sql.DB instance. It aggregates one or more Collectors and it looks much like a prometheus.Collector, except its Collect() method takes a Context to run in.

func NewTarget

func NewTarget(
	logContext, tname, jg, dsn string, ccs []*config.CollectorConfig, constLabels prometheus.Labels, gc *config.GlobalConfig, ep *bool) (
	Target, errors.WithContext,
)

NewTarget returns a new Target with the given target name, data source name, collectors and constant labels. An empty target name means the exporter is running in single target mode: no synthetic metrics will be exported.

type Warmup

type Warmup struct {
	// contains filtered or unexported fields
}

Warmup pre-populates collector caches on startup by sequentially triggering each collector with a configurable delay between them, avoiding the thundering herd problem where all collectors hit the database simultaneously on first scrape.

func NewWarmup

func NewWarmup() *Warmup

NewWarmup creates a new Warmup instance.

func (*Warmup) Done

func (w *Warmup) Done() bool

Done returns true if warmup has completed without blocking.

func (*Warmup) Run

func (w *Warmup) Run(targets []Target, delay time.Duration, timeout time.Duration)

Run sequentially triggers each collector across all targets with a delay between each, pre-populating the in-memory caches before the first real scrape. The timeout limits the ping and each collector run, not the whole warmup.

Directories

Path Synopsis
cmd
sql_exporter command
Package config provides the configuration structures and functions for sql_exporter.
Package config provides the configuration structures and functions for sql_exporter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL