feat(otel): export logs through the tracing pipeline, correlated with traces (#147)

Logs were a separate pipeline: env_logger in debug (never exported) and
opentelemetry-appender-log in release (exported without trace context,
so SigNoz could not link logs to traces).

- tracing-subscriber `tracing-log` feature: try_init installs LogTracer,
  so log:: records become tracing events: one console format, and
  RUST_LOG per-module directives still apply to them.
- opentelemetry-appender-tracing exports events as OTel log records when
  OTLP_OTLS_ENDPOINT is set (any build), stamped with the enclosing
  span's trace_id/span_id. A per-layer filter drops the exporter's own
  crates.
- The OTel span layer keeps only WARN/ERROR events as span events; the
  info/debug copies duplicated the correlated logs.
- Remove env_logger init in the server, init_logs, and the unused
  opentelemetry-appender-log / opentelemetry-stdout deps.
- tests/otel_log_correlation.rs pins correlation (native + bridged),
  the span-event filter, and per-module filtering of bridged records.
- Constitution 1.2.0 (Principle V logging rule), CLAUDE.md, README,
  .env.example.

Closes #147

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Cameron CordesandClaude Opus 5.5 committed 2026-09-29 22:56:10 -04:00
1 parent 79b339a2a6
commit 3b3e6bdb39
9 files changed
+284 -106

No files matched your search

+20 -19
View File
@@ -1,17 +1,15 @@
<!--
Sync Impact Report
==================
Version change: 1.0.0 -> 1.1.0
Bump rationale: MINOR. Principle V is materially expanded: the tracing
mechanism changed (tracing + tracing-opentelemetry in every build), and
it adds two new MUST rules: no manual Context threading, and carrying
the parent span across spawns. No principle is removed or redefined in
intent.
Version change: 1.1.0 -> 1.2.0
Bump rationale: MINOR. Principle V's logging rule is materially changed:
logs are no longer a separate, build-profile-dependent pipeline; they
share the tracing subscriber and export correlated with traces in any
build (#147). No principle is removed or redefined in intent.
Modified principles:
- V. Observability: mechanism + rules updated for the tracing migration
(map #135, PR #148)
- V. Observability: logging bullet rewritten; span events limited to
WARN/ERROR
Also updated:
- I. Layered Architecture: Database Layer "traced" wording
- Technology Stack & Constraints: Tracing line
Added sections: N/A
Removed sections: N/A
@@ -22,11 +20,11 @@
- .specify/templates/checklist-template.md — ✅ no changes needed
- .specify/templates/agent-file-template.md — ✅ no changes needed
Runtime guidance:
- CLAUDE.md "Tracing" — ✅ already consistent (conventions landed with #148);
OTLP env line + dependency list updated alongside this amendment
- README.md — ✅ RUST_LOG default/gating corrected; OTLP_OTLS_ENDPOINT added
- .env.example — ✅ telemetry header corrected
Follow-up TODOs: None
- CLAUDE.md "Tracing" — ✅ logs bullet added; dependency list updated
- README.md — ✅ RUST_LOG default + OTLP_OTLS_ENDPOINT now cover logs
- .env.example — ✅ telemetry header covers logs
Follow-up TODOs: migrate `log::` macros to `tracing::` (bridged records
export with target "log"; module survives only in code.namespace)
-->
# ImageApi Constitution
@@ -113,8 +111,11 @@ All database operations and HTTP handlers MUST be instrumented with
an uncarried spawn orphans its spans onto a fresh trace.
- `RUST_LOG` gates span export as well as console output (one `EnvFilter`).
Deployments MUST run at `info` or `debug`.
- Logs are a separate pipeline: `env_logger` in debug, OTel log export in
release.
- Logs share the tracing subscriber: `log::` records are bridged into
`tracing`, so both print in one console format. With
`OTLP_OTLS_ENDPOINT` set (any build), events export as OTel log records
carrying the enclosing span's trace_id / span_id. Only WARN and ERROR
events are also recorded on spans as span events.
- Prometheus metrics (`imageserver_image_total`,
`imageserver_video_total`) MUST be maintained for key counters.
- Errors MUST be logged at `error!` level with sufficient context
@@ -136,8 +137,8 @@ job in one trace by construction.
- **Image Processing**: `image` crate for thumbnails, `kamadak-exif`
for EXIF extraction
- **Tracing**: `tracing` + `tracing-opentelemetry` (every build), OTLP
export when `OTLP_OTLS_ENDPOINT` is set; logs via `env_logger` (debug) /
OTel log export (release)
export when `OTLP_OTLS_ENDPOINT` is set; logs through the same
subscriber via `opentelemetry-appender-tracing` (`log::` bridged)
- **Testing**: `cargo test`, `actix_web::test`, in-memory SQLite
External dependencies (ffmpeg, Ollama) are optional runtime
@@ -177,4 +178,4 @@ MUST comply with these principles.
these principles. The CLAUDE.md file provides runtime development
guidance and MUST remain consistent with this constitution.
**Version**: 1.1.0 | **Ratified**: 2026-02-26 | **Last Amended**: 2026-09-29
**Version**: 1.2.0 | **Ratified**: 2026-02-26 | **Last Amended**: 2026-09-29