diff --git a/docs/concept/components.md b/docs/concept/components.md index c40030abe6..7330521b1e 100644 --- a/docs/concept/components.md +++ b/docs/concept/components.md @@ -77,6 +77,17 @@ monitoring will be carried out later and also Prometheus has a nice fault-tolerant alerting system for enterprise needs. By default, Prometheus is not set up for long term metrics storage! + +### [gRPC](https://grpc.io/) + +gRPC is a high-performance, open source RPC framework. + +It offers a way to push metrics to a custom storage backend +by implementing your own gRPC server based on pgwatch +[protobuf definition](https://github.com/cybertec-postgresql/pgwatch/blob/master/api/pb/pgwatch.proto). + +This is useful when none of the built-in storage options meet your needs. + ### JSON files Plain text files for testing / special use cases. diff --git a/docs/index.md b/docs/index.md index 120530f2e1..bff7e23ff8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,7 +40,7 @@ In addition to the standard metrics, pgwatch can be easily extended to monitor * **Where are the measurements stored and where can users inspect the dashboards?** -- pgwatch allows users to choose from a variety of **storage backends** aka **sinks** for storing monitoring data, such as JSON file, TimescaleDB, Prometheus, or a traditional PostgreSQL database. +- pgwatch allows users to choose from a variety of **storage backends** aka **sinks** for storing monitoring data, such as JSON file, TimescaleDB, Prometheus, PostgreSQL, or a custom gRPC-based backend. - The **user interface** for pgwatch is powered by **Grafana dashboards**, providing interactive and detailed visualization of the collected metrics. Users can easily view the performance and status of their databases in real-time, drill down into historical data, and configure custom dashboard views based on their preferences. For a detailed list of all features and capabilities, please refer to the [Features](intro/features.md) page. diff --git a/docs/intro/features.md b/docs/intro/features.md index 776c03c5ac..7f704d8511 100644 --- a/docs/intro/features.md +++ b/docs/intro/features.md @@ -14,7 +14,8 @@ title: List of main features - Easy extensibility of metrics which are defined in pure SQL, thus they could also be from the business domain - Many metric data storage options - PostgreSQL, PostgreSQL with the - compression enabled TimescaleDB extension, or Prometheus scraping + compression enabled TimescaleDB extension, Prometheus scraping, or + gRPC-based custom storage integration - Multiple deployment options - PostgreSQL configuration DB, YAML or ENV configuration - Possible to monitoring all, single or a subset (list or regex) of diff --git a/docs/reference/cli_env.md b/docs/reference/cli_env.md index b5367599da..c4424fe7e4 100644 --- a/docs/reference/cli_env.md +++ b/docs/reference/cli_env.md @@ -89,7 +89,9 @@ from resolved databases. Examples: `postgresql://pgwatch@localhost:5432/metrics`, `prometheus://localhost:9090`, `jsonfile:///tmp/metrics.json`, - `rpc://localhost:5000/` + `grpc://user:pwd@localhost:5000/?sslrootca=/home/user/ca.crt` + + See [Sinks Options & Parameters](sinks_options.md) for more details. - `--batching-delay=` diff --git a/docs/reference/sinks_options.md b/docs/reference/sinks_options.md new file mode 100644 index 0000000000..a6fafeb518 --- /dev/null +++ b/docs/reference/sinks_options.md @@ -0,0 +1,52 @@ +# Sinks Options & Parameters + +## PostgreSQL + +The PostgreSQL sink URI format is the standard [PostgreSQL connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS), +e.g. + +```bash +--sink=postgresql://user:pwd@host:port/dbname?sslmode=disable&connect_timeout=10 +``` + +All [standard environment variables](https://www.postgresql.org/docs/current/libpq-envars.html) are supported as well. + +## Prometheus + +The Prometheus sink URI format is + +```bash +--sink=prometheus://host:port/namespace +``` + +If you omit host, e.g. `--sink=prometheus://:9187`, server listens on all interfaces and supplied port. +If you omit namespace, default is `pgwatch`. + +## JSON file + +The JSON file sink URI format is + +```bash +--sink=jsonfile:///path/to/file.json +``` + +It should be a valid file path where the JSON data will be written. If the file does not exist, it will be created. + +## gRPC + +The gRPC sink URI format is + +```bash +--sink=grpc://user:pwd@host:port/?sslrootca=/path/to/ca.crt +``` + +The gRPC sink supports optional **authentication** and **TLS encryption** over the RPC channel. + +For authentication credentials can be provided using the `username:password` format in the URI string, +e.g. `--sink=grpc://user:pwd@localhost:5000/`. +If omitted, defaults to empty string for both username and password. +The values are then forwarded to the gRPC server under the `"username"` and `"password"` fields in the metadata. + +Enable TLS by specifying a custom Certificate Authority (CA) file via the `sslrootca` URI parameter, e.g. +`--sink=grpc://localhost:5000/?sslrootca=/home/user/ca.crt` +If omitted, encryption is not used. diff --git a/mkdocs.yml b/mkdocs.yml index a89a747d71..df2e598ecf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,6 +73,7 @@ nav: - Advanced Features: reference/advanced_features.md - Metric Definitions: reference/metric_definitions.md - Docker Variables: reference/env_variables.md + - Sinks Options: reference/sinks_options.md - Gallery: - Dashboards: gallery/dashboards.md - Web UI: gallery/webui.md