Documentation
¶
Overview ¶
Package debuglog is the step-level debug tracer for the databricks-sql-go SEA/kernel integration.
The SEA-via-kernel path crosses a Go-GC <-> Rust-ownership FFI boundary where failures are silent and non-local (thread migration, use-after-free, thread blowup, cross-region latency that looks like "the protocol is slow"). A Go stack trace stops at the cgo edge, so the way to see which step failed or slowed down is an explicit, ordered, timed, per-function log at each step — in particular an "enter" line emitted *before* a step runs, so a step that hangs at the FFI edge (and never returns) is still visible.
This is a thin helper over the driver's single logger (logger.Logger): every event is an ordinary debug-level line on the same sink, in the same format (JSON in production, pretty in a terminal) as the rest of the driver's logs. There is no second logger and no separate output knob — turn it on the way you turn on any driver logging, with logger.SetLogLevel("debug") or DATABRICKS_LOG_LEVEL=debug. That keeps these lines readable next to the existing driver logs and lets kernel-side logs (written to the same stderr) interleave into one stream in execution order.
Each event carries the function the step is in, the phase ("enter"/"done", omitted for a point log), the elapsed time (on "done"), and the conn/correlation/query ids from the context. The shared logger supplies the timestamp and level fields, so the format matches every other driver line.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Enabled ¶
func Enabled() bool
Enabled reports whether debug-level logging is currently on, i.e. whether events would be emitted. Cheap enough to call at every step; callers use it to skip building expensive log arguments. It simply reflects the driver's log level, so debug tracing follows SetLogLevel like every other driver log.
func Logf ¶
Logf emits a single function-tagged step event at debug level. fn is the function the step is in (e.g. "thrift.Backend.Execute"); the format/args describe the step. No-op when debug logging is off (the underlying event is nil and discards cheaply) — guard the call with Enabled() if the args are expensive to build.
func Track ¶
Track marks the start of a step and returns a function that logs the step's elapsed time. Intended for `defer`:
defer debuglog.Track(ctx, "thrift.Backend.Execute", "sql.len=%d", len(query))()
The enter event is emitted immediately (so a step that never returns is still visible); the returned closure emits a matching done event carrying the elapsed duration. Both are no-ops when debug logging is off, and the returned closure is always safe to call.
Example ¶
ExampleTrack shows the intended defer-Track idiom.
prevLevel := logger.Logger.GetLevel()
_ = logger.SetLogLevel("debug")
defer func() { logger.Logger.Logger = logger.Logger.Level(prevLevel) }()
fn := func(ctx context.Context) {
defer Track(ctx, "pkg.example", "doing work")()
}
fn(context.Background())
fmt.Println("ran")
Output: ran
Types ¶
This section is empty.
Source Files