Official support for span-based tracing

[uuushiro]

First of all, thank you for all your work maintaining SeaORM.

Motivation

SeaORM’s official documentation currently focuses on debug logging (enabling SQL logs via RUST_LOG, etc.). This is helpful for local debugging, but it’s mostly logging-oriented, and it doesn’t provide strong support for span-based tracing (e.g., parent/child spans under an HTTP request span, standardized DB span attributes, timing, error status, etc.).

In practice, many teams want distributed tracing style visibility: “this HTTP request → these DB operations → which query was slow / failed”. Logs alone make this much harder.Spans provide hierarchy and timing (“which DB calls happened under this request?”), which is difficult to achieve with logging-only approaches.

There is clear ecosystem interest in OpenTelemetry-compatible spans

• sqlx-tracing instruments SQLx operations by wrapping pools/executors and emitting OpenTelemetry-style span fields.
• sea-orm-tracing (community crate) implements a traced wrapper around DatabaseConnection / ConnectionTrait and emphasizes automatic nesting of DB spans under the current active span (HTTP middleware, etc.).

These examples show demand, but the lack of an official hook forces users into “external wrapper” strategies or ad-hoc solutions.

Proposed Solutions

Introduce a small, optional instrumentation hook in SeaORM core that can be used to create spans around DB operations.

Concept

An ObservabilityHook (name bikesheddable) that is invoked around query execution paths

• called for execute, query_one, query_all, stream, execute_unprepared
• also used in transaction flows (begin/commit/rollback where applicable)

This hook would allow SeaORM to remain backend-agnostic while enabling

• span creation with correct parent/child relationships
• error recording
• duration measurement
• standardized attributes following OpenTelemetry DB semantic conventions

Design goals

• Opt-in / zero overhead by default (no hook → no extra allocations/spans)
• Minimal API surface (don’t bake OpenTelemetry types into SeaORM; just enable tracing integration)
• Works for existing backends (Postgres/MySQL/SQLite)

Related: Proxy / extension points

I saw recent work improving proxy-related behavior (e.g., ProxyDatabase support in transaction impl).

That’s great progress—separately, it would be helpful to discuss whether proxy/hook patterns could become a stable extension point for observability (not only testing/mocking).

Questions for maintainers

Does the overall direction make sense to you — i.e., strengthening SeaORM’s span-based tracing instrumentation (OpenTelemetry-friendly) in addition to the existing debug logging? If you agree with the goal, what do you think is the best approach in SeaORM’s architecture?

A lightweight hook/middleware around execution paths (driver / connection / transaction), orSome other extension point you’d recommend?

[Huliiiiii]

I'm not familiar with this. But I think we can implement basic support first and then refine it based on community feedback.
PR welcome.

[uuushiro]

@Huliiiiii Thanks! I’m going to try putting together a PR for the basic support first.

@tyt2y3 If you have any feedback on the idea or overall direction, I’d really appreciate it.

[uuushiro]

I've created a draft PR #2885 to address this issue.

While the original proposal suggested an ObservabilityHook pattern, this PR takes a simpler approach by using the tracing crate directly. This provides immediate value with minimal API surface.
I'd appreciate feedback on the overall direction. If this approach doesn't align with the project's vision, I'm happy to close the PR and adjust accordingly.