postgresqlreceiver

README

PostgreSQL Receiver

Status
Stability	beta: metrics
Distributions	contrib
Issues
Code Owners	@djaglowski

This receiver queries the PostgreSQL statistics collector.

🚧 This receiver is in BETA. Configuration fields and metric data model are subject to change.

Prerequisites

This receiver supports PostgreSQL versions 9.6+

The monitoring user must be granted SELECT on pg_stat_database.

Configuration

The following settings are required to create a database connection:

• username
• password

The following settings are optional:

• endpoint (default = localhost:5432): The endpoint of the postgresql server. Whether using TCP or Unix sockets, this value should be host:port. If transport is set to unix, the endpoint will internally be translated from host:port to /host.s.PGSQL.port

• transport (default = tcp): The transport protocol being used to connect to postgresql. Available options are tcp and unix.

• databases (default = []): The list of databases for which the receiver will attempt to collect statistics. If an empty list is provided, the receiver will attempt to collect statistics for all non-template databases.

• exclude_databases (default = []): List of databases which will be excluded when collecting statistics.

The following settings are also optional and nested under tls to help configure client transport security

• insecure (default = false): Whether to enable client transport security for the postgresql connection.

• insecure_skip_verify (default = true): Whether to validate server name and certificate if client transport security is enabled.

• cert_file (default = $HOME/.postgresql/postgresql.crt): A cerficate used for client authentication, if necessary.

• key_file (default = $HOME/.postgresql/postgresql.key): An SSL key used for client authentication, if necessary.

• ca_file (default = ""): A set of certificate authorities used to validate the database server's SSL certificate.

• collection_interval (default = 10s): This receiver collects metrics on an interval. This value must be a string readable by Golang's time.ParseDuration. Valid time units are ns, us (or µs), ms, s, m, h.

• initial_delay (default = 1s): defines how long this receiver waits before starting.

Example Configuration

receivers:
  postgresql:
    endpoint: localhost:5432
    transport: tcp
    username: otel
    password: ${env:POSTGRESQL_PASSWORD}
    databases:
      - otel
    collection_interval: 10s
    tls:
      insecure: false
      insecure_skip_verify: false
      ca_file: /home/otel/authorities.crt
      cert_file: /home/otel/mypostgrescert.crt
      key_file: /home/otel/mypostgreskey.key

The full list of settings exposed for this receiver are documented here with detailed sample configurations here. TLS config is documented further under the opentelemetry collector's configtls package.

Connection pool feature

The feature gate receiver.postgresql.connectionPool allows to enable the creation & reuse of a pool per database for the connections instead of creating & closing on each scrape. This is generally a useful optimization but also alleviates the volume of generated audit logs when the PostgreSQL instance is configured with log_connections=on and/or log_disconnections=on.

When this feature gate is enabled, the following optional settings are available nested under connection_pool to help configure the connection pools:

• max_idle_time: The maximum amount of time a connection may be idle before being closed.
• max_lifetime: The maximum amount of time a connection may be reused.
• max_idle: The maximum number of connections in the idle connection pool.
• max_open: The maximum number of open connections to the database.

Those settings and their defaults are further documented in the sql/database package here.

Example Configuration

receivers:
  postgresql:
    endpoint: localhost:5432
    transport: tcp
    username: otel
    password: ${env:POSTGRESQL_PASSWORD}
    connection_pool:
      max_idle_time: 10m
      max_lifetime: 0
      max_idle: 2
      max_open: 5

Metrics

Details about the metrics produced by this receiver can be found in metadata.yaml

Documentation

Index

• Constants
• func NewFactory() receiver.Factory
• type Config
  • func (cfg *Config) Validate() error
• type ConnectionPool

Constants

const (
	ErrNoUsername          = "invalid config: missing username"
	ErrNoPassword          = "invalid config: missing password" // #nosec G101 - not hardcoded credentials
	ErrNotSupported        = "invalid config: field '%s' not supported"
	ErrTransportsSupported = "invalid config: 'transport' must be 'tcp' or 'unix'"
	ErrHostPort            = "invalid config: 'endpoint' must be in the form <host>:<port> no matter what 'transport' is configured"
)

Errors for missing required config parameters.

Functions

func NewFactory

func NewFactory() receiver.Factory

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	Username                       string                         `mapstructure:"username"`
	Password                       configopaque.String            `mapstructure:"password"`
	Databases                      []string                       `mapstructure:"databases"`
	ExcludeDatabases               []string                       `mapstructure:"exclude_databases"`
	confignet.AddrConfig           `mapstructure:",squash"`       // provides Endpoint and Transport
	configtls.ClientConfig         `mapstructure:"tls,omitempty"` // provides SSL details
	ConnectionPool                 `mapstructure:"connection_pool,omitempty"`
	metadata.MetricsBuilderConfig  `mapstructure:",squash"`
}

func (*Config) Validate

func (cfg *Config) Validate() error

type ConnectionPool

type ConnectionPool struct {
	MaxIdleTime *time.Duration `mapstructure:"max_idle_time,omitempty"`
	MaxLifetime *time.Duration `mapstructure:"max_lifetime,omitempty"`
	MaxIdle     *int           `mapstructure:"max_idle,omitempty"`
	MaxOpen     *int           `mapstructure:"max_open,omitempty"`
}