OTEL & ADOT: Auto vs. Manual

AgentCore Observability is the operations pillar: trace, debug, and monitor agents in production with per-step visualizations. It is powered by Amazon CloudWatch and emits OTEL-compatible telemetry, so it plugs into whatever you already run. Metrics, spans, traces, and logs all land in CloudWatch.

The single most important distinction in this lesson is where your agent runs, because that decides who instruments it:

• A) Runtime-hosted (auto-instrumented). You deploy through the AgentCore CLI. The platform wires up OpenTelemetry for you — no extra libraries, no extra config — and you get baseline traces, sessions, and metrics immediately.
• B) Outside Runtime (you instrument). Your agent runs on EKS, ECS, Lambda, or your laptop. AgentCore is not in the request path, so you add the AWS Distro for OpenTelemetry (ADOT), create a log group, set OTEL env vars, and start the process under opentelemetry-instrument.

Both paths produce the same shape of data and feed the same CloudWatch backend. The difference is purely who does the wiring.

When you deploy a Runtime-hosted agent through the AgentCore CLI, OpenTelemetry instrumentation is applied for you. You write a normal agent, wrap it with the SDK, deploy, and the baseline telemetry appears in CloudWatch with no extra libs or config.

# agent.py — a plain Runtime agent. Nothing here is observability code.
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()  # Strands

@app.entrypoint
def invoke(payload):
    return agent(payload["prompt"]).message

if __name__ == "__main__":
    app.run()  # binds 0.0.0.0:8080, serves /invocations + /ping

agentcore deploy                     # package + deploy to Runtime (auto-instrumented)
agentcore invoke '{"prompt":"hi"}'   # pass a runtimeSessionId to drive the Sessions view

That is the entire setup for path A. The CLI provisions the Runtime endpoint, auto-creates the log group, and turns on OTEL. The InvokeAgentRuntime span (with attributes like session.id, latency_ms, and error_type) flows to aws/spans, and Runtime metrics land in the bedrock-agentcore namespace. Pass a runtimeSessionId on invoke so the Sessions View can group activity by session.

A practical caveat: because the platform already instruments the agent, do not also wrap it in your own opentelemetry-instrument or a second auto-instrumentor — double-instrumenting a Runtime agent produces duplicate/confusing spans.

If your agent runs anywhere other than Runtime, AgentCore is not intercepting calls, so you take over instrumentation. The recipe is four steps: add ADOT, create a log group, set OTEL env vars, launch via opentelemetry-instrument.

1) Add the distro to your dependencies:

# requirements.txt
aws-opentelemetry-distro>=0.10.0
strands-agents[otel]        # if you use Strands; emits OTEL spans

2) Create the CloudWatch log group your agent will write to (Runtime would have done this for you; outside Runtime it does not exist yet):

aws logs create-log-group --log-group-name agents/my-agent-logs

3) Set the OTEL environment variables. These are the exact keys AgentCore expects:

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator   # Python only
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-agent,aws.log.group.names=agents/my-agent-logs"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-aws-log-group=agents/my-agent-logs,..."

4) Launch the process under the auto-instrumentor instead of running Python directly:

opentelemetry-instrument python agent.py

In a container, that becomes the entrypoint command:

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

That is the whole difference from path A: you supply the dependency, the log group, the env vars, and the launch wrapper that the Runtime would otherwise have supplied.

Regardless of which path you took, OpenTelemetry auto-captures the agent's whole execution shape:

• Agent invocation sequences — the end-to-end request path.
• LLM calls and responses — model invocations and their outputs.
• Tool invocations and results — every tool the agent calls and what it returned.
• Error paths — failures classified into throttle / system / user (error_type on the span).
• Framework integration — Strands, LangChain, and the other supported frameworks are stitched in automatically.

What the platform does not invent for you — the things specific to your domain — you add explicitly:

• Custom spans / traces to mark business-meaningful units of work.
• Custom metrics emitted via EMF into the bedrock-agentcore namespace.
• Custom logs for your own application events.
• Custom attributes / baggage to enrich spans (e.g. a tenant id, a feature flag, the session id).

from opentelemetry import trace, baggage

tracer = trace.get_tracer(__name__)

# A custom span with custom attributes
with tracer.start_as_current_span("retrieve_policy_docs") as span:
    span.set_attribute("tenant.id", tenant_id)
    span.set_attribute("doc.count", len(docs))
    # baggage propagates across the trace (e.g. for session grouping)
    baggage.set_baggage("session.id", session_id)

Custom metrics use the CloudWatch Embedded Metric Format (EMF), written to the bedrock-agentcore namespace. Note that the execution role must allow cloudwatch:PutMetricData scoped with the condition cloudwatch:namespace=bedrock-agentcore.

AgentCore Observability does not lock you into a single instrumentation source. The supported families are:

• Framework-native instrumentation — Strands, LangChain, and CrewAI emit OTEL spans directly. For Strands that capability rides on the strands-agents[otel] extra.
• OpenInference (from Arize).
• OpenLLMetry (from Traceloop).
• OpenLIT.
• Traceloop.

Because everything reduces to OpenTelemetry, these libraries coexist: a Strands agent can emit its native spans while an OpenInference or OpenLLMetry instrumentor adds LLM-semantic-convention detail on top. The collector and exporter config (the OTEL env vars from path B, or the platform's wiring in path A) is what funnels them all into CloudWatch.

# requirements.txt — mixing framework-native + an OTEL instrumentor
strands-agents[otel]
aws-opentelemetry-distro>=0.10.0
openinference-instrumentation-langchain   # example add-on instrumentor

By default a Runtime-hosted agent ships its telemetry into AWS via ADOT. If your organization standardizes on Datadog, Dynatrace, LangSmith, or Langfuse, you can redirect a Runtime agent's telemetry to that backend instead.

The switch is a single environment variable:

DISABLE_ADOT_OBSERVABILITY=true

Setting this on the Runtime tells AgentCore to stand down its default ADOT export so your own exporter / OTLP configuration takes over and points at the third-party collector. Two things people forget:

1. Keep the OTEL machinery in your dependencies. Disabling the AWS export does not mean you can drop instrumentation — your image still needs the framework's OTEL support and the distro, e.g. strands-agents[otel] and aws-opentelemetry-distro in requirements.txt, so spans are actually produced and exportable.
2. Configure the destination yourself. With ADOT disabled you supply the OTLP endpoint, headers, and credentials for Datadog/Langfuse/etc. via the standard OTEL exporter env vars; AgentCore is no longer doing that for you.

# requirements.txt for a Runtime agent exporting to a non-AWS backend
strands-agents[otel]
aws-opentelemetry-distro

# On the Runtime: turn off the AWS export, then point OTEL at your backend
DISABLE_ADOT_OBSERVABILITY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-backend-collector>
OTEL_EXPORTER_OTLP_HEADERS="<auth header for your backend>"

The net effect: you keep AgentCore Runtime's hosting and session isolation, but your traces land in the observability tool your team already lives in.