> 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-protection-protection/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/configure-the-agentcore-collector.md).

# Configure the AgentCore collector

The AgentCore collector brings traces from Amazon Bedrock AgentCore into Harness. It is one of the three collectors in the AWS CloudWatch agent, and it behaves differently from the other two. The API Gateway and Bedrock collectors read request and response logs. The AgentCore collector reads trace spans, joins them with the matching runtime logs, and sends the result as OpenTelemetry (OTLP) traces.

This topic explains how the collector finds its data, what its settings do, and what happens to spans that cannot be completed.

## What will you learn in this topic?

By the end of this topic, you will understand:

* The way the AgentCore collector finds and combines its data.
* The steps to turn the collector on for each installation method.
* The purpose of each AgentCore setting and its default value.
* The permissions the collector needs, and what happens when enrichment fails.

***

## Before you begin

* Make sure you have installed the AWS CloudWatch agent using Terraform, CloudFormation, or a manual install. For more information, see [AWS CloudWatch agent overview](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-protection-protection/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview.md).
* Make sure AgentCore observability is enabled in your account so AgentCore produces spans. AWS describes the steps in its [AgentCore observability documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin).
* Make sure the agent's IAM role has the permissions listed in [Review the IAM permissions](#review-the-iam-permissions).
* Make sure you have enabled the AgentCore collector. Collectors are off by default, and enabling the API Gateway or Bedrock collector does not enable this one.

***

## Turn on the collector

Each installation method has its own collector settings. Set it to `true`, then apply the change or reinstall the agent as you normally would. The following table lists the settings to use for each installation method.

| Installation Method   | Setting                                                   |
| --------------------- | --------------------------------------------------------- |
| Terraform             | `enable_agentcore_collector = true` in `terraform.tfvars` |
| CloudFormation        | `EnableAgentCoreCollector` set to `true`                  |
| Manual install on EC2 | `--enable-agentcore true` on the installer command        |

***

## Understand how the collector works

The collector reads from two places in CloudWatch Logs, and it needs both to produce a complete trace.

* **The source log group, `aws/spans`.** This is the AWS-managed log group where AgentCore writes its spans. AWS manages this log group, so neither you nor the collector can change its name or location.
* **The enrichment log groups, `/aws/bedrock-agentcore/runtimes/*/otel-rt-logs`.** These hold the prompt and completion bodies for each span. The collector matches a log entry to a span by its `traceId:spanId` pair, and adds the content to the span. The agent finds these log groups on its own, so unlike the Bedrock collector, you do not name them in your configuration.

The collector then posts the enriched spans as OTLP data to `<endpoint>/v1/traces`. This is a different path from the API Gateway and Bedrock collectors, which post to `<endpoint>/ext_cap/v1/req_res_list_cap`. The base URL is the same TPA endpoint for all three.

The region comes from the account entry you configured. If the entry has no region, the collector uses the default region that the AWS SDK resolves from the host's environment or configuration.

### Service name

The service name for AgentCore traffic always comes from the AgentCore resource itself, which is the AgentCore agent or runtime name in the span's resource attributes. The `--service-name` flag and the `SERVICE_NAME` Environment variables are ignored for this collector. That is why you see the AgentCore resource's name in Harness, not the value you set for the other collectors.

### What happens when enrichment fails

Sometimes a span cannot be enriched, for example, when its runtime log entry is missing. The collector drops only that span, and only when it is a leaf span. It never drops the parent of a dropped span, so the trace keeps its structure.

Each time this happens, the collector logs a line that starts with `Dropped N span(s)`, where `N` is the number of spans dropped. If traces look incomplete, search the agent logs for that line. For the steps, see [Troubleshooting the AWS CloudWatch agent](https://developer.harness.io/web-application-and-api-protection-waap-discovery-discovery-protection-protection/data-collection/gateways-load-balancers/aws/aws-cloudwatch-agent-overview/troubleshooting-the-aws-cloudwatch-agent.md).

***

## Check your data

Give the agent one run interval (5 minutes by default), then look for your AgentCore 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.

Look for the name of your AgentCore resource, because that is the service name the collector uses.

***

## Review the AgentCore settings

Use the following table when you run the collector directly, as in the manual install. Terraform and CloudFormation set these values for you through their own parameters. The table lists each setting with its flag, its environment variable, its default, and what it does.

| Flag                            | Environment Variable     | Default                 | What It Does                                                                                                      |
| ------------------------------- | ------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--tpa-endpoint`                | `TPA_ENDPOINT`           | `http://localhost:5442` | The TPA endpoint the collector posts traces to.                                                                   |
| `--token`                       | `TA_TOKEN`               | None                    | The agent token, sent in the `traceableai-agent-token` header.                                                    |
| `--guid`                        | `TA_GUID`                | None                    | The GUID, sent in the `x-traceable-guid` header.                                                                  |
| `--account`                     | `ACCOUNT`                | None                    | The account to read. The collector uses only the `region` and `cross_account_role_arn` fields.                    |
| `--environment`                 | `TA_ENVIRONMENT`         | None                    | The Harness environment. It must match the setting on the TPA, or Harness cannot associate the service correctly. |
| `--module-name`                 | None                     | `aws-cloudwatch`        | The module name, shared with the other collectors.                                                                |
| `--cross-account-role-arn`      | `CROSS_ACCOUNT_ROLE_ARN` | None                    | The role to assume when the AgentCore resources are in another account.                                           |
| None                            | None                     | `50`                    | The number of spans the collector sends to the TPA in one request.                                                |
| None                            | None                     | `5` minutes             | How often the agent runs.                                                                                         |
| `--enable-checkpoint`           | None                     | Off                     | Turns on checkpointing. See [Use checkpointing](#use-checkpointing).                                              |
| `--no-checkpoint`               | None                     | None                    | Turns checkpointing off, even when another setting turns it on.                                                   |
| `--start-time` and `--end-time` | None                     | None                    | A fixed time window in epoch milliseconds. Available from the command line only.                                  |

### Use checkpointing

Checkpointing is off by default. Turn it on with `--enable-checkpoint` when you want each run to continue from where the previous one stopped, which avoids reading the same spans twice. The overlap defaults to 15 minutes. Use `--no-checkpoint` to force checkpointing off.

### Read a fixed time window

Pass `--start-time` and `--end-time` as epoch milliseconds to make one run read a specific window. This is useful for backfilling data or reproducing a problem. A run with an explicit window disables checkpointing for that run, so it does not move the checkpoint. These two flags are only available from the command line.

***

## Review the IAM permissions

The AgentCore collector needs a small set of permissions. The following table lists each one and the reason the collector needs it.

| Permission               | Why the Collector Needs It                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `logs:FilterLogEvents`   | Reads events from `aws/spans` and from the runtime log groups.                                    |
| `logs:DescribeLogGroups` | Discovers the runtime log groups when the collector needs to find them.                           |
| `sts:AssumeRole`         | Lets the collector assume the cross-account role. You need it only for cross-account deployments. |

These permissions are the same as those the task role already grants to the other collectors, so a working API Gateway or Bedrock setup usually requires no additional IAM changes.

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