[AWS Cloudwatch input] - Update documentation

packages/aws_cloudwatch_input_otel/_dev/build/docs/README.md

@@ -1,15 +1,35 @@
+{{- generatedHeader }}
 # AWS CloudWatch OpenTelemetry Input Package
 
 ## Overview
-The AWS CloudWatch OpenTelemetry Input Package for Elastic enables collection of CloudWatch metrics for selected AWS services through OpenTelemetry protocols using the [awscloudwatchmetricsreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchmetricsreceiver#aws-cloudwatch-metrics-receiver).
 
-### How it works
-This package configures the AWS region, credentials, and a CloudWatch namespace once per supported AWS service (EC2, RDS, SQS, ELB, Lambda, Fargate). The configuration is applied to the `awscloudwatchmetrics` receiver in the EDOT collector, which polls CloudWatch via the AWS API and forwards metrics to the Elastic Agent. The Elastic Agent enriches the data and ships it to Elasticsearch for indexing and analysis. The receiver runs in autodiscover mode so newly published metrics from AWS are picked up automatically without package changes.
+The AWS CloudWatch OpenTelemetry Input Package collects Amazon CloudWatch metrics for selected AWS services using the [AWS CloudWatch receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver) from the OpenTelemetry Collector.
+
+Instead of listing individual metrics, the package automatically discovers the metrics published in each service's CloudWatch namespace, so newly available metrics are picked up without any configuration changes. This makes it a low-maintenance way to bring AWS infrastructure metrics into Elastic for dashboards, alerting, and analysis.
+
+## How it works
+
+This package configures the AWS CloudWatch receiver in the EDOT (Elastic Distribution of OpenTelemetry) Collector, which:
+
+1. Authenticates to AWS using the credentials you provide.
+2. Discovers the metrics available in the selected service's CloudWatch namespace.
+3. Polls CloudWatch on a regular interval and retrieves the configured statistics (such as Average, Sum, and Maximum) for each metric.
+4. Forwards the metrics to Elastic Agent, which ships them to Elasticsearch for indexing and visualization.
+
+You add the integration once for each AWS service you want to monitor.
+
+## Deployment modes
+
+This package can be deployed in two ways:
+
+- **Agentless** (default): Elastic manages the collector for you, with no infrastructure to run. This is the recommended option for most users.
+- **Elastic Agent**: Run the collector on your own Elastic Agent.
 
 ## Supported services
-Each service is exposed as a separate policy template. Add the integration once per service you want to monitor.
 
-| Policy template | CloudWatch namespace |
+Each AWS service is available as a separate option when you add the integration.
+
+| Service | CloudWatch namespace |
 |---|---|
 | AWS EC2 | `AWS/EC2` |
 | AWS Lambda | `AWS/Lambda` |
@@ -18,5 +38,58 @@ Each service is exposed as a separate policy template. Add the integration once
 | AWS Application ELB | `AWS/ApplicationELB` |
 | AWS ECS / Fargate | `AWS/ECS` |
 
+Each service collects a set of statistics chosen to suit that service's metrics (for example, averages for utilization metrics and sums for counters). These defaults work well out of the box and require no configuration.
+
+## Requirements
+
+- An AWS account with the services you want to monitor.
+- AWS credentials with permission to read CloudWatch metrics. At minimum, the credentials must allow:
+  - `cloudwatch:ListMetrics`
+  - `cloudwatch:GetMetricData`
+- The AWS region your resources run in.
+
+## Configuration
+
+### Core settings
+
+| Setting | Description |
+|---|---|
+| AWS Region | The AWS region to collect metrics from (for example, `us-east-1`). |
+| AWS Access Key ID | The access key used to authenticate to AWS. |
+| AWS Secret Access Key | The secret key paired with the access key. |
+| AWS Session Token | Required only when using temporary (STS) credentials. |
+
+## Authentication
+
+The package supports the following ways to authenticate to AWS:
+
+- **Access keys**: Provide an access key ID and secret access key.
+- **Temporary credentials**: Provide an access key ID, secret access key, and session token.
+- **IAM role assumption**: Provide a Role ARN (and optionally an External ID) under the advanced settings to assume a role.
+
+Use credentials scoped to read-only CloudWatch access wherever possible.
+
 ## Metrics reference
-For a complete list of available metrics in each namespace, refer to the [Amazon CloudWatch metrics and dimensions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CW_Support_For_AWS.html). For receiver configuration options, refer to the [`awscloudwatchmetricsreceiver` documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/awscloudwatchmetricsreceiver/README.md) in the upstream OpenTelemetry Collector repository.
+
+For the complete list of metrics available in each namespace, see the [Amazon CloudWatch metrics and dimensions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CW_Support_For_AWS.html).
+
+## Troubleshooting
+
+### No metrics appear
+
+1. Confirm the AWS Region matches where your resources are running.
+2. Verify the credentials are valid and not expired (temporary credentials require a session token).
+3. Ensure the credentials have `cloudwatch:ListMetrics` and `cloudwatch:GetMetricData` permissions.
+4. Allow time for the first collection cycle to complete, and remember that CloudWatch publishes metrics with a short delay.
+
+### Authentication errors
+
+1. Double-check the access key ID and secret access key.
+2. If using temporary credentials, make sure the session token is set and current.
+3. If assuming a role, verify the Role ARN and, if required, the External ID.
+
+## Further reading
+
+- [Amazon CloudWatch documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)
+- [AWS CloudWatch receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver)
+- [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/)

packages/aws_cloudwatch_input_otel/changelog.yml

@@ -1,4 +1,9 @@
 # newer versions go on top
+- version: "0.3.1"
+  changes:
+    - description: Update the integration documentation.
+      type: enhancement
+      link: https://github.com/elastic/integrations/pull/19624
 - version: "0.3.0"
   changes:
     - description: Add support for region specific to a service.

packages/aws_cloudwatch_input_otel/docs/README.md

@@ -1,15 +1,36 @@
+<!-- NOTICE: Do not edit this file manually.-->
+<!-- This file is automatically generated by Elastic Package -->
 # AWS CloudWatch OpenTelemetry Input Package
 
 ## Overview
-The AWS CloudWatch OpenTelemetry Input Package for Elastic enables collection of CloudWatch metrics for selected AWS services through OpenTelemetry protocols using the [awscloudwatchmetricsreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchmetricsreceiver#aws-cloudwatch-metrics-receiver).
 
-### How it works
-This package configures the AWS region, credentials, and a CloudWatch namespace once per supported AWS service (EC2, RDS, SQS, ELB, Lambda, Fargate). The configuration is applied to the `awscloudwatchmetrics` receiver in the EDOT collector, which polls CloudWatch via the AWS API and forwards metrics to the Elastic Agent. The Elastic Agent enriches the data and ships it to Elasticsearch for indexing and analysis. The receiver runs in autodiscover mode so newly published metrics from AWS are picked up automatically without package changes.
+The AWS CloudWatch OpenTelemetry Input Package collects Amazon CloudWatch metrics for selected AWS services using the [AWS CloudWatch receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver) from the OpenTelemetry Collector.
+
+Instead of listing individual metrics, the package automatically discovers the metrics published in each service's CloudWatch namespace, so newly available metrics are picked up without any configuration changes. This makes it a low-maintenance way to bring AWS infrastructure metrics into Elastic for dashboards, alerting, and analysis.
+
+## How it works
+
+This package configures the AWS CloudWatch receiver in the EDOT (Elastic Distribution of OpenTelemetry) Collector, which:
+
+1. Authenticates to AWS using the credentials you provide.
+2. Discovers the metrics available in the selected service's CloudWatch namespace.
+3. Polls CloudWatch on a regular interval and retrieves the configured statistics (such as Average, Sum, and Maximum) for each metric.
+4. Forwards the metrics to Elastic Agent, which ships them to Elasticsearch for indexing and visualization.
+
+You add the integration once for each AWS service you want to monitor.
+
+## Deployment modes
+
+This package can be deployed in two ways:
+
+- **Agentless** (default): Elastic manages the collector for you, with no infrastructure to run. This is the recommended option for most users.
+- **Elastic Agent**: Run the collector on your own Elastic Agent.
 
 ## Supported services
-Each service is exposed as a separate policy template. Add the integration once per service you want to monitor.
 
-| Policy template | CloudWatch namespace |
+Each AWS service is available as a separate option when you add the integration.
+
+| Service | CloudWatch namespace |
 |---|---|
 | AWS EC2 | `AWS/EC2` |
 | AWS Lambda | `AWS/Lambda` |
@@ -18,5 +39,58 @@ Each service is exposed as a separate policy template. Add the integration once
 | AWS Application ELB | `AWS/ApplicationELB` |
 | AWS ECS / Fargate | `AWS/ECS` |
 
+Each service collects a set of statistics chosen to suit that service's metrics (for example, averages for utilization metrics and sums for counters). These defaults work well out of the box and require no configuration.
+
+## Requirements
+
+- An AWS account with the services you want to monitor.
+- AWS credentials with permission to read CloudWatch metrics. At minimum, the credentials must allow:
+  - `cloudwatch:ListMetrics`
+  - `cloudwatch:GetMetricData`
+- The AWS region your resources run in.
+
+## Configuration
+
+### Core settings
+
+| Setting | Description |
+|---|---|
+| AWS Region | The AWS region to collect metrics from (for example, `us-east-1`). |
+| AWS Access Key ID | The access key used to authenticate to AWS. |
+| AWS Secret Access Key | The secret key paired with the access key. |
+| AWS Session Token | Required only when using temporary (STS) credentials. |
+
+## Authentication
+
+The package supports the following ways to authenticate to AWS:
+
+- **Access keys**: Provide an access key ID and secret access key.
+- **Temporary credentials**: Provide an access key ID, secret access key, and session token.
+- **IAM role assumption**: Provide a Role ARN (and optionally an External ID) under the advanced settings to assume a role.
+
+Use credentials scoped to read-only CloudWatch access wherever possible.
+
 ## Metrics reference
-For a complete list of available metrics in each namespace, refer to the [Amazon CloudWatch metrics and dimensions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CW_Support_For_AWS.html). For receiver configuration options, refer to the [`awscloudwatchmetricsreceiver` documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/awscloudwatchmetricsreceiver/README.md) in the upstream OpenTelemetry Collector repository.
+
+For the complete list of metrics available in each namespace, see the [Amazon CloudWatch metrics and dimensions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CW_Support_For_AWS.html).
+
+## Troubleshooting
+
+### No metrics appear
+
+1. Confirm the AWS Region matches where your resources are running.
+2. Verify the credentials are valid and not expired (temporary credentials require a session token).
+3. Ensure the credentials have `cloudwatch:ListMetrics` and `cloudwatch:GetMetricData` permissions.
+4. Allow time for the first collection cycle to complete, and remember that CloudWatch publishes metrics with a short delay.
+
+### Authentication errors
+
+1. Double-check the access key ID and secret access key.
+2. If using temporary credentials, make sure the session token is set and current.
+3. If assuming a role, verify the Role ARN and, if required, the External ID.
+
+## Further reading
+
+- [Amazon CloudWatch documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)
+- [AWS CloudWatch receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver)
+- [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/)