aws / aws/agentcore-cli

bug(typescript): agentcore deploy sets up no ADOT/OTel instrumentation for TypeScript agents, silently dropping all 3p telemetry

Open
#1,892 1 comment 0 reactions 0 assignees View on GitHub
bug telemetry
Dominant language
TypeScript
Stars
283
Forks
95
Avg merge
1d 2h
Merged PRs (30d)
183

Description

### Description

`agentcore deploy` does not set up any OpenTelemetry / ADOT instrumentation for **TypeScript** agents. Python agents get zero-code instrumentation via `opentelemetry-instrument`; TypeScript agents get nothing at any layer. As a result, spans emitted by any 3p instrumentation library (Strands, Vercel AI SDK, or a user's own `@opentelemetry/api` calls) are silently dropped, and nothing appears in CloudWatch / X-Ray Transaction Search.

This is a **regression**, not a never-implemented feature — the wiring existed and was removed (see below).

### Steps to Reproduce

1. `agentcore create --language TypeScript --sdk Strands --protocol HTTP --build Container`
2. `agentcore deploy`
3. Invoke the deployed agent so it produces LLM/tool calls
4. Open CloudWatch → Application Signals / X-Ray Transaction Search and look for traces from the agent

Also observable statically, without deploying:

- Generated `Dockerfile` ends in `CMD ["npx", "tsx", "main.ts"]` — no instrumentation wrapper
- Generated `package.json` contains no OTel SDK, only the no-op `@opentelemetry/api`

### Expected Behavior

TypeScript agents get zero-code ADOT instrumentation at parity with Python, so that 3p instrumentation libraries emitting via `@opentelemetry/api` export to the collector and show up in CloudWatch without any application code changes.

### Actual Behavior

No instrumentation is configured. Three independent gaps, each sufficient on its own to produce zero telemetry:

**1. `enableOtel` is hardcoded off for TypeScript** — `src/cli/operations/agent/generate/schema-mapper.ts:284`

```ts
const enableOtel = !isMcp && config.language !== 'TypeScript';
```

**2. The TypeScript Dockerfile has no instrumentation branch at all** — `src/assets/container/typescript/Dockerfile:25`

```dockerfile
CMD ["npx", "tsx", "main.ts"]
```

Compare `src/assets/container/python/Dockerfile:40-44`, which does branch:

```dockerfile
{{#if enableOtel}}
CMD ["opentelemetry-instrument", "python", "-m", "{{entrypoint}}"]
{{else}}
CMD ["python", "-m", "{{entrypoint}}"]
{{/if}}
```

Because no `{{#if enableOtel}}` block exists in the TS Dockerfile, **setting `instrumentation.enableOtel: true` on a TypeScript agent has no effect** — there is nothing for it to render. The schema at `src/schema/schemas/agent-env.ts:194` defaults it to `true` and documents it as "the runtime entrypoint is wrapped with `opentelemetry-instrument`", which is silently untrue for TypeScript.

**3. No OTel SDK dependency or bootstrap in the TS templates.** `src/assets/typescript/http/strands/base/package.json` carries only `@opentelemetry/api` — the no-op API surface, which discards all spans unless a global provider is registered. `src/assets/typescript/http/vercelai/base/package.json` has no OTel dependency at all. Neither template registers a provider.

The CodeZip path is affected too: TS CodeZip builds are bundled with esbuild (`src/lib/packaging/node.ts:95`) and have no Dockerfile to hook, so they need the instrumentation applied via runtime env vars rather than a `CMD` change.

### Origin of the regression

Commit `580cd10b` — *"fix(templates): remove OTEL, session storage, and gateway from TS templates"*, merged in #981 (2026-05-14) — removed the working implementation:

- deleted `src/assets/typescript/http/strands/base/otel-register.ts` and the `vercelai` equivalent, which registered a `NodeTracerProvider` + `MeterProvider` with OTLP exporters
- removed `import './otel-register.js';` from both `main.ts` files
- removed 7 `@opentelemetry/*` dependencies from both `package.json` files
- flipped `schema-mapper.ts` to exclude TypeScript

The OTel removal was one commit inside a broader TS template/streaming PR, so it isn't visible from the PR title.

### Interaction with #1270 (important)

Fixing the CLI alone is **not sufficient** to get traces into CloudWatch. Per #1270, AgentCore Runtime starts the ADOT collector sidecar on `localhost:4318` only when it detects `opentelemetry-instrument` in the container entrypoint, which is Python-specific. A TypeScript entrypoint never matches, so nothing listens on `:4318` and OTLP export fails silently even with a correctly registered SDK.

These two need to land together for end-to-end telemetry. Adopting a `--require`-based ADOT entrypoint (below) may also give the Runtime a detectable signal for starting the sidecar, which is worth confirming with the Runtime team.

### Suggested fix

ADOT for Node exists and is current: `@aws/aws-distro-opentelemetry-node-autoinstrumentation@0.12.0`. True zero-code parity with Python is a `NODE_OPTIONS=--require @aws/aws-distro-opentelemetry-node-autoinstrumentation/register` entrypoint — a single dependency and no hand-maintained `otel-register.ts`, unlike the reverted implementation.

Touch points:

- `src/cli/operations/agent/generate/schema-mapper.ts:284` — stop excluding TypeScript
- `src/assets/container/typescript/Dockerfile` — add the `{{#if enableOtel}}` branch
- both TS template `package.json` files — add the ADOT distro dependency
- TS CodeZip path — set the instrumentation env vars on the runtime (no Dockerfile to hook)
- `src/assets/__tests__/dockerfile-render.test.ts` — currently only exercises the Python Dockerfile; add TS coverage so this cannot silently regress again

### CLI Version

0.25.0 (repo `package.json`, at commit 8fba8160)

Contributor guide

Open the contributing guide

Research direction

Start with schema-mapper.ts, the TypeScript Dockerfile, both TypeScript template package.json files, and the CodeZip path in src/lib/packaging/node.ts. Run the existing Dockerfile rendering tests and add the named TypeScript coverage. Done means container and CodeZip TypeScript agents configure the documented instrumentation path and telemetry behavior is verified alongside the Runtime sidecar dependency in #1270.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, docker, node.js, typescript
Domain
build-system, devops, observability, testing-qa
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.