[
  {
    "id": "agentcore-obs-smoke-test",
    "prompt": "Read agent-context.json. List each target's label, host, and region. No analysis needed.",
    "expected_output": "Lists every target from files/agent-context.json with its label, host, and region exactly as defined in the file.",
    "files": ["files/agent-context.json"],
    "assertions": [
      "contains 'orders-agent'",
      "contains 'billing-agent'",
      "matches regex /[a-z]{2}-[a-z]+-\\d/",
      "contains 'runtime'",
      "contains 'lambda'"
    ]
  },
  {
    "id": "agentcore-obs-operating-principle",
    "prompt": "According to the skill, what is the operating principle for deciding whether a check is confirmed or only recommended? Name the two check types. No account access required.",
    "expected_output": "States 'verify where reachable, prescribe everywhere else' and names VERIFY and PRESCRIBE as the two check types.",
    "files": [],
    "assertions": [
      "contains 'verify' or contains 'VERIFY'",
      "contains 'prescribe' or contains 'PRESCRIBE'"
    ]
  },
  {
    "id": "agentcore-obs-transaction-search-root-cause",
    "prompt": "A user reports their AgentCore runtime agent runs fine but no traces appear in CloudWatch. According to the skill, what account-level prerequisite is the most common silent root cause, and how is it verified? No account access required.",
    "expected_output": "Identifies CloudWatch Transaction Search as the prerequisite and states it is verified via xray:GetTraceSegmentDestination (destination CloudWatchLogs, status ACTIVE), or inferred from whether spans are arriving.",
    "files": [],
    "assertions": [
      "contains 'Transaction Search'",
      "contains 'GetTraceSegmentDestination' or contains 'span' or contains 'CloudWatch Logs'"
    ]
  },
  {
    "id": "agentcore-obs-permission-tiers",
    "prompt": "List the three read-only IAM tiers the skill uses and one capability each tier unlocks. No account access required.",
    "expected_output": "Describes Tier 1 (standard CloudWatch logs/metrics telemetry-arrival verification), Tier 2 (runtime config: Transaction Search, GetAgentRuntime, deliveries, resource policy), and Tier 3 (non-runtime host config for Lambda/ECS/EKS).",
    "files": [],
    "assertions": [
      "contains 'Tier 1' or contains 'Tier1'",
      "contains 'Tier 2' or contains 'Tier2'",
      "contains 'Tier 3' or contains 'Tier3'",
      "contains 'logs' or contains 'CloudWatch'",
      "contains 'bedrock-agentcore' or contains 'GetAgentRuntime'",
      "contains 'lambda' or contains 'ecs' or contains 'eks' or contains 'Lambda' or contains 'ECS' or contains 'EKS'"
    ]
  },
  {
    "id": "agentcore-obs-host-outcomes",
    "prompt": "According to the skill, what is the expected outcome (verify vs prescribe) for an agent hosted on EKS versus on-prem/multi-cloud? No account access required.",
    "expected_output": "EKS: verify telemetry arrival only + prescribe config (pod env not IAM-verifiable due to K8s RBAC). On-prem/multi-cloud: prescribe only.",
    "files": [],
    "assertions": [
      "contains 'EKS' or contains 'eks'",
      "contains 'telemetry' or contains 'prescribe' or contains 'RBAC'",
      "contains 'on-prem' or contains 'multi-cloud' or contains 'prescribe only' or contains 'prescribe-only'"
    ]
  },
  {
    "id": "agentcore-obs-severity-definitions",
    "prompt": "List the five severity levels the skill uses for findings, from most to least urgent. No account access required.",
    "expected_output": "Lists CRITICAL, HIGH, MEDIUM, LOW, INFO in that order.",
    "files": [],
    "assertions": [
      "contains 'CRITICAL'",
      "contains 'HIGH'",
      "contains 'MEDIUM'",
      "contains 'LOW'",
      "contains 'INFO'"
    ]
  }
]

