Documentation
¶
Index ¶
- Constants
- Variables
- func DryRun()
- func DummyServer() (s *http.Server, exit <-chan bool)
- func GetConfig() (res string)
- func GetPGURL() string
- func LoadConfig(configPath string) (queries map[string]*Query, err error)
- func ParseArgs()
- func ParseConfig(content []byte) (queries map[string]*Query, err error)
- func ParseDatname(pgurl string) string
- func ParseSemver(semverStr string) int
- func PgbouncerPrecheck(s *Server) (err error)
- func PostgresPrecheck(s *Server) (err error)
- func ProcessPGURL(pgurl string) string
- func Reload() error
- func ReloadFunc(w http.ResponseWriter, r *http.Request)
- func ReplaceDatname(pgurl, datname string) string
- func RetrievePGURL() (res string)
- func Run()
- func ShadowPGURL(pgurl string) string
- func TitleFunc(w http.ResponseWriter, r *http.Request)
- func VersionFunc(w http.ResponseWriter, r *http.Request)
- type Collector
- func (q *Collector) CacheHit() bool
- func (q *Collector) Collect(ch chan<- prometheus.Metric)
- func (q *Collector) Describe(ch chan<- *prometheus.Desc)
- func (q *Collector) Duration() float64
- func (q *Collector) Error() error
- func (q *Collector) PredicateSkip() (bool, string)
- func (q *Collector) ResultSize() int
- type Column
- type Exporter
- func (e *Exporter) Check()
- func (e *Exporter) Close()
- func (e *Exporter) Collect(ch chan<- prometheus.Metric)
- func (e *Exporter) CreateServer(dbname string)
- func (e *Exporter) Describe(ch chan<- *prometheus.Desc)
- func (e *Exporter) Explain() string
- func (e *Exporter) ExplainFunc(w http.ResponseWriter, r *http.Request)
- func (e *Exporter) IterateServer() (res []*Server)
- func (e *Exporter) OnDatabaseChange(change map[string]bool)
- func (e *Exporter) PrimaryCheckFunc(w http.ResponseWriter, r *http.Request)
- func (e *Exporter) Recovery() bool
- func (e *Exporter) RemoveServer(dbname string)
- func (e *Exporter) ReplicaCheckFunc(w http.ResponseWriter, r *http.Request)
- func (e *Exporter) Stat() string
- func (e *Exporter) StatFunc(w http.ResponseWriter, r *http.Request)
- func (e *Exporter) Status() string
- func (e *Exporter) Up() bool
- func (e *Exporter) UpCheckFunc(w http.ResponseWriter, r *http.Request)
- type ExporterOpt
- func WithAutoDiscovery(flag bool) ExporterOpt
- func WithCacheDisabled(disableCache bool) ExporterOpt
- func WithConfig(configPath string) ExporterOpt
- func WithConfigReader(reader io.Reader) ExporterOpt
- func WithConnectTimeout(timeout int) ExporterOpt
- func WithConstLabels(s string) ExporterOpt
- func WithExcludeDatabase(excludeStr string) ExporterOpt
- func WithFailFast(failFast bool) ExporterOpt
- func WithIncludeDatabase(includeStr string) ExporterOpt
- func WithIntroDisabled(disableIntro bool) ExporterOpt
- func WithNamespace(namespace string) ExporterOpt
- func WithTags(tags string) ExporterOpt
- type MetricDesc
- type PredicateQuery
- type Query
- func (q *Query) ColumnList() (res []*Column)
- func (q *Query) Explain() string
- func (q *Query) HTML() string
- func (q *Query) HasTag(tag string) bool
- func (q *Query) LabelList() []string
- func (q *Query) MarshalYAML() string
- func (q *Query) MetricList() (res []*MetricDesc)
- func (q *Query) TimeoutDuration() time.Duration
- type Server
- func (s *Server) Check() error
- func (s *Server) Collect(ch chan<- prometheus.Metric)
- func (s *Server) Compatible(query *Query) (res bool, reason string)
- func (s *Server) Describe(ch chan<- *prometheus.Desc)
- func (s *Server) Duration() float64
- func (s *Server) Error() error
- func (s *Server) Explain() string
- func (s *Server) ExplainHTML() string
- func (s *Server) GetConnectTimeout() time.Duration
- func (s *Server) HasTag(tag string) bool
- func (s *Server) Name() string
- func (s *Server) Plan(queries ...*Query)
- func (s *Server) ResetStats()
- func (s *Server) Stat() string
- func (s *Server) Uptime() float64
- type ServerOpt
Constants ¶
const ( DISCARD = "DISCARD" // Ignore this column (when SELECT *) LABEL = "LABEL" // Use this column as a label COUNTER = "COUNTER" // Use this column as a counter GAUGE = "GAUGE" // Use this column as a gauge HISTOGRAM = "HISTOGRAM" // Use this column as a histogram )
Variables ¶
PgExporter is the global singleton of Exporter
var ColumnUsage = map[string]bool{ DISCARD: false, LABEL: false, COUNTER: true, GAUGE: true, HISTOGRAM: true, }
ColumnUsage determine how to use query result column
var Version = "0.8.0"
Version is read by make build procedure
Functions ¶
func DummyServer ¶
DummyServer response with a dummy metrics pg_up 0 or pgbouncer_up 0
func GetPGURL ¶
func GetPGURL() string
GetPGURL will retrieve, parse, modify postgres connection string
func LoadConfig ¶
LoadConfig will read single conf file or read multiple conf file if a dir is given conf file in a dir will be load in alphabetic order, query with same name will overwrite predecessor
func ParseArgs ¶
func ParseArgs()
ParseArgs will parse cli args with kingpin. url and config have special treatment
func ParseConfig ¶
ParseConfig turn config content into Query struct
func ParseDatname ¶
ParseDatname extract database name part of a pgurl
func ParseSemver ¶
ParseSemver will turn semantic version string into integer
func PgbouncerPrecheck ¶
PgbouncerPrecheck checks pgbouncer connection before scrape
func PostgresPrecheck ¶
PostgresPrecheck checks postgres connection and gathering facts if any important fact changed, it will trigger a plan before next scrape
func ProcessPGURL ¶
ProcessPGURL will fix URL with default options
func ReloadFunc ¶
func ReloadFunc(w http.ResponseWriter, r *http.Request)
ReloadFunc handles reload request
func ReplaceDatname ¶
ReplaceDatname will replace pgurl with new database name
func RetrievePGURL ¶
func RetrievePGURL() (res string)
RetrievePGURL retrieve pg target url from multiple sources according to precedence priority: cli-args > env > env file path
- Command Line Argument (--url -u -d)
- Environment PG_EXPORTER_URL
- From file specified via Environment PG_EXPORTER_URL_FILE
- Default url
func TitleFunc ¶
func TitleFunc(w http.ResponseWriter, r *http.Request)
TitleFunc responding a description message
func VersionFunc ¶
func VersionFunc(w http.ResponseWriter, r *http.Request)
VersionFunc responding current pg_exporter version
Types ¶
type Collector ¶
type Collector struct { *Query Server *Server // It's a query, but holds a server // contains filtered or unexported fields }
Collector holds runtime information of a Query running on a Server It is deeply coupled with Server. Besides, it can be a collector itself
func NewCollector ¶
NewCollector will generate query instance from query, Injecting a server object
func (*Collector) Collect ¶
func (q *Collector) Collect(ch chan<- prometheus.Metric)
Collect implement prometheus.Collector
func (*Collector) Describe ¶
func (q *Collector) Describe(ch chan<- *prometheus.Desc)
Describe implement prometheus.Collector
func (*Collector) PredicateSkip ¶ added in v0.7.0
PredicateSkip tells the last scrape skip due to predicate query and if so which predicate query caused the skip?
func (*Collector) ResultSize ¶
ResultSize report last scraped metric count
type Column ¶
type Column struct { Name string `yaml:"name"` Usage string `yaml:"usage,omitempty"` // column usage Rename string `yaml:"rename,omitempty"` // rename column Bucket []float64 `yaml:"bucket,omitempty"` // histogram bucket Scale string `yaml:"scale,omitempty"` // scale factor Default string `yaml:"default,omitempty"` // default value Desc string `yaml:"description,omitempty"` }
Column holds the metadata of query result
func (*Column) MetricDesc ¶
func (c *Column) MetricDesc(prefix string, labels []string) *MetricDesc
MetricDesc will generate MetricDesc from column and additional information
func (*Column) PrometheusValueType ¶
func (c *Column) PrometheusValueType() prometheus.ValueType
PrometheusValueType returns column's corresponding prometheus value type
type Exporter ¶
type Exporter struct {
// contains filtered or unexported fields
}
Exporter implement prometheus.Collector interface exporter contains one or more (auto-discover-database) servers that can scrape metrics with Query
func NewExporter ¶
func NewExporter(dsn string, opts ...ExporterOpt) (e *Exporter, err error)
NewExporter construct a PG Exporter instance for given dsn
func (*Exporter) Check ¶
func (e *Exporter) Check()
Check will perform an immediate server health check
func (*Exporter) Collect ¶
func (e *Exporter) Collect(ch chan<- prometheus.Metric)
Collect implement prometheus.Collector
func (*Exporter) CreateServer ¶
CreateServer will spawn new database server from a database name combined with existing dsn string This happens when a database is newly created
func (*Exporter) Describe ¶
func (e *Exporter) Describe(ch chan<- *prometheus.Desc)
Describe implement prometheus.Collector
func (*Exporter) ExplainFunc ¶
func (e *Exporter) ExplainFunc(w http.ResponseWriter, r *http.Request)
ExplainFunc expose explain document
func (*Exporter) IterateServer ¶
IterateServer will get snapshot of extra servers
func (*Exporter) OnDatabaseChange ¶
OnDatabaseChange will spawn new Server when new database is created and destroy Server if corresponding database is dropped
func (*Exporter) PrimaryCheckFunc ¶
func (e *Exporter) PrimaryCheckFunc(w http.ResponseWriter, r *http.Request)
PrimaryCheckFunc tells whether target instance is a primary, 200 yes 404 no 503 unknown
func (*Exporter) RemoveServer ¶
RemoveServer will destroy Server from Exporter according to database name This happens when a database is dropped
func (*Exporter) ReplicaCheckFunc ¶
func (e *Exporter) ReplicaCheckFunc(w http.ResponseWriter, r *http.Request)
ReplicaCheckFunc tells whether target instance is a replica, 200 yes 404 no 503 unknown
func (*Exporter) StatFunc ¶
func (e *Exporter) StatFunc(w http.ResponseWriter, r *http.Request)
StatFunc expose html statistics
func (*Exporter) UpCheckFunc ¶
func (e *Exporter) UpCheckFunc(w http.ResponseWriter, r *http.Request)
UpCheckFunc tells whether target instance is alive, 200 up 503 down
type ExporterOpt ¶
type ExporterOpt func(*Exporter)
ExporterOpt configures Exporter
func WithAutoDiscovery ¶
func WithAutoDiscovery(flag bool) ExporterOpt
WithAutoDiscovery configures exporter with excluded database
func WithCacheDisabled ¶
func WithCacheDisabled(disableCache bool) ExporterOpt
WithCacheDisabled set cache param to exporter
func WithConfig ¶
func WithConfig(configPath string) ExporterOpt
WithConfig add config path to Exporter
func WithConfigReader ¶ added in v0.7.1
func WithConfigReader(reader io.Reader) ExporterOpt
WithConfigReader uses a the provided reader to load a configuration for the Exporter
func WithConnectTimeout ¶
func WithConnectTimeout(timeout int) ExporterOpt
WithConnectTimeout will specify timeout for conn pre-check. It's useful to increase this value when monitoring a remote instance (cross DC, cross AZ)
func WithConstLabels ¶
func WithConstLabels(s string) ExporterOpt
WithConstLabels add const label to exporter. 0 length label returns nil
func WithExcludeDatabase ¶
func WithExcludeDatabase(excludeStr string) ExporterOpt
WithExcludeDatabase configures exporter with excluded database
func WithFailFast ¶
func WithFailFast(failFast bool) ExporterOpt
WithFailFast marks exporter fail instead of waiting during start-up
func WithIncludeDatabase ¶
func WithIncludeDatabase(includeStr string) ExporterOpt
WithIncludeDatabase configures exporter with included database
func WithIntroDisabled ¶
func WithIntroDisabled(disableIntro bool) ExporterOpt
WithIntroDisabled will pass introspection option to server
func WithNamespace ¶
func WithNamespace(namespace string) ExporterOpt
WithNamespace will specify metric namespace, by default is pg or pgbouncer
func WithTags ¶
func WithTags(tags string) ExporterOpt
WithTags will register given tags to Exporter and all belonged servers
type MetricDesc ¶
MetricDesc is generated by collector's column definition
func (*MetricDesc) String ¶
func (m *MetricDesc) String() string
Signature will print metric signature such as pg_db_age{datname}
type PredicateQuery ¶ added in v0.7.0
type PredicateQuery struct { Name string `yaml:"name,omitempty"` // predicate query name, only used for logging SQL string `yaml:"predicate_query"` // SQL command to return a predicate TTL float64 `yaml:"ttl,omitempty"` // How long to cache results for }
A PredicateQuery is a query that returns a 1-column resultset that's used to decide whether to run the main query.
type Query ¶
type Query struct { Name string `yaml:"name,omitempty"` // actual query name, used as metric prefix Desc string `yaml:"desc,omitempty"` // description of this metric query SQL string `yaml:"query"` // SQL command to fetch metrics PredicateQueries []PredicateQuery `yaml:"predicate_queries,omitempty"` // SQL command to filter metrics Branch string `yaml:"-"` // branch name, top layer key of config file // control query behaviour Tags []string `yaml:"tags,omitempty"` // tags are used for execution control TTL float64 `yaml:"ttl,omitempty"` // caching ttl in seconds Timeout float64 `yaml:"timeout,omitempty"` // query execution timeout in seconds Priority int `yaml:"priority,omitempty"` // execution priority, from 1 to 999 MinVersion int `yaml:"min_version,omitempty"` // minimal supported version, include MaxVersion int `yaml:"max_version,omitempty"` // maximal supported version, not include Fatal bool `yaml:"fatal,omitempty"` // if query marked fatal fail, entire scrape will fail Skip bool `yaml:"skip,omitempty"` // if query marked skip, it will be omit while loading Metrics []map[string]*Column `yaml:"metrics"` // metric definition list // metrics parsing auxiliaries Path string `yaml:"-"` // where am I from ? Columns map[string]*Column `yaml:"-"` // column map ColumnNames []string `yaml:"-"` // column names in origin orders LabelNames []string `yaml:"-"` // column (name) that used as label, sequences matters MetricNames []string `yaml:"-"` // column (name) that used as metric }
Query hold the information of how to fetch metric and parse them
func ParseQuery ¶
ParseQuery generate a single query from config string
func (*Query) ColumnList ¶
ColumnList return ordered column list
func (*Query) HasTag ¶
HasTag tells whether this query have specific tag since only few tags is provided, we don't really need a map here
func (*Query) MarshalYAML ¶
MarshalYAML will turn query into YAML format
func (*Query) MetricList ¶
func (q *Query) MetricList() (res []*MetricDesc)
MetricList returns a list of MetricDesc generated by this query
func (*Query) TimeoutDuration ¶
TimeoutDuration will turn timeout settings into time.Duration
type Server ¶
type Server struct { *sql.DB // database instance (do not close this due to the stupid implementation in database/sql) // postgres fact gather from server UP bool // indicate whether target server is connectable Recovery bool // is server in recovering Version int // pg server version num Database string // database name of current server connection Username string // current username Databases map[string]bool // all available database in target cluster Namespaces map[string]bool // all available schema in target cluster Extensions map[string]bool // all available extension in target cluster Tags []string // server tags set by cli arg --tag PgbouncerMode bool // indicate it is a pgbouncer server DisableCache bool // force executing, ignoring caching policy ExcludeDbnames []string // if ExcludeDbnames is provided, Auto Database Discovery is enabled Forked bool // is this a forked server ? (does not run cluster level query) Planned bool // if false, server will trigger a plan before collect ConnectTimeout int // connect timeout for this server in ms ConnMaxLifetime int // connection max lifetime for this server in seconds // query Collectors []*Collector // query collector instance (installed query) // contains filtered or unexported fields }
Server represent a postgres connection, with additional fact, conf, runtime info
func (*Server) Collect ¶
func (s *Server) Collect(ch chan<- prometheus.Metric)
Collect implement prometheus.Collector interface
func (*Server) Compatible ¶
Compatible tells whether a query is compatible with current server
func (*Server) Describe ¶
func (s *Server) Describe(ch chan<- *prometheus.Desc)
Describe implement prometheus.Collector
func (*Server) ExplainHTML ¶
ExplainHTML will print server stats in HTML format
func (*Server) GetConnectTimeout ¶
type ServerOpt ¶
type ServerOpt func(*Server)
ServerOpt configures Server
func WithCachePolicy ¶
WithCachePolicy will pass cache option to server
func WithConstLabel ¶
func WithConstLabel(labels prometheus.Labels) ServerOpt
WithConstLabel copy constant label map to server
func WithQueries ¶
WithQueries set server's default query set
func WithServerConnectTimeout ¶
WithServerConnectTimeout will set a connect timeout for server precheck queries otherwise, a default value 100ms will be used. Increase this value if you are monitoring a remote (cross-DC, cross-AZ) instance
func WithServerTags ¶
WithServerTags will mark server only execute query without cluster tag