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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions