fix(logger)!: default to info when DEPLOYMENT_ENV is unset

[Henry Zhang (caezium)]

Summary

• Default the logger threshold to info when DEPLOYMENT_ENV is unset.
• Enable debug by default only for explicit DEPLOYMENT_ENV=development.
• Preserve precedence: LOG_LEVEL → programmatic override → environment-derived default.
• Clarify that the separate deployment.environment resource fallback does not control logging.
• Add regression coverage for the default matrix and public setupOtel({ logLevel }) precedence.
• Document the behavior change and LOG_LEVEL=debug compatibility path.

Why

@photon-ai/otel previously treated an absent DEPLOYMENT_ENV as development. Unset is the normal case for embedding SDK consumers such as Spectrum, so ordinary SDK use could emit debug-level console noise without an explicit debug opt-in.

Spectrum embeds this package and uses its structured logger even when telemetry export is disabled. The telemetry: true option controls OTLP setup; it does not control whether Spectrum emits console logs.

Breaking change

Consumers relying on unset DEPLOYMENT_ENV producing debug output must now set:

LOG_LEVEL=debug

Spectrum consumers can alternatively configure:

options: { logLevel: "debug" }

The OpenTelemetry deployment.environment resource attribute still falls back to development; only the logger threshold changes.

If this ships on the OTel 4.x line, Spectrum must bump its current ^3.1.0 dependency before normal Spectrum projects receive the change.

Validation

• bun run test — 98/98 tests passed
• node ./node_modules/vitest/vitest.mjs run — 98/98 tests passed
• bun run build
• bun x ultracite check
• git diff --check main...HEAD

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

---

Note

Medium Risk
Behavior change for embedders and anyone depending on implicit debug logging without setting LOG_LEVEL or DEPLOYMENT_ENV=development; telemetry resource attributes are unchanged.

Overview
Breaking change: default log verbosity no longer treats an unset DEPLOYMENT_ENV like development. defaultLevel() in logger.ts now uses debug only when DEPLOYMENT_ENV is exactly development; otherwise it uses info, including when the variable is missing. setupOtel() still sets deployment.environment to development when unset—only the logger threshold changes.

Precedence is unchanged: LOG_LEVEL → setupOtel({ logLevel }) / setLogLevel() → env-derived default. Docs (README, configuration, logging, API, environment) describe the split and note that v3.2.0 users who relied on unset env for debug should set LOG_LEVEL=debug.

Tests add coverage for unset DEPLOYMENT_ENV → info and for logLevel vs LOG_LEVEL precedence via setupOtel.

^{Reviewed by Cursor Bugbot for commit f21b618. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Updated default logging behavior: debug is now used only when DEPLOYMENT_ENV=development; otherwise, the default is info.
  • Preserved the precedence of explicit LOG_LEVEL settings and programmatic overrides.
  • Clarified that the telemetry environment attribute may still default to development independently.

• Documentation

  • Updated configuration, logging, API, and environment reference documentation.
  • Added upgrade guidance for users moving from v3.2.0.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

📝 Walkthrough

Walkthrough

The logger now defaults to debug only when DEPLOYMENT_ENV=development, and to info when unset or set otherwise. Tests cover these cases and override precedence, while documentation explains the updated behavior and v3.2.0 upgrade path.

Changes

Deployment-aware log-level defaults

Layer / File(s)	Summary
Update log-level fallback resolution src/logger.ts, src/setup.ts	Log-level fallback and option documentation now distinguish explicit development from unset or other deployment environments.
Validate environment and override behavior tests/logger.test.ts, tests/setup.test.ts	Tests cover environment defaults, invalid values, module state, and precedence between setup options and LOG_LEVEL.
Align configuration and upgrade documentation README.md, docs/configuration.mdx, docs/guides/logging.mdx, docs/reference/*.mdx	Documentation describes separate resource-attribute and log-level defaults, including the v3.2.0 upgrade behavior.

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

Suggested reviewers: underthestars-zhy

Poem

A bunny hops through logs tonight,
Development keeps debug bright.
Unset now rests at info’s glow,
Tests watch the precedence flow.
“Set debug,” I thump, “for the old delight!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: logger defaults now use info when DEPLOYMENT_ENV is unset.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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