[+] add packages doc.go files (#623)

api/doc.go

@@ -0,0 +1,2 @@
+// package api contains the API definitions for external use, such as the RPC sink.
+package api

cmd/convert_metrics/doc.go

@@ -0,0 +1,2 @@
+// convert_metrics is a tool that converts v2 metric definitions to v3 format.
+package main

cmd/pgwatch/doc.go

@@ -0,0 +1,110 @@
+// pgwatch is a command line tool that collects metrics from PostgreSQL databases and forwards to external sinks.
+//
+// Usage:
+//
+//	pgwatch [OPTIONS] [config | metric | source]
+//
+// Sources:
+//
+//	-s, --sources=                           Postgres URI, file or folder of YAML
+//	                                         files containing info on which DBs
+//	                                         to monitor [$PW_SOURCES]
+//	    --refresh=                           How frequently to resync sources and
+//	                                         metrics (default: 120) [$PW_REFRESH]
+//	-g, --group=                             Groups for filtering which databases
+//	                                         to monitor. By default all are
+//	                                         monitored [$PW_GROUP]
+//	    --min-db-size-mb=                    Smaller size DBs will be ignored and
+//	                                         not monitored until they reach the
+//	                                         threshold. (default: 0)
+//	                                         [$PW_MIN_DB_SIZE_MB]
+//	    --max-parallel-connections-per-db=   Max parallel metric fetches per DB.
+//	                                         Note the multiplication effect on
+//	                                         multi-DB instances (default: 4)
+//	                                         [$PW_MAX_PARALLEL_CONNECTIONS_PER_DB]
+//	    --try-create-listed-exts-if-missing= Try creating the listed extensions
+//	                                         (comma sep.) on first connect for
+//	                                         all monitored DBs when missing. Main
+//	                                         usage - pg_stat_statements
+//	                                         [$PW_TRY_CREATE_LISTED_EXTS_IF_MISSING]
+//
+// Metrics:
+//
+//	-m, --metrics=                           File or folder of YAML files with
+//	                                         metrics definitions [$PW_METRICS]
+//	    --create-helpers                     Create helper database objects from
+//	                                         metric definitions
+//	                                         [$PW_CREATE_HELPERS]
+//	    --direct-os-stats                    Extract OS related psutil statistics
+//	                                         not via PL/Python wrappers but
+//	                                         directly on host
+//	                                         [$PW_DIRECT_OS_STATS]
+//	    --instance-level-cache-max-seconds=  Max allowed staleness for instance
+//	                                         level metric data shared between DBs
+//	                                         of an instance. Affects 'continuous'
+//	                                         host types only. Set to 0 to disable
+//	                                         (default: 30)
+//	                                         [$PW_INSTANCE_LEVEL_CACHE_MAX_SECONDS]
+//	    --emergency-pause-triggerfile=       When the file exists no metrics will
+//	                                         be temporarily fetched / scraped
+//	                                         (default:
+//	                                         /tmp/pgwatch-emergency-pause)
+//	                                         [$PW_EMERGENCY_PAUSE_TRIGGERFILE]
+//
+// Sinks:
+//
+//	--sink=                              URI where metrics will be stored,
+//	                                     can be used multiple times [$PW_SINK]
+//	--batching-delay=                    Max milliseconds to wait for a
+//	                                     batched metrics flush. [Default:
+//	                                     250ms] (default: 250ms)
+//	                                     [$PW_BATCHING_MAX_DELAY]
+//	--retention=                         If set, metrics older than that will
+//	                                     be deleted (default: 14)
+//	                                     [$PW_RETENTION]
+//	--real-dbname-field=                 Tag key for real database name
+//	                                     (default: real_dbname)
+//	                                     [$PW_REAL_DBNAME_FIELD]
+//	--system-identifier-field=           Tag key for system identifier value
+//	                                     (default: sys_id)
+//	                                     [$PW_SYSTEM_IDENTIFIER_FIELD]
+//
+// Logging:
+//
+//	-v, --log-level=[debug|info|error]       Verbosity level for stdout and log
+//	                                         file (default: info)
+//	    --log-file=                          File name to store logs
+//	    --log-file-format=[json|text]        Format of file logs (default: json)
+//	    --log-file-rotate                    Rotate log files
+//	    --log-file-size=                     Maximum size in MB of the log file
+//	                                         before it gets rotated (default: 100)
+//	    --log-file-age=                      Number of days to retain old log
+//	                                         files, 0 means forever (default: 0)
+//	    --log-file-number=                   Maximum number of old log files to
+//	                                         retain, 0 to retain all (default: 0)
+//
+// WebUI:
+//
+//	--web-disable=[all|ui]               Disable REST API and/or web UI
+//	                                     [$PW_WEBDISABLE]
+//	--web-addr=                          TCP address in the form 'host:port'
+//	                                     to listen on (default: :8080)
+//	                                     [$PW_WEBADDR]
+//	--web-user=                          Admin login [$PW_WEBUSER]
+//	--web-password=                      Admin password [$PW_WEBPASSWORD]
+//
+// Help Options:
+//
+//	-h, --help                               Show this help message
+//
+// Available commands:
+//
+//	config         Manage configurations
+//	   init            Initialize configuration
+//	   upgrade         Upgrade configuration schema
+//	metric         Manage metrics
+//	   print-init      Get and print init SQL for a given metric or preset
+//	   print-sql       Get and print SQL for a given metric
+//	source         Manage sources
+//	   ping            Try to connect to configured sources, report errors if any and exit
+package main

internal/cmdopts/doc.go

@@ -0,0 +1,2 @@
+// Package cmdopts provides functionality to parse command line options and ENV variables.
+package cmdopts

internal/db/doc.go

@@ -0,0 +1,2 @@
+// Package db provides common functionality to work with databases.
+package db

internal/log/doc.go

@@ -0,0 +1,2 @@
+// Package log contains the logger interface and its implementation used in the project.
+package log

internal/metrics/doc.go

@@ -1,6 +1,5 @@
-// # Metrics
+// Package metrics is responsible for reading and writing metric definitions.
 //
-// Code in this folder is responsible for reading and writing metric definitions.
 // At the moment, metric definitions support two storages:
 //   - PostgreSQL database
 //   - YAML file

internal/metrics/psutil/doc.go

@@ -0,0 +1,2 @@
+// Package psutil provides a way to read local system metrics using the psutil library.
+package psutil

internal/reaper/doc.go

@@ -0,0 +1,3 @@
+// Package reaper is responsible to query the metrics from monitored sources
+// and send measurements to sinks.
+package reaper

internal/sinks/doc.go

@@ -1,4 +1,4 @@
-// Package sinks provides functionality to store monitored data in different ways.
+// Package sinks rovides functionality to store monitored data in different ways.
 //
 // At the moment we provide sink connectors for
 //   - PostgreSQL and flavours,

internal/sources/doc.go

@@ -1,17 +1,13 @@
-package sources
-
-// # Sources
-
-// Code in this folder is responsible for reading and writing sources.
+// Provides functionality to read monitored data from different sources.
+//
 // Sources defines how to get the information for the monitored databases.
 // At the moment, sources definitions support two storages:
 // * PostgreSQL database
 // * YAML file
-
-// ## Content
-
+//
 // * `postgres.go` files cover the functionality for the PostgreSQL database.
 // * `yaml.go` files cover the functionality for the YAML file.
 // * `resolver.go` implements continuous discovery from patroni and postgres cluster.
 // * `types.go` defines the types and interfaces.
 // * `sample.sources.yaml` is a sample configuration file.
+package sources

internal/webserver/doc.go

@@ -0,0 +1,2 @@
+// Package webserver serves the REST API and the web user interface.
+package webserver

internal/webui/doc.go

@@ -0,0 +1,2 @@
+// Package webui provides a web-based user interface for the service.
+package webui