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 ¶
- Variables
- func OfBool(i bool) *bool
- func OpenConnection(ctx context.Context, logContext, dsn string, maxConns, maxIdleConns int, ...) (*sql.DB, error)
- func PingDB(ctx context.Context, conn *sql.DB) error
- func Reload(e Exporter, configFile *string) error
- func TrimMissingCtx(logContext string) string
- type Collector
- type Exporter
- type Job
- type Metric
- type MetricDesc
- type MetricFamily
- func (mf MetricFamily) Collect(row map[string]any, ch chan<- Metric)
- func (mf MetricFamily) ConstLabels() []*dto.LabelPair
- func (mf MetricFamily) Help() string
- func (mf MetricFamily) Labels() []string
- func (mf MetricFamily) LogContext() string
- func (mf MetricFamily) Name() string
- func (mf MetricFamily) ValueType() prometheus.ValueType
- type Query
- type Target
- type Warmup
Constants ¶
This section is empty.
Variables ¶
var (
SvcRegistry = prometheus.NewRegistry()
)
Functions ¶
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 ¶
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 ¶
Reload function is used to reload the exporter configuration without restarting the exporter
func TrimMissingCtx ¶
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 ¶
func NewJob(jc *config.JobConfig, gc *config.GlobalConfig) (Job, errors.WithContext)
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.
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) LogContext ¶
func (mf MetricFamily) LogContext() string
LogContext 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.
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.
Source Files
¶
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. |