[
  {"query": "Which skill would help me validate that AgentCore observability is configured correctly? Just name it; do not run it.", "should_trigger": true},
  {"query": "Is there a skill for diagnosing why my Bedrock agent has no traces in CloudWatch? Answer yes or no with the skill name; do not execute it.", "should_trigger": true},
  {"query": "Name the skill that sets up OTEL and tracing for an AgentCore agent. Do not run any validation.", "should_trigger": true},
  {"query": "Write a Python script that sorts a list of numbers", "should_trigger": false},
  {"query": "What's the weather forecast for Sydney this weekend?", "should_trigger": false},
  {"query": "Create a CloudFormation template for an S3 bucket", "should_trigger": false}
]

# AgentCore Observability — Check Catalog

Full catalog of checks the skill runs. Each check is tagged **VERIFY** (confirmable via a read-only
API) or **PRESCRIBE** (cannot be read; validate the effect and emit steps). Every finding gets a
severity: CRITICAL / HIGH / MEDIUM / LOW / INFO.

All operations are read-only. Never mutate IAM, configuration, or resources.

---

## Account-level prerequisites

| # | Check | Type | API / signal | Pass condition | Fail severity |
|---|-------|------|--------------|----------------|---------------|
| A1 | CloudWatch Transaction Search enabled | VERIFY (Tier 2) | `xray:GetTraceSegmentDestination` | `Destination = CloudWatchLogs` and `Status = ACTIVE` | CRITICAL |
| A2 | Transaction Search (inferred) | VERIFY (Tier 1) | span log streams receiving data | spans present after invocations | CRITICAL (inferred) |

Transaction Search is the most common silent root cause: without it, AgentCore cannot deliver spans
to CloudWatch Logs, so traces never appear even when the agent runs and instrumentation is correct.

---

## Runtime agents (`/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint>`)

| # | Check | Type | API / signal | Pass condition | Fail severity |
|---|-------|------|--------------|----------------|---------------|
| R1 | Agent log group exists | VERIFY (Tier 1) | `logs:DescribeLogGroups` prefix `/aws/bedrock-agentcore/runtimes/` | log group present | HIGH |
| R2 | Runtime logs arriving | VERIFY (Tier 1) | `logs:FilterLogEvents` on `runtime-logs` stream, last 24h | recent events after invocations | HIGH |
| R3 | Spans flowing | VERIFY (Tier 1) | `spans` stream in agent log group **or** shared `aws/spans` | spans present after invocations | CRITICAL |
| R4 | Session metrics emitting | VERIFY (Tier 1) | `cloudwatch:ListMetrics` namespace `bedrock-agentcore` | metrics present | MEDIUM |
| R5 | Runtime tracing / ADOT not disabled | VERIFY (Tier 2) | `bedrock-agentcore:GetAgentRuntime` env | `DISABLE_ADOT_OBSERVABILITY` not unintentionally `true` | HIGH |
| R6 | Span destination mode | VERIFY (Tier 2) | `GetAgentRuntime` env `UNIFIED_TRACES_DESTINATION_ENABLED` | matches intended destination. **Default-on for agents created after 2026-07-20 in supported Regions** (agent's own log group); agents created before that date default to shared `aws/spans` unless opted in | INFO/LOW |
| R7 | X-Ray resource policy on log group | VERIFY (Tier 2) | `logs:DescribeResourcePolicies` | policy allows `xray.amazonaws.com` `logs:PutLogEvents` on the agent log group | HIGH — **applies by default for agents created after 2026-07-20 in supported Regions**, since unified span destination is the new default (per the AgentCore release notes). Mark N/A only when the agent was created before 2026-07-20 and still delivers to shared `aws/spans`, or the customer has explicitly opted out via `UNIFIED_TRACES_DESTINATION_ENABLED=false`. |
| R8 | ADOT distro in requirements | PRESCRIBE | — | `aws-opentelemetry-distro>=0.10.0` (≥0.18.0 for unified spans) present | HIGH (if spans absent) |
| R9 | `opentelemetry-instrument` launch | PRESCRIBE | — | agent launched via `opentelemetry-instrument python main.py` | HIGH (if spans absent) |
| R10 | Framework tracing + auto-instrumentor | PRESCRIBE | — | framework emits OTEL (Strands tracer / `opentelemetry-instrumentation-langchain` / OpenInference / Openllmetry / OpenLit / Traceloop) | MEDIUM |
| R11 | Session-id propagation | PRESCRIBE | — | `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` set on invoke | LOW |

---

## Memory & Gateway resources

Default vended log group: `/aws/vendedlogs/bedrock-agentcore/{memory|gateway}/APPLICATION_LOGS/{resource-id}`

| # | Check | Type | API / signal | Pass condition | Fail severity |
|---|-------|------|--------------|----------------|---------------|
| M1 | Log delivery configured | VERIFY (Tier 2) | `logs:DescribeDeliverySources` / `DescribeDeliveries` | `APPLICATION_LOGS` source bound to the resource ARN with an active delivery | HIGH |
| M2 | Logs arriving | VERIFY (Tier 1) | `logs:FilterLogEvents` on the vended log group | recent events | MEDIUM |
| M3 | Tracing delivery configured | VERIFY (Tier 2) | `DescribeDeliveries` for a `TRACES`→XRAY delivery | traces delivery present | MEDIUM |
| M4 | Tracing enabled (resource) | PRESCRIBE | — | tracing toggle enabled on the memory/gateway resource | MEDIUM |

---

## Built-in tools (code interpreter, browser)

| # | Check | Type | Pass condition | Fail severity |
|---|-------|------|----------------|---------------|
| B1 | Custom log output configured | PRESCRIBE | customer emits logs from tool code to a log destination | MEDIUM |
| B2 | Telemetry arriving | VERIFY (Tier 1) | target log group receiving data (only if B1 present) | LOW |
| B3 | Trace headers on tool APIs | PRESCRIBE | `X-Amzn-Trace-Id` / `traceparent` passed to Start*/Invoke*/Stop* APIs | LOW |

---

## Non-runtime hosts

| # | Check | Type | API / signal | Pass condition | Fail severity |
|---|-------|------|--------------|----------------|---------------|
| L1 | Lambda OTEL layer + wrapper | VERIFY (Tier 3) | `lambda:GetFunctionConfiguration` | OTEL Layer attached and `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument` | HIGH |
| L2 | Lambda agent log-group env | VERIFY (Tier 3) | `GetFunctionConfiguration` env | agent log group + OTEL vars set | HIGH |
| E1 | ECS OTEL env in task def | VERIFY (Tier 3) | `ecs:DescribeTaskDefinition` | container env carries the OTEL variable set | HIGH |
| K1 | EKS telemetry arriving | VERIFY (Tier 1) | agent log group receiving data | events present | HIGH |
| K2 | EKS pod/ConfigMap OTEL env | PRESCRIBE | — | not IAM-verifiable (K8s RBAC); prescribe only | MEDIUM |
| X1 | On-prem / multi-cloud OTEL env + creds | PRESCRIBE | — | full ADOT SDK env + IAM creds/Roles Anywhere + outbound HTTPS to OTLP endpoint | MEDIUM |

---

## Notes

- **ADOT Collector is not supported** for agent observability. Use the ADOT SDK or the AWS Lambda
  Layer for OpenTelemetry only.
- Unified span destination (spans in the agent's own log group instead of shared `aws/spans`)
  requires **ADOT ≥ 0.18.0** and the X-Ray log-group resource policy (R7). Earlier versions ignore
  the setting and deliver to `aws/spans`. **As of 2026-07-20, newly created agents in supported AWS
  Regions default to the unified span destination**; agents created before that date remain on
  shared `aws/spans` unless `UNIFIED_TRACES_DESTINATION_ENABLED=true` is set explicitly.
- Cross-service trace correlation requires W3C Trace Context (`traceparent`) propagation.

# Read-Only IAM Tiers

The skill degrades gracefully across three read-only permission tiers. It detects which tier is
present, runs the matching checks, and reports the exact policy to attach to unlock the rest.

**Who applies these:** the customer attaches a scoped inline policy to the DevOps Agent role in
their own account. The shared managed access policy is cross-tenant and must **not** be modified
per-skill, so Tier 2 and Tier 3 are customer-applied and opt-in. All permissions are read-only; the
skill never mutates IAM.

---

## Tier 1 — Standard (telemetry-arrival verification, host-agnostic)

Typically already available to the DevOps Agent role.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreObsTier1",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:FilterLogEvents",
        "logs:GetLogEvents",
        "logs:StartQuery",
        "logs:GetQueryResults",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics",
        "cloudwatch:DescribeAlarms"
      ],
      "Resource": "*"
    }
  ]
}
```

## Tier 2 — Runtime config verification

Unlocks Transaction Search state, runtime tracing/env, Memory/Gateway delivery, X-Ray resource policy.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreObsTier2",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetAgentRuntime",
        "bedrock-agentcore:ListAgentRuntimes",
        "xray:GetTraceSegmentDestination",
        "logs:DescribeDeliveries",
        "logs:DescribeDeliverySources",
        "logs:DescribeDeliveryDestinations",
        "logs:DescribeResourcePolicies"
      ],
      "Resource": "*"
    }
  ]
}
```

