[LuisFigueroaG]

Summary

• add an optional metrics_enabled argument to Traceloop.init()
• make explicit values take precedence over TRACELOOP_METRICS_ENABLED
• preserve the existing environment/default behavior when the argument is None

Root cause

Metric export and several bundled instrumentations previously read TRACELOOP_METRICS_ENABLED directly, so applications could not disable metrics through the Python API. Disabling only the SDK metric exporter would also leave instrumentations initialized with metrics enabled.

The effective value is now resolved before tracer and instrumentation setup. Explicit values are exposed during that setup and the original environment is restored afterward, including when initialization raises. The existing behavior for custom trace pipelines without a custom metrics exporter is unchanged.

Impact

Applications can now use Traceloop.init(metrics_enabled=False) instead of mutating container or process configuration. Existing callers retain the environment-variable behavior because the new argument defaults to None and was appended to the public signature.

Testing

• uv run pytest -q — 453 passed
• uv run ruff check .
• uv run mypy traceloop/sdk

Closes #1646

This replaces #4381 with the same change, moved to a properly named branch and squashed into one commit on top of current main.

Summary by CodeRabbit

• New Features

  • Added an optional metrics_enabled setting to Traceloop.init().
  • Explicit configuration now takes precedence over the TRACELOOP_METRICS_ENABLED environment variable.
  • When unset, metrics continue to follow the environment variable.
  • Metrics configuration is applied during initialization and the previous environment setting is restored afterward.

• Documentation

  • Clarified metrics configuration precedence, default behavior, and one-time initialization requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: d6e2d16c-e3fe-4d99-b58f-5ab0bb5b16a7

📥 Commits

Reviewing files that changed from the base of the PR and between 8d9c93f and 7a21b82.

📒 Files selected for processing: 2

• packages/traceloop-sdk/tests/test_sdk_initialization.py
• packages/traceloop-sdk/traceloop/sdk/__init__.py

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Traceloop.init() now accepts an optional metrics_enabled argument. An explicit value takes precedence over the environment setting during tracer initialization. Initialization serializes temporary environment changes and restores the previous value.

Changes: Programmatic Metrics Configuration

Layer / File(s)	Summary
Metrics initialization option packages/traceloop-sdk/traceloop/sdk/__init__.py	Traceloop.init() adds metrics_enabled. Its documentation describes precedence, the environment default, and one-time initialization behavior.
Synchronized metrics initialization packages/traceloop-sdk/traceloop/sdk/__init__.py, packages/traceloop-sdk/tests/test_sdk_initialization.py	Tracer construction reads the effective setting under a lock, temporarily applies explicit values to TRACELOOP_METRICS_ENABLED, and restores the prior value. Metrics disablement uses the captured setting. Tests cover precedence, propagation, and restoration after initialization errors.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Traceloop.init()
  participant MetricsLock
  participant TRACELOOP_METRICS_ENABLED
  participant TracerConstruction
  Traceloop.init()->>MetricsLock: acquire
  Traceloop.init()->>TRACELOOP_METRICS_ENABLED: read prior value and apply explicit setting
  Traceloop.init()->>TracerConstruction: initialize with effective metrics setting
  Traceloop.init()->>TRACELOOP_METRICS_ENABLED: restore prior value
  Traceloop.init()->>MetricsLock: release

Loading

Suggested reviewers: swatipoojary

Merge Risk: ⚪ Minimal · up to 7a21b

Traceloop.init() gains an optional metrics_enabled argument that takes precedence over the environment variable, and the previous environment value is restored afterward. No merge-blocking issue was found.

Security architecture risk: 🔵 Low · up to 7a21b

The option remains application-controlled and preserves existing safeguards against unintended metric export. The main residual uncertainty is configuration isolation during concurrent or interrupted initialization, rather than a demonstrated security bypass.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The configuration bridge has process-wide rather than per-instance scope. Unrelated threads reading the same environment variable during construction can observe the temporary value; the private lock only coordinates participating SDK initialization calls. No concurrent-reader path causing unintended export is established by the supplied evidence.

Security Findings and Attack Paths

• observed — The supplied public-entrypoint range is a pytest test using patched initialization dependencies, not a deployable request handler. It exercises a public library API but does not itself establish an attacker-controlled source or identity transition.

Trust Boundaries and Controls

• inferred — The new choice is available to application initialization code that already supplies exporters, endpoints and credentials. The inspected change introduces configuration precedence, not a new authentication or authorization mechanism; exposure through an external application's untrusted inputs remains unknown.

Resilience and Maintainability Implications

• observed — The lock does not make the complete initialization transition atomic: tracer static parameters are set before it, and metrics setup occurs afterward. The added tests verify precedence, propagation and constructor-error restoration, but not concurrent initialization or retry after partial singleton construction.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding programmatic control to disable metrics through the SDK.
Linked Issues check		Issue #1646 requires a programmatic equivalent of TRACELOOP_METRICS_ENABLED=false. Traceloop.init() now accepts optional metrics_enabled; explicit values override the environment, and None pre…
Out of Scope Changes check		The reported changes are limited to the Traceloop.init() metrics configuration, its setup behavior, documentation, and focused initialization tests. These changes directly support issue #1646. No un…
Docstring Coverage		Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 2 files.

Full details: Linked Issues check

Explanation

Issue #1646 requires a programmatic equivalent of TRACELOOP_METRICS_ENABLED=false. Traceloop.init() now accepts optional metrics_enabled; explicit values override the environment, and None preserves environment/default behavior. The override is active while TracerWrapper initializes bundled instrumentations, and the tests cover precedence, instrumentation visibility, and environment restoration.

Full details: Out of Scope Changes check

Explanation

The reported changes are limited to the Traceloop.init() metrics configuration, its setup behavior, documentation, and focused initialization tests. These changes directly support issue #1646. No unrelated change is established by the available evidence.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}