> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/dstl8-docs/sources/aws-cloudwatch.md).

# AWS CloudWatch

### Add a CloudWatch source

#### 1. Open the Add Source dialog

From **Sources**, click **Add Source** and select **AWS CloudWatch**.

#### 2. Configure the source

Give the source a unique name.

By default, CloudWatch log groups are **auto-discovered** from the account. To customize, expand **Advanced config**:

* **Auto Discover** *(default)* — log groups are found automatically.
* **Log Groups** — manually specify log groups, one per line (e.g. `/aws/lambda/my-function`). Use this when you want to limit ingestion to a known set.

#### **3. Enter credentials**

| Field                              | Notes                                                 |
| ---------------------------------- | ----------------------------------------------------- |
| **AWS Access Key ID**              | From an IAM user or role with CloudWatch read access. |
| **AWS Secret Access Key**          | Paired with the access key ID.                        |
| **AWS Region**                     | Region where your log groups live, e.g. `us-east-1`.  |
| **AWS Session Token** *(optional)* | Required only when using temporary STS credentials.   |

Need credentials? Create a dedicated IAM user with read-only Logs access and mint an access key. Attach the AWS-managed [`CloudWatchLogsReadOnlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html) policy (ARN `arn:aws:iam::aws:policy/CloudWatchLogsReadOnlyAccess`), which grants the `logs:Describe*`, `logs:Get*`, `logs:List*`, and `logs:FilterLogEvents` read actions with no write access.

```bash
# 1) create the user
aws iam create-user --user-name cloudwatch-ro-logs

# 2) attach AWS-managed CloudWatchLogsReadOnlyAccess
aws iam attach-user-policy \
  --user-name cloudwatch-ro-logs \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchLogsReadOnlyAccess

# 3) mint an access key (only shown once -- capture immediately)
aws iam create-access-key --user-name cloudwatch-ro-logs
```

The `create-access-key` output returns the `AccessKeyId` and `SecretAccessKey` for the two fields above. The secret is shown only once, so capture it immediately. For temporary credentials, attach the same policy to a role, assume it with `aws sts assume-role`, and use the returned token in **AWS Session Token**.

Click **Test Connection**. You should see **Connection successful**.

#### 4. Create

Click **Create** to add the source.

### After creating

The source appears in the list as **Pending** with 0 streams. Within a couple of minutes, CloudWatch events begin arriving, streams are detected, and the source transitions to **Healthy**. Each stream is listed with its inferred **Stream Type** (e.g. `ec2/stage/clickhouse`, `eks`, `unknown`).

### Assign streams to workspaces

Streams need to be assigned to a workspace to be accessible. Open the source's actions menu (gear icon) and select **Assign Streams**, then check the streams you want the **Default** workspace (or any other workspace) to receive and **Save**.

See Assigning streams to workspaces for details.

### Tips

* Add a separate CloudWatch source per AWS account or region rather than sharing credentials across environments.
* Start with **Auto Discover** for the simplest setup; move to manual **Log Groups** when you need tighter control over what's ingested.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/dstl8-docs/sources/aws-cloudwatch.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.