feat(sdk): expose trace_content via Traceloop.init()

[yoheidemachi]

Summary

Adds a trace_content: Optional[bool] = None argument to Traceloop.init() that mirrors the existing TRACELOOP_TRACE_CONTENT environment variable, addressing #137 (open since 2023).

• trace_content=None (default): the TRACELOOP_TRACE_CONTENT env var stays authoritative — no behavior change for existing deployments.
• trace_content=True / False: the argument explicitly overrides the env var so applications can toggle prompt/completion capture without relying on process-level configuration.

The implementation sets os.environ["TRACELOOP_TRACE_CONTENT"] before any instrumentor initializes, so every bundled instrumentation that reads the env var (bedrock, watsonx, alephalpha, writer, …) picks up the value transparently without further changes.

Design notes

• An explicit arg wins over the env var (consistent with use_attributes / use_legacy_attributes, which also use Optional[bool] = None to signal "not explicitly set").

Behavior to be aware of

• Process-wide side effect. Because the implementation writes os.environ["TRACELOOP_TRACE_CONTENT"], child processes that inherit the env and any other code reading that variable will see the override too. This is the same surface area the existing env var already has — the arg just adds a programmatic entry point.
• The override is sticky. Once trace_content=True/False has been passed, a later Traceloop.init(trace_content=None) will not restore the previous env-driven value — the most recent explicit setting keeps winning until the env var is changed externally. Fine for the typical "init once at startup" flow; documented in the docstring.
• Per-span override still works. Setting trace_content=False does not block the existing override_enable_content_tracing OTel context value — instrumentations treat env and context as OR, so individual spans can opt back in while the global default stays off. This preserves the current semantics intentionally.

Test plan

• test_trace_content_false_disables_content_tracing — explicit False overrides env=true
• test_trace_content_true_overrides_env — explicit True overrides env=false
• test_trace_content_none_honors_env — omitting the arg preserves env-driven behavior
• Existing test_sdk_initialization.py + test_privacy_no_prompts.py (32 tests) still pass
• nx run traceloop-sdk:lint passes

Closes #137

Summary by CodeRabbit

Release Notes

• New Features
  • Introduced trace_content parameter to SDK initialization for controlling sensitive data capture in distributed traces. Once configured, the setting persists across subsequent initialization calls, ensuring consistent tracing behavior throughout the application lifecycle. Individual spans can still override the global configuration as needed.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 70fd9d8a-16a1-4c5c-9b96-15f821c699a6

📥 Commits

Reviewing files that changed from the base of the PR and between b39151b and 376f59e.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

This PR introduces a new trace_content optional parameter to Traceloop.init() that allows callers to control content tracing (prompts, completions) without relying solely on the TRACELOOP_TRACE_CONTENT environment variable. When provided, the parameter sets the env var for the process lifetime with sticky behavior across subsequent init() calls.

Changes

trace_content Feature

Layer / File(s)	Summary
API parameter and documentation packages/traceloop-sdk/traceloop/sdk/__init__.py	Adds trace_content: Optional[bool] = None to Traceloop.init() and documents how it overrides TRACELOOP_TRACE_CONTENT, its sticky behavior, per-span context interaction, and that it does not apply in early no-op paths.
Environment variable override logic packages/traceloop-sdk/traceloop/sdk/__init__.py	Sets os.environ["TRACELOOP_TRACE_CONTENT"] to "true" or "false" when trace_content is explicitly provided, before computing enable_content_tracing.
Test fixture and validation cases packages/traceloop-sdk/tests/test_sdk_initialization.py	Adds os import, isolated_trace_content_env fixture for safe env var manipulation, and four tests validating: explicit False disables content tracing, explicit True overrides disabled env values, omitted parameter honors env state, and sticky override behavior across init() calls.

🎯 2 (Simple) | ⏱️ ~12 minutes

🐰 A trace_content flag hops in with style,
No more prompts hiding all the while!
Environment vars now bow and bend,
To parameters users send—control to the end! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: exposing trace_content parameter via Traceloop.init() method.
Linked Issues check	✅ Passed	The pull request fully implements the feature request from #137: adds trace_content parameter to Traceloop.init() with proper override behavior for TRACELOOP_TRACE_CONTENT env var.
Out of Scope Changes check	✅ Passed	All changes are within scope: the new parameter in Traceloop.init(), supporting tests, and documentation align directly with the objectives of issue #137.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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