> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/manual-install-on-ec2.md).

# Manual install on EC2

The manual install puts the AWS CloudWatch agent directly on a Linux host and runs it as a cron job. There is no Terraform module, no CloudFormation stack, and no container image to pull. You copy one archive to the host, run one script, and the script registers the schedule.

This method is the right one for an EC2 instance you already manage, and it is the recommended choice for airgapped environments where the host cannot pull images. If you want AWS to build the infrastructure for you, use [Deployment using Terraform](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/deployment-using-terraform.md) or [Deployment using CloudFormation](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/deployment-using-cloudformation.md) instead.

## What will you learn in this topic?

By the end of this topic, you will understand:

* The steps to prepare the host, its IAM permissions, and your AWS services.
* The steps to run the installer and confirm that the cron job exists.
* The purpose of each installer flag.
* The way to remove the agent from the host.

***

## Before you begin

* Make sure that you have an EC2 instance or another Linux host that can reach your AWS account, and that you have `sudo` or root access on it. The installer writes to system locations, so it requires root access.
* Make sure that an IAM role or instance profile is attached to the host with the permissions listed in [Attach the IAM permissions](#attach-the-iam-permissions).
* Make sure that you have a TPA set up, and that the host can reach its URL. The agent sends all its data to the TPA, so follow the [TPA installation guide](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/installation/platform-agent.md) first, then note the TPA's URL. You pass it as `--tpa-endpoint` in Step 4.
* Make sure that `jq`, a command-line tool for processing JSON, is installed on the machine where you build the `ACCOUNTS_JSON` value. Step 3 uses it to encode your account settings.
* Make sure that you know which collectors you want. You must turn on at least one, or the installer stops before it writes the cron job.
* Make sure that API Gateway logging, Bedrock model-invocation logging, or AgentCore observability is turned on for the services you want to collect. Step 1 covers all three.

***

## Step 1: Prepare your AWS services

The agent does not create logs. It reads logs that your AWS services already write to CloudWatch Logs, so each service you want to collect from has to be logging first. The three collectors read different logs, so the preparation differs for each. API Gateway needs access logs in a specific JSON format. Bedrock needs model invocation logging enabled, plus the name of its log group, in your agent configuration. AgentCore needs observability turned on and nothing more.

Do only the parts for the collectors you plan to turn on. If you turn on more than one, do each part.

### API Gateway (REST APIs)

Use this section if the API Gateway collector will read REST APIs. The collector reads each stage's access logs, so every stage you want to collect from must write them in a format the agent can parse.

Complete the following for every stage you want to collect from:

1. Open the API Gateway console and select your API, then select the stage.
2. Go to **Logs/tracing**.
3. In the **CloudWatch Logs** drop-down, select **Error and info logs**.
4. Turn on **Custom Access Logging**.
5. In **Access log destination ARN**, enter the ARN of a CloudWatch log group. This is where API Gateway writes the access logs that the agent reads.
6. In **Log Format**, paste the following JSON:

```json
{
  "requestId": "$context.requestId",
  "ip": "$context.identity.sourceIp",
  "httpMethod": "$context.httpMethod",
  "path": "$context.path",
  "status": "$context.status",
  "responseLength": "$context.responseLength",
  "domainName": "$context.domainName"
}
```

Each field maps to an API Gateway `$context` variable. API Gateway fills the variables in for every request, so each log line carries the request ID, the caller's IP address, the HTTP method, the path, the status code, the response size, and the domain name. The agent expects these fields in every log line, so leave none out.

### API Gateway (HTTP APIs)

Use this section if the API Gateway collector will read HTTP APIs. The agent reads them the same way it reads REST APIs, so the log format is the same. Only the place where you turn logging on differs.

Turn on access logging for the stage and use the same JSON format as in the REST APIs section. That way, every log line carries the fields the agent needs.

### Bedrock

Use this section if you turn on the Bedrock collector. The collector reads Bedrock's model invocation logs from CloudWatch Logs, so you need to complete two tasks: turn on logging in Amazon Bedrock, and tell the agent which log group to read.

{% hint style="info" %}
**Note**: The Bedrock collector reads model invocation logs, which AWS provides for Amazon Bedrock Runtime. It does not collect data from Bedrock Mantle, because AWS does not support model invocation logging for it.
{% endhint %}

1. Turn on model invocation logging in Amazon Bedrock, and send the logs to a CloudWatch Logs log group. AWS describes the steps in its [model invocation logging documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-invocation-logging.html).
2. Add the name of that log group to the `log_groups` field of the matching object in `ACCOUNTS_JSON`, which Step 3 explains. The Bedrock collector does not discover this log group on its own, so it reads only the log groups that you list.

If the API Gateway collector is also on, list the API Gateway log groups in the same `log_groups` field as well.

### AgentCore

Use this section if you turn on the AgentCore collector. It needs the least setup on your side, because the agent finds its own log groups. All it needs is for AgentCore to produce observability data.

Turn on AgentCore observability by following the [AWS documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). The agent discovers all AgentCore log groups on its own, so you do not list any.

***

## Attach the IAM permissions

The agent runs on your host, so it uses the host's IAM role. Attach an IAM role or instance profile with these permissions:

```
apigateway:GET
logs:DescribeLogGroups
logs:FilterLogEvents
sts:AssumeRole
```

`logs:DescribeLogGroups` lets the agent find log groups, and `logs:FilterLogEvents` lets it read the events. `apigateway:GET` lets it read API Gateway details. You need `sts:AssumeRole` only when you collect from another account, because that is how the agent switches to the cross-account role. For the role itself, see Step 3 in [Deployment using Terraform](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/deployment-using-terraform.md) or [Deployment using CloudFormation](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/deployment-using-cloudformation.md).

***

## Step 2: Download the archive and copy it to the host

Download the airgapped archive from the Downloads site:

```
https://downloads.traceable.ai/install/aws-cloudwatch/offline-setup/x86-64/latest/aws-cloudwatch-airgapped.tar.gz
```

The archive is self-contained, so the host does not need to pull anything from the internet during the install. That is what makes this method work in airgapped environments. If your host has no internet access, download the file on another machine and copy it over. The `x86-64` in the path shows the host architecture the archive is for.

Copy the archive to the host, then extract it and move into the new directory:

```
tar xvzf aws-cloudwatch-airgapped.tar.gz
cd traceable
```

`tar xvzf` unpacks the gzip archive and lists each file as it goes. The archive extracts to a directory named `traceable`, and `offline-installer.sh` lives there.

***

## Step 3: Build the ACCOUNTS\_JSON value

The installer needs to know which accounts and regions to read. You pass that as a JSON array, with each element being a base64-encoded JSON object.

Start with one object per account-region pair. The following table describes each key you can set inside an object.

| Key                      | Required | What It Does                                                                                                                                                                                                                            |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`                 | Yes      | The AWS region to collect from.                                                                                                                                                                                                         |
| `api_list`               | Yes      | A list of API IDs. To target one stage, write `<api_id>/<stage_name>`.                                                                                                                                                                  |
| `exclude`                | Yes      | Decides how the agent treats the `api_list` entries. It applies to the API Gateway collector only. Set it to `false` to collect only the listed APIs. Set it to `true` to collect everything except the listed APIs.                    |
| `cross_account_role_arn` | Yes      | The ARN of the cross-account role. Use an empty string when the APIs are in the same account as the host.                                                                                                                               |
| `log_groups`             | No       | A list of log group names to read directly. For the Bedrock collector, list the model-invocation log group here. If the API Gateway collector is also on and you list log groups for Bedrock, list the API Gateway log groups here too. |
| `access_log_format`      | No       | A map that describes the access log format your API Gateway instances use. It is required when you set `log_groups`.                                                                                                                    |

{% hint style="info" %}
**Note**: The AgentCore collector uses only `region` and `cross_account_role_arn` from each object, and it discovers its own log groups.
{% endhint %}

Then run this command to encode them:

```
ACCOUNTS_JSON=$(jq -c '[.[] | @base64]' <<'EOF'
[
  {
    "region": "us-east-1",
    "api_list": ["<api-id>"],
    "cross_account_role_arn": "",
    "exclude": false
  }
]
EOF
)
```

The command works in three parts. The `<<'EOF'` block feeds your JSON to `jq` as input. `jq` takes each element of the array and applies `@base64`, which encodes it, and `-c` keeps the result on one line. The `$( ... )` wrapper stores that output in the shell variable `ACCOUNTS_JSON`, ready for the next step. To collect from more than one account or region, add more objects to the array.

***

## Step 4: Run the installer

Run the installer as root, and turn on at least one collector:

```
sudo ./offline-installer.sh \
  --accounts "$ACCOUNTS_JSON" \
  --tpa-endpoint "http://localhost:5442" \
  --service-name "aws-cloudwatch" \
  --environment "$TA_ENVIRONMENT" \
  --token "$TA_TOKEN" \
  --guid "$TA_GUID" \
  --enable-api-gateway true \
  --enable-bedrock true \
  --enable-agentcore false
```

The script installs the agent files, then registers a cron job so the agent runs on a schedule. Each flag sets one thing:

* `--accounts` passes the value you built in Step 3.
* `--tpa-endpoint` sets the URL of the TPA that receives the data the agent collects.
* `--service-name` sets the service name that Harness shows.
* `--environment`, `--token`, and `--guid` are optional values that identify your environment and authenticate the agent. You need them only when the TPA is hosted by Harness.
* `--enable-api-gateway`, `--enable-bedrock`, and `--enable-agentcore` each turn one collector on or off. Every one takes an explicit `true` or `false`.

If all three collector flags are `false`, the installer stops before it writes the cron job and prints the "at least one collector must be enabled" error.

{% hint style="info" %}
**Note**: The installer writes `--environment`, `--token`, and `--guid` into the cron file, `/etc/cron.d/traceable-awscloudwatch`. Because the token is sensitive, limit read access to that file and to the host.
{% endhint %}

***

## Step 5: Verify the installation

Confirm that the installer created the cron job:

```
cat /etc/cron.d/traceable-awscloudwatch
```

This prints the cron entry the installer registered. If the file exists and shows your settings, the agent will run on its next scheduled interval. The agent writes its logs to `/var/traceable/log/aws-cloudwatch` unless you set `--log-dir`, so look there if you want to watch a run.

Then give the agent one run interval (5 minutes by default) and check Harness for your traffic:

* Go to **Insights** → **Explore Data** to view the traces and spans directly.
* Go to **Discovery** → **Inventory** to view the services and endpoints the agent discovered.

API Gateway and Bedrock traffic appears under the service name you set with `--service-name`, which is `aws-cloudwatch` by default. AgentCore traffic appears under the name of the AgentCore resource.

If the cron file is missing or no data arrives, go through [Troubleshooting the AWS CloudWatch agent](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/troubleshooting-the-aws-cloudwatch-agent.md).

***

## Installer flag reference

The installer takes two groups of flags. The collector flags decide what the agent reads. The general flags decide where it installs, where it sends data, and how often it runs. Check the collector flags first, because the installer will not run without at least one of them.

### Collector flags

These three flags turn the collectors on and off, so every install uses at least one. The following table lists each flag with its default.

| Flag                   | Required               | Default | What It Does                                                                                                                                                                                                                                                                                                                                                |
| ---------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-api-gateway` | At least one collector | `false` | Turns on the API Gateway collector. Accepts `true` or `false`.                                                                                                                                                                                                                                                                                              |
| `--enable-bedrock`     | At least one collector | `false` | Turns on the Bedrock collector. Accepts `true` or `false`.                                                                                                                                                                                                                                                                                                  |
| `--enable-agentcore`   | At least one collector | `false` | Turns on the AgentCore collector. Accepts `true` or `false`. For its extra settings, see [Configure the AgentCore collector](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/configure-the-agentcore-collector.md). |

### General flags

These flags control the rest of the install, and most of them have a default you can leave alone. The following table lists every other installer flag, with its default and the reason you might change it.

| Flag                   | Required | Default                             | What It Does and Why You Might Change It                                                                                            |
| ---------------------- | -------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--accounts`           | Yes      | None                                | The JSON array of base64-encoded account objects that you built in Step 3.                                                          |
| `--log-dir`            | No       | `/var/traceable/log/aws-cloudwatch` | Where the agent writes its logs. Change it if you keep logs on a separate volume.                                                   |
| `--root-dir`           | No       | `/var/traceable/aws-cloudwatch`     | Where the agent binaries, configuration, and helper scripts are installed.                                                          |
| `--service-name`       | No       | `aws-cloudwatch`                    | The service name Harness shows. It applies to the API Gateway and Bedrock collectors only.                                          |
| `--tpa-endpoint`       | No       | `http://localhost:5442`             | Where the agent sends data. Change it when your TPA runs somewhere else.                                                            |
| `--tpa-max-batch-size` | No       | `500`                               | The maximum number of spans in one request to the TPA. Lower it if requests to your TPA time out.                                   |
| `--cron-interval-mins` | No       | `5`                                 | How often the agent runs, in minutes.                                                                                               |
| `--environment`        | No       | `""`                                | The name of your Harness environment. The agent sends it to the TPA as the `traceableai-environment-name` header.                   |
| `--token`              | No       | `""`                                | The agent token that authenticates the agent with a Harness-hosted TPA. The agent sends it as the `traceableai-agent-token` header. |
| `--guid`               | No       | `""`                                | The GUID that a Harness-hosted TPA expects with each request. The agent sends it as the `x-traceable-guid` header.                  |

The agent leaves out any header whose value is empty. You need `--environment`, `--token`, and `--guid` only when `--tpa-endpoint` points to a Harness-hosted (SaaS) TPA. For a self-hosted TPA, leave them out.

***

## Uninstall the agent

Run these commands on the host, as root or with `sudo`:

```
rm -f /etc/cron.d/traceable-awscloudwatch
rm -rf /var/traceable/aws-cloudwatch
rm -rf /var/traceable/log/aws-cloudwatch
```

The first command deletes the cron file, so the agent stops running. The second deletes the installation directory, and the third deletes the log directory. Run the commands in this order so the schedule is gone before the files are.

If the `traceable` system user exists on the host, and you created it only for this agent, you can remove it too:

```
userdel traceable
```

Check that no other process depends on that user before you run this command.

For more information, see [AWS CloudWatch agent overview](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview.md) and [Configure the AgentCore collector](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-api-security-testing/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/configure-the-agentcore-collector.md).
