|
|
|
@@ -1,20 +1,31 @@
|
|
|
|
|
<!--
|
|
|
|
|
Sync Impact Report
|
|
|
|
|
==================
|
|
|
|
|
Version change: (new) -> 1.0.0
|
|
|
|
|
Modified principles: N/A (initial ratification)
|
|
|
|
|
Added sections:
|
|
|
|
|
- Core Principles (5 principles)
|
|
|
|
|
- Technology Stack & Constraints
|
|
|
|
|
- Development Workflow
|
|
|
|
|
- Governance
|
|
|
|
|
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.
|
|
|
|
|
Modified principles:
|
|
|
|
|
- V. Observability: mechanism + rules updated for the tracing migration
|
|
|
|
|
(map #135, PR #148)
|
|
|
|
|
Also updated:
|
|
|
|
|
- I. Layered Architecture: Database Layer "traced" wording
|
|
|
|
|
- Technology Stack & Constraints: Tracing line
|
|
|
|
|
Added sections: N/A
|
|
|
|
|
Removed sections: N/A
|
|
|
|
|
Templates requiring updates:
|
|
|
|
|
- .specify/templates/plan-template.md — ✅ no changes needed (Constitution Check section is generic)
|
|
|
|
|
- .specify/templates/plan-template.md — ✅ no changes needed (generic Constitution Check)
|
|
|
|
|
- .specify/templates/spec-template.md — ✅ no changes needed
|
|
|
|
|
- .specify/templates/tasks-template.md — ✅ no changes needed
|
|
|
|
|
- .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
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
@@ -34,7 +45,8 @@ All features MUST follow the established layered architecture:
|
|
|
|
|
contracts. Every DAO MUST be defined as a trait to enable mock
|
|
|
|
|
implementations for testing.
|
|
|
|
|
- **Database Layer** (Diesel ORM, `schema.rs`): Concrete `Sqlite*Dao`
|
|
|
|
|
implementations. All queries traced with OpenTelemetry.
|
|
|
|
|
implementations. Every query runs inside a `tracing` span via
|
|
|
|
|
`otel::trace_db_call`.
|
|
|
|
|
|
|
|
|
|
New features MUST NOT bypass layers (e.g., HTTP handlers MUST NOT
|
|
|
|
|
execute raw SQL). Actix actors are permitted for long-running async
|
|
|
|
@@ -84,17 +96,35 @@ prohibited.
|
|
|
|
|
|
|
|
|
|
### V. Observability
|
|
|
|
|
|
|
|
|
|
All database operations and HTTP handlers MUST be instrumented
|
|
|
|
|
with OpenTelemetry spans via the `trace_db_call` helper or
|
|
|
|
|
equivalent tracing macros.
|
|
|
|
|
All database operations and HTTP handlers MUST be instrumented with
|
|
|
|
|
`tracing` spans, exported through `tracing-opentelemetry`: DAO bodies via
|
|
|
|
|
`otel::trace_db_call`, and handlers / feature functions via
|
|
|
|
|
`#[tracing::instrument]`. The per-request root span comes from the
|
|
|
|
|
`tracing-actix-web` middleware, which also honors an incoming W3C
|
|
|
|
|
`traceparent`.
|
|
|
|
|
|
|
|
|
|
- Release builds export traces to the configured OTLP endpoint.
|
|
|
|
|
- Debug builds use the basic logger.
|
|
|
|
|
- Spans are produced in debug and release builds alike. OTLP export is
|
|
|
|
|
enabled by `OTLP_OTLS_ENDPOINT`, not by build profile.
|
|
|
|
|
- Code MUST NOT thread an OpenTelemetry `Context` through call chains.
|
|
|
|
|
Spans parent on the ambient span.
|
|
|
|
|
- Every `tokio::spawn` or cross-thread fan-out (rayon, per-pass runtimes)
|
|
|
|
|
MUST carry its parent span: `.instrument(span)` or
|
|
|
|
|
`info_span!(parent: &span, ...)`. Tracing context is thread-local, and
|
|
|
|
|
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.
|
|
|
|
|
- Prometheus metrics (`imageserver_image_total`,
|
|
|
|
|
`imageserver_video_total`) MUST be maintained for key counters.
|
|
|
|
|
- Errors MUST be logged at `error!` level with sufficient context
|
|
|
|
|
for debugging without reproducing the issue.
|
|
|
|
|
|
|
|
|
|
**Rationale:** span parenting that relies on hand-threaded contexts drifted
|
|
|
|
|
into orphaned traces (the pre-migration baseline, #137). Ambient
|
|
|
|
|
parenting, plus an explicit carry at each spawn boundary, keeps a request or
|
|
|
|
|
job in one trace by construction.
|
|
|
|
|
|
|
|
|
|
## Technology Stack & Constraints
|
|
|
|
|
|
|
|
|
|
- **Language**: Rust (stable toolchain, Cargo build system)
|
|
|
|
@@ -105,8 +135,9 @@ equivalent tracing macros.
|
|
|
|
|
- **Video Processing**: ffmpeg/ffprobe (CLI, must be on PATH)
|
|
|
|
|
- **Image Processing**: `image` crate for thumbnails, `kamadak-exif`
|
|
|
|
|
for EXIF extraction
|
|
|
|
|
- **Tracing**: OpenTelemetry with OTLP export (release),
|
|
|
|
|
basic logger (debug)
|
|
|
|
|
- **Tracing**: `tracing` + `tracing-opentelemetry` (every build), OTLP
|
|
|
|
|
export when `OTLP_OTLS_ENDPOINT` is set; logs via `env_logger` (debug) /
|
|
|
|
|
OTel log export (release)
|
|
|
|
|
- **Testing**: `cargo test`, `actix_web::test`, in-memory SQLite
|
|
|
|
|
|
|
|
|
|
External dependencies (ffmpeg, Ollama) are optional runtime
|
|
|
|
@@ -146,4 +177,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.0.0 | **Ratified**: 2026-02-26 | **Last Amended**: 2026-02-26
|
|
|
|
|
**Version**: 1.1.0 | **Ratified**: 2026-02-26 | **Last Amended**: 2026-09-29
|