> `bedrock-agentcore` control-plane action names may vary by resource (runtime, memory, gateway).
> Verify exact action names against the current AgentCore API reference before applying; keep them
> read-only (`Get*` / `List*` / `Describe*` only).

## Tier 3 — Non-runtime host config verification

Unlocks host-side config checks for Lambda / ECS / EKS.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgentCoreObsTier3",
      "Effect": "Allow",
      "Action": [
        "lambda:GetFunctionConfiguration",
        "ecs:DescribeTaskDefinition",
        "ecs:DescribeServices",
        "ecs:ListTasks",
        "eks:DescribeCluster"
      ],
      "Resource": "*"
    }
  ]
}
```

---

## Provider connectivity

| Provider | Needed for | Tier |
|---|---|---|
| CloudWatch Logs + Metrics | telemetry-arrival verification (required baseline) | 1 |
| AWS X-Ray | Transaction Search state, traces delivery | 2 |
| AgentCore control plane | runtime auto-detection, runtime config | 2 |
| Lambda / ECS / EKS | non-runtime host config | 3 |

Source-repository file read (GitHub/GitLab) is **not** a dependency — code-level instrumentation
checks are prescriptive.

## Scoping note

`Resource: "*"` is shown for brevity because these are read/describe actions. Where the customer
prefers tighter scoping, restrict `logs:*` to the AgentCore log-group ARNs
(`/aws/bedrock-agentcore/*`, `/aws/vendedlogs/bedrock-agentcore/*`) and the resource actions to the
relevant function/cluster/task-definition ARNs.

# Remediation — Memory & Gateway Resources

Memory and Gateway resources do **not** get log destinations configured automatically. Logs and
traces must be wired explicitly. Default vended log group:
`/aws/vendedlogs/bedrock-agentcore/{memory|gateway}/APPLICATION_LOGS/{resource-id}`.

All steps are applied by the customer; the skill only generates them.

---

## Console

**Log delivery (Memory or Gateway):**
1. Open the resource in the AgentCore console (Memory or Gateway page).
2. Select the resource → **Log delivery** pane → **Add**.
3. Choose destination: CloudWatch Logs group, Amazon S3 bucket, or Amazon Data Firehose.
4. **Log type:** `APPLICATION_LOGS`.
5. For S3/Firehose, enter a delivery destination ARN. For CloudWatch Logs, the destination log group
   is prepopulated (override if desired).
6. **Add**.

**Tracing (Memory or Gateway):**
1. Open the resource → **Tracing** pane → **Edit**.
2. Toggle **Enable** → **Save**.

---

## SDK (boto3)

Wires both a logs delivery (→ CloudWatch Logs) and a traces delivery (→ X-Ray) for a Memory or
Gateway resource.

```python
import boto3

def enable_observability_for_resource(resource_arn, resource_id, account_id, region="us-east-1"):
    logs_client = boto3.client("logs", region_name=region)

    # 0. Log group for vended log delivery
    log_group_name = f"/aws/vendedlogs/bedrock-agentcore/{resource_id}"
    logs_client.create_log_group(logGroupName=log_group_name)
    log_group_arn = f"arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}"

    # 1. Delivery source for logs
    logs_source = logs_client.put_delivery_source(
        name=f"{resource_id}-logs-source",
        logType="APPLICATION_LOGS",
        resourceArn=resource_arn,
    )

    # 2. Delivery source for traces
    traces_source = logs_client.put_delivery_source(
        name=f"{resource_id}-traces-source",
        logType="TRACES",
        resourceArn=resource_arn,
    )

    # 3. Delivery destinations
    logs_dest = logs_client.put_delivery_destination(
        name=f"{resource_id}-logs-destination",
        deliveryDestinationType="CWL",
        deliveryDestinationConfiguration={"destinationResourceArn": log_group_arn},
    )
    traces_dest = logs_client.put_delivery_destination(
        name=f"{resource_id}-traces-destination",
        deliveryDestinationType="XRAY",
    )

    # 4. Connect sources to destinations
    logs_client.create_delivery(
        deliverySourceName=logs_source["deliverySource"]["name"],
        deliveryDestinationArn=logs_dest["deliveryDestination"]["arn"],
    )
    logs_client.create_delivery(
        deliverySourceName=traces_source["deliverySource"]["name"],
        deliveryDestinationArn=traces_dest["deliveryDestination"]["arn"],
    )
```

---

## Verification after applying

- `logs:DescribeDeliverySources` → an `APPLICATION_LOGS` source bound to the resource ARN.
- `logs:DescribeDeliveries` → an active logs delivery and a `TRACES`→XRAY delivery.
- `logs:FilterLogEvents` on the vended log group → recent events after exercising the resource.

See the provided log-data references for the fields emitted per resource type
(`observability-memory-metrics`, `observability-gateway-metrics` in the AgentCore docs).

# Remediation — Agents Hosted Outside AgentCore Runtime

For agents on Lambda, ECS, EKS, on-prem, or another cloud. Prerequisites first: enable CloudWatch
Transaction Search (see `remediation-runtime.md` §1) and add the ADOT SDK to the code. Then create
an agent log group and set the environment variables below.

> **ADOT Collector is not supported.** Use the ADOT SDK, or on Lambda the AWS Lambda Layer for
> OpenTelemetry. Nothing else.

All steps are applied by the customer; the skill only generates them.

---

## Full OTEL environment (ECS / EKS / on-prem / multi-cloud)

**AWS environment:**

```
AWS_ACCOUNT_ID=<account id>
AWS_DEFAULT_REGION=<default region>
AWS_REGION=<region>
AWS_ACCESS_KEY_ID=<access key id>        # on-prem/multi-cloud, or IAM Roles Anywhere
AWS_SECRET_ACCESS_KEY=<secret key>       # prefer role-based creds on AWS hosts
```

**OTEL environment:**

```
AGENT_OBSERVABILITY_ENABLED=true
OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator          # ADOT Python only
OTEL_RESOURCE_ATTRIBUTES=service.name=<agent-name>,aws.log.group.names=/aws/bedrock-agentcore/runtimes/<agent-id>,cloud.resource_id=<AgentEndpointArn:AgentEndpointName>
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=spans   # optional: unified spans; needs ADOT >=0.18.0 + X-Ray log-group resource policy
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
```

On AWS-hosted compute (ECS/EKS), use the task/pod IAM role instead of static access keys.

If `OTEL_EXPORTER_OTLP_TRACES_HEADERS` points spans at your own log group, add the X-Ray log-group
resource policy (see `remediation-runtime.md` §4).

---

## Lambda

Lambda uses the **AWS Lambda Layer for OpenTelemetry** — do **not** add `aws-opentelemetry-distro`
or run `opentelemetry-instrument`.

1. Attach the AWS Lambda Layer for OpenTelemetry to the function.
2. Set:

```
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
```

3. Add the agent log-group / OTEL resource attributes as above. Lambda-specific extras:

```
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false   # disable Application Signals
OTEL_LOGS_EXPORTER=otlp                       # export logs over OTLP
OTEL_METRICS_EXPORTER=awsemf                  # metrics as CloudWatch EMF
```

**Verify (Tier 3):** `lambda:GetFunctionConfiguration` → Layer present, `AWS_LAMBDA_EXEC_WRAPPER`
set, OTEL/log-group vars present.

---

## ECS

Put the full OTEL environment (above) into the container definition's `environment` block; use the
task role for credentials.

**Verify (Tier 3):** `ecs:DescribeTaskDefinition` → container env carries the OTEL variable set.

---

## EKS

The OTEL environment lives in the pod spec / ConfigMap, governed by Kubernetes RBAC — **not**
verifiable via IAM. The skill verifies **telemetry arrival** (Tier 1: is the agent log group
receiving data?) and prescribes the pod/ConfigMap env below. Direct pod-env verification is out of
scope: it would require EKS Access Entries, in-cluster RBAC, and native Kubernetes API calls
(partially mutating, per-cluster), which this read-only skill does not perform.

Set the OTEL environment (above) in the pod spec or a ConfigMap referenced by the deployment.

---

## On-prem / multi-cloud

Outside the DevOps Agent's reach — **prescribe only**. Same ADOT SDK env as ECS/EKS, plus:

- Credentials: IAM access keys **or** IAM Roles Anywhere (preferred).
- Outbound HTTPS to the AWS OTLP endpoints must be allowed from the host network.
- Create the agent log group in the target AWS account/region and reference it in
  `OTEL_RESOURCE_ATTRIBUTES` / `OTEL_EXPORTER_OTLP_*_HEADERS`.

# Remediation — AgentCore Runtime Agents

Copy-pasteable remediation for gaps found on the runtime path. All steps are applied by the
customer; the skill only generates them.

---

## 1. Enable CloudWatch Transaction Search (account prerequisite)

Without Transaction Search, spans are not delivered to CloudWatch Logs — traces never appear.

**Console:** CloudWatch → Application Signals (APM) → Transaction search → **Enable Transaction
Search** → select **ingest spans as structured logs** → Save.

**Effect:** X-Ray trace segments are ingested into CloudWatch Logs so AgentCore can deliver spans.

---

## 2. Code-level instrumentation (ADOT SDK)

Add to `requirements.txt`:

```
aws-opentelemetry-distro>=0.10.0
boto3
```

Use `aws-opentelemetry-distro>=0.18.0` if you want spans delivered to the agent's **own** log group
(unified span destination) rather than the shared `aws/spans` group.

Launch the agent with auto-instrumentation:

```bash
opentelemetry-instrument python my_agent.py
```

Containerized:

```dockerfile
CMD ["opentelemetry-instrument", "python", "main.py"]
```

Ensure the framework emits traces (e.g. configure the Strands tracer, or add the matching
auto-instrumentor such as `opentelemetry-instrumentation-langchain`). Supported instrumentation
libraries: OpenInference, Openllmetry, OpenLit, Traceloop.

---

## 3. Span destination (unified vs shared)

Set on the agent runtime environment:

- Deliver spans to the agent's own log group: `UNIFIED_TRACES_DESTINATION_ENABLED=true`
- Deliver spans to the shared `aws/spans` log group: `UNIFIED_TRACES_DESTINATION_ENABLED=false`

**Default:** starting 2026-07-20, newly created agents in supported AWS Regions default to the
unified span destination (agent's own log group), so `=false` is now the opt-out. Agents created
before that date default to shared `aws/spans` unless `=true` is set explicitly. Requires ADOT ≥
0.18.0; earlier versions ignore this setting and deliver to `aws/spans` regardless.

---

## 4. X-Ray resource policy on the agent log group (unified destination)

When delivering spans to the agent's own log group, the agent execution role needs
`logs:PutResourcePolicy`, and a CloudWatch Logs resource policy must allow X-Ray to write:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowXRayToPutSpans",
      "Effect": "Allow",
      "Principal": { "Service": "xray.amazonaws.com" },
      "Action": "logs:PutLogEvents",
      "Resource": "arn:aws:logs:<region>:<account-id>:log-group:/aws/bedrock-agentcore/runtimes/<agent-id>-<endpoint>:*"
    }
  ]
}
```

---

## 5. Session-id propagation

Set the session-id header when invoking the runtime so ADOT stamps `session_id` on downstream
telemetry:

```
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>
```

For W3C cross-service correlation, propagate `traceparent`.

---

## Third-party observability platforms

To route telemetry to a non-AWS platform, set `DISABLE_ADOT_OBSERVABILITY=true` on the runtime.
This unsets the default ADOT environment. Note: this intentionally disables AWS-side observability —
flag it if the customer expects CloudWatch data.