feat(server): export log records over OTLP

[yordis]

What Changed

Log records can now be exported over OTLP, configured the way traces and metrics already are: T3CODE_OTLP_LOGS_URL, the desktop bootstrap envelope, or Settings, in that order of precedence. Logs share T3CODE_OTLP_HEADERS, T3CODE_OTLP_PROTOCOL, and the export interval with the other two signals, and the resource each exporter tags its signal with is now one otlpResource helper instead of a literal repeated per signal.

With no log endpoint configured, nothing changes. The logger set is what it was, and stdout output and SSH-managed log persistence are untouched either way. When one is configured, the OTLP logger takes the place of Logger.tracerLogger rather than joining it, so an in-span message leaves once as a log record instead of twice.

Why

Traces and metrics could reach a collector and logs could not, which left the signal people reach for first as the one the server kept to itself. Debugging a remote environment meant having spans that showed a turn took too long and no way to read what the server said while it happened, short of asking someone to find a file and paste it.

Partial coverage is also the confusing kind of gap. Two signals arriving looks like all of them arrived, so the missing third is invisible from the dashboard rather than obviously absent.

The placement in serverLogger.ts is the part worth reviewing. Logger.layer writes the whole logger set rather than adding to it, so the OTLP log exporter has to be declared beside the console logger instead of sitting in the observability layer with its sibling signals. A second layer that installs a logger independently silently drops whichever set loses the merge, which is why this one is not there.

That same call is where the overlap with Logger.tracerLogger gets settled. The tracer logger only emits for messages logged inside a recorded span, and files them under traces rather than logs, so it covers less than the log records do. Recording events on spans is also the shape OpenTelemetry is deprecating, in favor of log-based events correlated to the current span: https://opentelemetry.io/blog/2026/deprecating-span-events/. Keeping both would export every in-span message twice, so the log signal replaces it once an endpoint is set. The tradeoff is that the local trace file stops carrying log messages in that mode.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (not applicable, no UI change)
• I included a video for animation/interaction changes (not applicable)

Summary by CodeRabbit

• New Features

  • Added OTLP log export alongside metrics and trace export.
  • Configure log export with T3CODE_OTLP_LOGS_URL.
  • Environment, bootstrap, and persisted settings now resolve observability endpoints consistently.
  • Server status shows whether log export is enabled.
  • Exported logs include trace context and avoid duplicate trace logging.
  • Logs continue appearing in stdout and SSH-persisted output.
  • Observability settings are trimmed and persisted consistently.

• Documentation

  • Updated observability guidance with log configuration, examples, and fallback behavior.

• Compatibility

  • Older server configurations decode with log export disabled.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a cross-cutting production capability for exporting every server log record over OTLP, including new configuration, persistence, contracts, and logger/exporter wiring. Although disabled when no endpoint is configured and covered by focused tests, its integration surface and remote log-transmission behavior warrant human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 0f305837-a999-4ac8-b58b-1759d23678f6

📥 Commits

Reviewing files that changed from the base of the PR and between c2277fd and fea5659.

📒 Files selected for processing (5)

• apps/desktop/src/app/DesktopConfig.ts
• apps/desktop/src/app/DesktopEnvironment.test.ts
• apps/desktop/src/app/DesktopEnvironment.ts
• apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
• apps/desktop/src/backend/DesktopBackendConfiguration.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds OTLP log endpoint configuration across desktop, server, contracts, and persisted settings. The server conditionally exports logs through OTLP and exposes the endpoint status to clients. Tests and documentation cover configuration, compatibility, trimming, and export behavior.

Changes

OTLP log export

Layer / File(s)	Summary
Configuration and contracts apps/desktop/src/backend/*, apps/desktop/src/app/*, apps/server/src/cli/*, apps/server/src/config.ts, packages/contracts/src/*, packages/shared/src/serverSettings.*	Observability schemas, persisted settings, desktop bootstrap data, and configuration resolution now include otlpLogsUrl. Environment, bootstrap, and persisted values are resolved with environment values taking precedence.
Server OTLP log exporter apps/server/src/serverLogger.*, apps/server/src/observability/*, apps/server/src/config.ts	The server conditionally exports logs through OTLP. The exporter uses configured settings and shared resource attributes. The tracer logger is omitted when OTLP log export is enabled.
Server exposure and documentation apps/server/src/ws.ts, apps/server/src/serverSettings.test.ts, packages/client-runtime/src/rpc/session.test.ts, packages/contracts/src/server.test.ts, docs/operations/observability.md	Server responses expose the logs URL and enabled flag. Tests cover compatibility, trimming, fallback behavior, disabled export, and configured export. Documentation describes the environment variable and export behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ServerLoggerLive
  participant ServerConfig
  participant OtlpExporter
  participant Collector
  ServerLoggerLive->>ServerConfig: Read OTLP logs configuration
  ServerLoggerLive->>OtlpExporter: Configure log export
  OtlpExporter->>Collector: Send serialized log records

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to fea56

The OTLP logs configuration is wired through desktop configuration, bootstrap data, server settings, runtime export, and client exposure with corresponding coverage. No current merge-blocking risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 24 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: exporting server log records over OTLP.
Description check	✅ Passed	The description includes complete What Changed, Why, and Checklist sections. It explains configuration precedence, behavior with and without an endpoint, logger replacement, tradeoffs, and the lack of…
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[yordis]

Following up on the heads up that most server logs already reach a collector as span events, since it changed what this PR does.

That is accurate, and to avoid sending the same message twice I pushed a commit so the two paths are mutually exclusive: when a logs endpoint is configured the server installs the OTLP logger in place of Logger.tracerLogger, and with no endpoint set the logger set is exactly what it is on main today.

Two reasons the log signal still earns its place. Coverage: Logger.tracerLogger returns early when the fiber has no recorded internal span, so the orchestration reactors, the WS layer, the provider adapters, the terminal manager, and most of startup and shutdown emit nothing at all right now. In apps/server/src that is 306 log call sites against 51 withSpan sites, with the spans concentrated in auth, checkpoint diffing, and the RPC wrapper. Those uncovered paths are stdout only, which is the one place you cannot reach on a remote environment. The diagnostics RPC methods make it sharper, since they set TracerEnabled: false deliberately, so the handlers you would reach for to debug a sick server drop their logs from telemetry too.

Destination: a span event lands in the trace store, not the log store, so it is not searchable by severity (effect.logLevel is a span attribute string rather than OTLP severityNumber), log-based alerting never fires on it, and log retention does not apply. OtlpLogger stamps traceId and spanId on every record, so correlation with the trace survives in the log signal.

This is also the direction OpenTelemetry is heading. They are deprecating the span event recording API in favor of log-based events correlated to the current span: https://opentelemetry.io/blog/2026/deprecating-span-events/. Nothing urgent, and the post is explicit that existing span event data stays part of the supported OTLP trace model, but it does mean the choice is ours in our own logger list rather than something Effect has to change first.

The tradeoff worth flagging: with log export configured the local NDJSON trace file stops carrying log messages, which changes what trace diagnostics shows for those users. If you would rather keep both locally, the alternative is to keep Logger.tracerLogger installed and skip only the forward to the OTLP delegate in LocalFileSpan.event. Happy to go that way instead, it is just a larger change and it leans on Effect's internal attribute naming.