postgresqlreceiver

README

PostgreSQL Receiver

Status
Stability	beta
Supported pipeline types	metrics
Distributions	contrib

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.

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.

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.

Metrics

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

Feature gate configurations

Transition from metrics without "resource_attributes"

All metrics are being transitioning to moving the metric attributes table and database to resource attributes postgresql.table and postgresql.database respectively. This effort is motivated via the resource specification found in the metrics data model.

Eventually the move will be finalized, but there will be a transitional period where metrics will emit with resource attributes behind a feature gate.

Transition Schedule

1. v0.58.0, August 2022:

   • The version of the metrics receiver with resource attributes will be available via feature gates.
   • The old metrics with table and database metric attributes are deprecated with a warning.
   • receiver.postgresql.emitMetricsWithResourceAttributes is disabled by default.
   • receiver.postgresql.emitMetricsWithoutResourceAttributes is enabled by default.

2. v0.60.0, September 2022:

   • The new collection method with resource attributes is enabled by default. The old metrics with the table and database metric attributes is disabled by default.
   • receiver.postgresql.emitMetricsWithResourceAttributes is enabled by default.
   • receiver.postgresql.emitMetricsWithoutResourceAttributes is disabled by default.

3. v0.62.0, October 2022:

   • The feature gates are removed.
   • Metrics collection using resource attributes are always emitted
   • Metrics collection using the database and table metric attributes are no longer available.

Documentation

Index

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

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.ScraperControllerSettings `mapstructure:",squash"`
	Username                                string                         `mapstructure:"username"`
	Password                                string                         `mapstructure:"password"`
	Databases                               []string                       `mapstructure:"databases"`
	confignet.NetAddr                       `mapstructure:",squash"`       // provides Endpoint and Transport
	configtls.TLSClientSetting              `mapstructure:"tls,omitempty"` // provides SSL details
	Metrics                                 metadata.MetricsSettings       `mapstructure:"metrics"`
}

func (*Config) Validate

func (cfg *Config) Validate() error