Decouple deployment environment from logger level defaults

[Ryan Zhu (underthestars-zhy)]

Summary

• Set the default logger level to info regardless of deployment environment
• Ensure explicit logLevel options take precedence over LOG_LEVEL
• Upgrade @photon-ai/otel to 3.3.0 and document the updated behavior

Testing

Not run (not requested)

---

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

---

Note

Low Risk
Observability-only changes (defaults and docs); local dev may see less debug output unless logLevel or LOG_LEVEL is set.

Overview
Default logging is now always info, removing the previous behavior where development (DEPLOYMENT_ENV) could default to debug.

Precedence for severity is clarified in code and docs: an explicit options.logLevel on Spectrum() wins over the LOG_LEVEL environment variable (via @photon-ai/otel), including when telemetry is off.

Dependency bump: @photon-ai/otel is upgraded from ^3.1.0 to ^3.3.0 across the root, core, and imessage packages (lockfile also pulls in OTLP metrics export support from that release). Getting started docs note the info default and the logLevel vs LOG_LEVEL ordering.

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

Summary by CodeRabbit

• Documentation

  • Clarified that the default logging level is info.
  • Documented that an explicitly configured logLevel takes precedence over the LOG_LEVEL environment variable.

• Behavior

  • Explicit log-level settings now consistently override environment-based logging configuration, including when telemetry is disabled.

[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 change updates logging documentation and comments to state an info default and explicit logLevel precedence over LOG_LEVEL, while upgrading @photon-ai/otel dependency ranges to ^3.3.0.

Changes

Logging configuration alignment

Layer / File(s)	Summary
Logging semantics and dependency alignment docs/getting-started.mdx.vel, packages/core/src/spectrum.ts, package.json, packages/core/package.json, packages/imessage/package.json	Logging documentation and comments describe the info default and explicit logLevel precedence; all listed @photon-ai/otel dependency ranges are updated to ^3.3.0.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

A rabbit twitched an ear,
“Info” now rings bright and clear.
Explicit levels lead the way,
Env vars follow what they say.
Otel hops to three-point-three!

🚥 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 are no longer tied to the deployment environment.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ryan/eng-2063-decouple-deployment-environment-from-logger-level-defaults

---

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

[pkg-pr-new]

Open in StackBlitz

@spectrum-ts/core

npm i https://pkg.pr.new/@spectrum-ts/core@215

@spectrum-ts/elysia

npm i https://pkg.pr.new/@spectrum-ts/elysia@215

@spectrum-ts/express

npm i https://pkg.pr.new/@spectrum-ts/express@215

@spectrum-ts/fastify

npm i https://pkg.pr.new/@spectrum-ts/fastify@215

@spectrum-ts/hono

npm i https://pkg.pr.new/@spectrum-ts/hono@215

@spectrum-ts/imessage

npm i https://pkg.pr.new/@spectrum-ts/imessage@215

@spectrum-ts/imessage-local

npm i https://pkg.pr.new/@spectrum-ts/imessage-local@215

@spectrum-ts/slack

npm i https://pkg.pr.new/@spectrum-ts/slack@215

spectrum-ts

npm i https://pkg.pr.new/spectrum-ts@215

@spectrum-ts/telegram

npm i https://pkg.pr.new/@spectrum-ts/telegram@215

@spectrum-ts/terminal

npm i https://pkg.pr.new/@spectrum-ts/terminal@215

@spectrum-ts/whatsapp-business

npm i https://pkg.pr.new/@spectrum-ts/whatsapp-business@215

commit: 82897cb

[cursor]

Problem analysis

What this PR is trying to fix

Two related logging design problems, both living in @photon-ai/otel and showing up through Spectrum:

1. Log verbosity was tied to deployment metadata. If DEPLOYMENT_ENV was unset or development, the logger defaulted to debug. That variable is really meant for OpenTelemetry’s deployment.environment resource attribute — not for deciding how chatty logs should be. In local/dev (where that env var is often unset), apps could get unexpectedly noisy debug output.

2. An explicit SDK setting could lose to an env var. Spectrum’s options.logLevel (and otel’s setLogLevel / setupOtel({ logLevel })) were documented and intended as the app’s choice, but LOG_LEVEL still won. That’s surprising for a library API: you set a level in code, and the environment quietly overrides it.

Is the problem valid? Yes. Mixing “what environment am I in?” with “how much should I log?” couples two different concerns. And for an SDK, “explicit option beats ambient env” is the more predictable rule.

Is this the right fix?

Yes — this addresses the root cause, not just a symptom.

The actual behavior change is already in @photon-ai/otel@3.3.0:

• default level is always info
• programmatic level wins over LOG_LEVEL
• DEPLOYMENT_ENV only labels telemetry, and no longer affects log level

This Spectrum PR is the correct consumer follow-up: bump the dependency so Spectrum actually gets that fix, and update Spectrum’s docs/JSDoc so they no longer claim the old defaults and precedence.

That’s the right layering. Spectrum should not re-implement its own log-level policy on top of otel; it should call setLogLevel when the caller passes logLevel, and otherwise let otel’s resolution apply. The existing applyLogLevel helper already does that (it only sets a level when one is provided, so LOG_LEVEL still works as a fallback when Spectrum users don’t pass options.logLevel).

Things to be aware of

These are intentional breaking behavior changes for Spectrum users, even though the diff here looks mostly like docs + a version bump:

• Local/dev will be quieter by default. Anyone who relied on “unset DEPLOYMENT_ENV ⇒ debug logs” will need options.logLevel: "debug" or LOG_LEVEL=debug.
• Ops can no longer use LOG_LEVEL to override a level set in code. If a host app sets Spectrum({ options: { logLevel: "info" } }), LOG_LEVEL=debug will not win anymore. That’s the desired SDK-first policy, but deployments that depended on the old order need a heads-up.
• The PR title sounds like Spectrum itself decouples these concerns. In practice, Spectrum is adopting the otel fix. That’s fine — just worth saying clearly in the summary so reviewers don’t hunt for logic that isn’t in this repo.

Verdict

Valid problem, right solution. The deeper issue was in otel’s level resolution; that was fixed properly upstream, and this PR correctly wires Spectrum onto that release and keeps the public docs honest. Not a band-aid.

Optional polish (non-blocking): call out the breaking default/precedence change in the Spectrum release notes, and consider a small test that options.logLevel beats LOG_LEVEL so this contract doesn’t regress silently the next time otel is bumped.

  

_{Sent by Cursor Automation: PR analyze}

[cursor]

This comment is accurate for the new otel contract, but the behavior change itself is not implemented here — it comes from the @photon-ai/otel ^3.3.0 bump. Worth keeping the docs/comments in sync (as this PR does), and maybe noting in the PR summary that Spectrum is adopting otel#15 rather than re-encoding the policy locally.