[FEATURE] add CloudWatch plugin

[T-Chittibabu]

Design discussion: perses/perses#4547

Description

This adds a CloudWatch plugin for Amazon CloudWatch metrics, reworked following the design discussion: there is no dedicated proxy anymore. The datasource is a regular HTTPProxy to the CloudWatch API of a region, with a secret holding a sigv4 configuration, and all the CloudWatch logic lives in the plugin.

The Perses server signs the requests with the AWS Signature Version 4, so the browser never receives AWS credentials. The plugin calls the CloudWatch API directly through the proxy, with the AWS JSON 1.0 protocol (X-Amz-Target: GraniteServiceVersion20100801.GetMetricData / ListMetrics).

Depends on the sigv4 authentication of the HTTP proxy in perses/perses (perses/perses#4569). The plugin itself only uses released packages, so its CI doesn't depend on it, but the requests can't be signed without it.

Plugins

• CloudWatchDatasource:
  • an HTTPProxy to https://monitoring.<region>.amazonaws.com, restricted to POST /, with a mandatory secret;
  • the editor builds the URL from the region (including the China regions);
  • a direct URL is not supported, as the requests must be signed by the server.
• CloudWatchTimeSeriesQuery:
  • metrics (namespace, metric name, dimensions, statistic, period) and metric math expressions referencing the other queries by ID, sent in a single GetMetricData request;
  • the pages are merged; forbidden or failed queries and error messages are reported instead of returning incomplete data;
  • returnData: false hides the series only used by an expression;
  • the editor includes a metric discovery (ListMetrics) to add a metric in one click.
• CloudWatchDimensionValuesVariable: the values of a dimension in a namespace (for example every InstanceId), optionally filtered by metric name and by other dimension values.

Behavior

• Period: the period of a metric is a minimum, like the minimum step of a Prometheus query. It is increased to the step suggested by the panel, and so the series stay under 10000 datapoints. For example, a single metric over 7 days is queried every 2 minutes.
• Variables: dashboard variables are replaced in the namespaces, metric names, dimension names and values, expressions and legends, and dependsOn lists them.
• Discovery: at most 1000 metrics are listed; the editor tells when the list is truncated.
• Errors: AWS errors are shown with their type and message (for example InvalidParameterValueException: ...), and so are the errors of the Perses proxy.
• Connection test: no healthCheckPath is defined, as the CloudWatch API only accepts signed POST requests. The editor doesn't show the generic test button; the metric discovery checks the datasource.
• Go SDK: builders for the datasource (CloudWatch(region, secretName, URL(...))), the query (Metric, Expression, Label, Hidden) and the variable.
• Docs: docs/cloudwatch (overview and setup, data model, Go SDK), as requested by @AntoineThebaud.

Testing

• npm run type-check, lint and build for the workspace. lint reports no new warning (only the existing setup-tests.ts one shared by every plugin).
• npm run test: 43 tests covering:
  • the exact GetMetricData / ListMetrics requests (headers, body, epoch timestamps);
  • the merge of the pages, the truncation of the discovery and the error reporting;
  • the period calculation, including that the datapoint budget is never exceeded;
  • variable replacement, dependsOn and query validation;
  • the endpoints of the regions and the datasource validation.
• oxfmt --check, cue fmt, mdox and the license check.
• percli plugin lint passes, and percli plugin test-schemas passes all 9 schema tests.
• Go SDK: go vet, go test and golangci-lint v2.13.2 (0 issues).
• The signing itself is covered by the tests of the perses/perses SigV4 change. No live AWS account was used.

Screenshots

The editors use the standard MUI fields of the other plugins. I'll add screenshots once the SigV4 change is available in a running Perses.

Checklist

• Pull request has a descriptive title and context useful to a reviewer.
• Pull request title follows the [<catalog_entry>] <commit message> naming convention.
• All commits have DCO signoffs.

UI Changes

• Changes that impact the UI include screenshots and/or screencasts of the relevant changes.
• Code follows the UI guidelines.

[AntoineThebaud]

Please don't forget to document this new plugin by adding content to https://github.com/perses/plugins/tree/main/docs

[T-Chittibabu]

Thanks @AntoineThebaud, I added the docs in docs/cloudwatch (overview and setup, data model and Go SDK). I also reworked the plugin following the discussion in perses/perses#4547: it now uses a regular HTTP proxy with SigV4 instead of a dedicated proxy.