feat(dev): add --otel-endpoint flag to forward traces to custom OTLP …

[mangelino]

…backend

Description

Add a new --otel-endpoint option to agentcore dev that lets users send agent traces to an external OTLP/HTTP collector (e.g. Jaeger, Grafana Tempo) instead of the built-in local collector.

When --otel-endpoint is provided:

• The local in-process OtelCollector is not started (no port bound)
• OTEL_EXPORTER_OTLP_ENDPOINT is set to the supplied URL
• All other OTEL env vars are injected as normal
• collector is returned as undefined (traces panel in web UI will be empty)

The existing --no-traces flag continues to disable telemetry entirely.

Changes:

• src/cli/operations/dev/otel/collector.ts: startOtelCollector accepts optional customEndpoint; skips local server when provided
• src/cli/commands/dev/command.tsx: add --otel-endpoint flag, log the endpoint at startup, pass through to runBrowserMode
• src/cli/commands/dev/browser-mode.ts: thread otelEndpoint through BrowserModeOptions and launchBrowserDev
• src/cli/commands/dev/tests/dev.test.ts: verify flag appears in help
• src/cli/operations/dev/otel/tests/collector.test.ts: 10 unit tests covering both default and custom-endpoint behaviour

Related Issue

Closes #1009

Documentation PR

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-cli-automation]

Dead code: otelEndpoint on BrowserModeOptions is never consumed

otelEndpoint is added to BrowserModeOptions (browser-mode.ts L101–102) and threaded from both launchBrowserDev and the dev action handler (command.tsx L432) into runBrowserMode, but runBrowserMode's destructure at L133 doesn't pull it out and nothing inside the function uses it:

const { workingDir, project, agentName, otelEnvVars = {}, collector } = opts;

So the field has no behavioral effect today — the custom endpoint's entire effect comes from startOtelCollector(persistTracesDir, opts.otelEndpoint) which returns the right otelEnvVars and collector = undefined. That's already enough.

A couple of options:

1. Remove the otelEndpoint field from BrowserModeOptions, the otelEndpoint param on launchBrowserDev, and the otelEndpoint: opts.otelEndpoint pass-through in command.tsx — keeps the diff minimal and matches the actual runtime behavior.
2. If you intend the web UI to surface the custom endpoint somewhere (e.g., show "traces forwarded to " in the traces panel instead of an empty list), destructure and actually plumb it through.

Option 1 is probably what you want unless there's a follow-up planned.

[agentcore-cli-automation]

--no-traces + --otel-endpoint silently does nothing

In command.tsx the guard is:

if (opts.traces !== false) {
  const otelResult = await startOtelCollector(persistTracesDir, opts.otelEndpoint);
  ...
  if (opts.otelEndpoint) {
    console.log(`OTEL traces → ${opts.otelEndpoint}`);
  }
}

If a user passes both --no-traces and --otel-endpoint <url>, --no-traces silently wins: no env vars are injected, no collector starts, and nothing is forwarded to the user's endpoint — with no warning. Given the two flags are semantically in conflict (one disables telemetry, the other configures where it goes), this is easy to get wrong and hard to debug.

Options:

1. Error out early if both flags are provided (e.g., "--no-traces and --otel-endpoint are mutually exclusive").
2. Let --otel-endpoint take precedence over --no-traces and print a warning.
3. At minimum, print a warning when both are set explaining that --no-traces wins.

Option 1 is the cleanest.