Promscale retention improvements (#1379)

* Improve retention docs with functions to get configured retention

* Additional clarification

* Add the functions to get metric retention to the sql api reference

* Update promscale/manage-data/retention.md

Co-authored-by: Lana Brindley <github@lanabrindley.com>

* Update promscale/manage-data/retention.md

Co-authored-by: Lana Brindley <github@lanabrindley.com>

* Update promscale/manage-data/retention.md

Co-authored-by: Lana Brindley <github@lanabrindley.com>

* Update promscale/manage-data/retention.md

Co-authored-by: Lana Brindley <github@lanabrindley.com>

Co-authored-by: Lana Brindley <github@lanabrindley.com>
Co-authored-by: Rajakavitha Kodhandapani <krajakavitha@gmail.com>
Co-authored-by: Vineeth Pothulapati <vineethpothulapati@outlook.com>

promscale/manage-data/retention.md

@@ -18,29 +18,49 @@ similar scheduling tool to schedule the maintenance task. See the
 details.
 
 ## Configure data retention for metrics
-You can set a default data retention period for metrics, and override the
-default on a per-metric basis.
+Metric data has an automated retention that drops data after a certain age.
+The default retention is 90 days which can be customized. It is also possible
+to configure a specific retention for a metric. This is typically used if you
+want to keep certain important metrics for longer to do trend analysis or for
+audit purposes while not incurring the higher storage costs of having to keep
+all metrics for longer.
+
+Get the currently configured default retention for metrics using the
+`prom_api.get_default_retention_period()` function, like this:
+ ```sql
+SELECT prom_api.get_default_metric_retention_period();
+```
 
 Change the default retention period for metrics by adjusting the 
 `retention_period` parameter of the function
 `prom_api.set_default_retention_period(retention_period INTERVAL)`:
 ```sql
-SELECT prom_api.set_default_retention_period(30 * INTERVAL '1 day')
+SELECT prom_api.set_default_retention_period(30 * INTERVAL '1 day');
 ```
 
 If you have specific metrics you need to retain for longer, use
 the function
 `prom_api.set_metric_retention_period(metric_name TEXT, new_retention_period INTERVAL)`:
 ```sql
-SELECT prom_api.set_metric_retention_period('container_cpu_usage_seconds_total', 180 * INTERVAL '1 day')
+SELECT prom_api.set_metric_retention_period('container_cpu_usage_seconds_total', 180 * INTERVAL '1 day');
+```
+
+You can retrieve which retention is being used for a specific metric, using the 
+`prom_api.get_metric_retention_period(metric_name TEXT)` function:
+```sql
+SELECT prom_api.get_metric_retention_period('container_cpu_usage_seconds_total');
 ```
+If no specific retention has been set for the metric, this returns the default retention.
 
 Reset an overridden metric retention period to the default
 by using the function `prom_api.reset_metric_retention_period(metric_name TEXT)`
 ```sql
-SELECT prom_api.reset_metric_retention_period('container_cpu_usage_seconds_total')
+SELECT prom_api.reset_metric_retention_period('container_cpu_usage_seconds_total');
 ```
 
+When you change the default retention period, any metrics that have a specific
+retention configured keep that retention, unless you reset it.
+
 ## Configure data retention for traces
 The `_ps_trace.span`, `_ps_trace.event`, and `_ps_trace.link` hypertables have
 an automated data retention policy which drops chunks beyond a certain age. By

promscale/sql-api.md

@@ -50,8 +50,10 @@ ORDER BY 1, 2, 4;
 |Name|Arguments|Type|Description|
 |-|:-:|:-:|:-|
  |`drop_metric`|metric_name_to_be_dropped text|void||
- |`delete_series_from_metric`|metric_name text, series_ids|boolean|deletes the series from the metric.|               
+ |`delete_series_from_metric`|metric_name text, series_ids|boolean|deletes the series from the metric.|
+ |`get_default_metric_retention_period`||interval|Returns the current default retention period for metrics.|              
  |`get_metric_metadata`|metric_family_nametext|TABLE(metric_family text, type text, unit text, help text)|
+ |`get_metric_retention_period`|metric_name text|interval|Returns the retention period configured for a specific metric.|
  |`get_multiple_metric_metadata`|metric_families text[]|TABLE(metric_family text, type text, unit text, help text)|
  |`is_normal_nan`|value double precision|boolean|is_normal_nan returns true if the value is a NaN.|
  |`is_stale_marker`|value double precision|boolean|is_stale_marker returns true if the value is a Prometheus stale marker.|