Skip to content

Conversation

@uuushiro
Copy link
Contributor

@uuushiro uuushiro commented Dec 30, 2025

Summary

This PR adds optional tracing instrumentation for database operations, enabling distributed tracing and observability.

  • Introduces tracing-spans feature flag for opt-in tracing support
  • Creates spans for all database operations (execute, query_one, query_all) and transaction flows (begin, commit, rollback)
  • Records OpenTelemetry-compatible semantic attributes (db.system, db.operation, db.statement, otel.status_code)
  • Uses .instrument(span) pattern for proper async span context propagation

Motivation

As noted in #2867, logs alone make it difficult to understand database call hierarchies and timing within request contexts. Spans provide:

  • Hierarchy: Which DB calls happened under which request
  • Timing: Precise duration of each operation
  • Context: Error status and query details for debugging

Design Decision

The original issue proposed an ObservabilityHook pattern. This PR takes a simpler approach by using the tracing crate directly:

  1. Standard ecosystem: tracing is the de facto standard for Rust instrumentation
  2. Simpler integration: Users just enable the feature and configure their tracing subscriber
  3. Backend agnostic: Works with any tracing-compatible backend (Jaeger, Datadog, OpenTelemetry, etc.)
  4. SQL safety: Relies on tracing backends (e.g., Datadog Agent) for SQL obfuscation rather than implementing custom filtering

Usage

[dependencies]
sea-orm = { version = "2.0", features = ["tracing-spans"] }
// Set up any tracing subscriber
tracing_subscriber::fmt()
    .with_max_level(tracing::Level::INFO)
    .init();

// All database operations automatically generate spans
let db = Database::connect("postgres://...").await?;
let users = User::find().all(&db).await?;  // Generates span with db.* attributes

Span Attributes

Attribute Description Example
db.system Database type postgresql, mysql, sqlite
db.operation SQL operation SELECT, INSERT, UPDATE, DELETE
db.statement SQL query SELECT * FROM users WHERE id = $1
otel.status_code Result status OK, ERROR
exception.message Error details (on failure)

Closes #2867

@uuushiro uuushiro marked this pull request as ready for review December 30, 2025 14:33
@uuushiro
Copy link
Contributor Author

#2867 (comment)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Official support for span-based tracing

1 participant