Skip to content

Query source tracking (call-site attribution), mirroring the Rust driver #78

Description

@polaz

Feature: query source tracking (call-site attribution)

The Rust driver (coordinode-client) already supports source tracking: when
enabled, every query method captures the caller's source location (file + line)
and sends it alongside the query so the server can attribute slow/expensive
queries back to the exact call site (query advisor / EXPLAIN). The Python SDK
should mirror that contract so all three reference drivers (Rust, TypeScript,
Python) behave consistently.

Rust reference contract

  • #[track_caller] on every public query method captures the caller frame.
  • An opt-in connection/config flag (debug_source_tracking(bool)) gates it; off
    by default (zero overhead in production).
  • When on, the captured file:line is attached to the request metadata.

What the Python SDK needs

  • Capture the caller frame via inspect.stack() (skip internal SDK frames) when
    the debug flag is set.
  • A debug flag in the connection/client options (e.g. debug_source_tracking=True),
    off by default.
  • Attach the captured file:line to the request metadata, matching the wire
    field the Rust driver populates.
  • Tests: with the flag off, no frame inspection happens and no metadata is sent;
    with it on, a query carries the correct call-site file:line.

Acceptance

Source tracking in the Python SDK is behaviourally equivalent to the Rust driver:
opt-in, off by default, correct file:line attribution when enabled.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions