feat(telemetry): add a switch to disable instrumentation via OTEL_SDK_DISABLED / enabled (#1059)

[maxmilian]

Description

StrandsTelemetry had no way to turn instrumentation off. Applications that already run their own OpenTelemetry setup still get Strands' tracer/meter providers registered globally and its spans/metrics emitted — even when they don't want them (#1059; one reporter's downstream CloudWatch pipeline couldn't flush the Strands metrics and accumulated them like a leak).

This adds an enabled switch to StrandsTelemetry that defaults to honoring the OTel-standard OTEL_SDK_DISABLED=true environment variable, with an explicit StrandsTelemetry(enabled=False) override for programmatic control (the explicit arg always wins; the env var is consulted only when enabled is left None).

When disabled:

• __init__ does not create or register a global tracer provider and does not set global propagators;
• setup_console_exporter / setup_otlp_exporter / setup_meter are no-ops (return self, build nothing, register no meter provider).

The default (no env var, no arg) path is unchanged and fully backward compatible — __init__ is additive (new keyword-only enabled arg defaulting to None).

This is the StrandsTelemetry-level toggle @zastrowm suggested on the issue.

Scope (please confirm)

This gates provider/exporter registration via StrandsTelemetry. It intentionally does not change Tracer / get_tracer agent-span creation or the unconditional ThreadingInstrumentor().instrument() in telemetry/tracer.py. So for a host that never instantiates StrandsTelemetry (relying entirely on its own OTel), Strands spans on the global provider and the threading instrumentor are still active — OTEL_SDK_DISABLED would not stop those. I kept this PR focused on the location you pointed to and steered clear of the separate ThreadingInstrumentor opt-in work in #2167. Happy to follow up with span-creation gating in Tracer if you'd like that covered here too — let me know your preference.

Related Issues

Relates to #1059 (gates the StrandsTelemetry portion; see Scope note above).

Documentation PR

The public API is documented inline (the StrandsTelemetry docstring now covers OTEL_SDK_DISABLED and the enabled arg). I can add a short note to the conversation-management / observability page under site/ in a follow-up if you'd like it surfaced in the user guide.

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce new warnings.

• I ran hatch run prepare

hatch wasn't available in my environment, so I ran the underlying checks directly in a venv with .[dev,otel] installed (from strands-py/):

• pytest tests/strands/telemetry/test_config.py → 23 passed
• ruff format --check src/strands/telemetry/config.py tests/strands/telemetry/test_config.py → clean
• ruff check ... → All checks passed
• mypy src/strands/telemetry/config.py → Success, no issues

The new tests cover the env-var path, the explicit-flag path, explicit-flag-overrides-env, that disabling leaves a host-provided provider unregistered, that setup_* are no-ops when disabled, and OTEL_SDK_DISABLED parsing (case-insensitive / trimmed / only "true" disables). Red/green verified: the new behavior tests fail against main (no enabled switch) and pass on this branch.

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly (docstring updated inline; happy to add a site/ user-guide note as follow-up — see Documentation PR section)
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed (env var + arg documented in the StrandsTelemetry docstring)
• 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.