sql

Documentation

Index

• func ParseSQLComment(query string) (CommentResult, CommentStatus)
• func StripSQLComment(query string) string
• type CommentResult
• type CommentStatus
• type Correlator
  • func NewCorrelator(ttl time.Duration) *Correlator
  • func (c *Correlator) ClearActive(traceID, spanID string)
  • func (c *Correlator) Correlate() (traceID, parentID string)
  • func (c *Correlator) SetActive(traceID, spanID string)
• type DBProtocol
• type PGProtocol
  • func (PGProtocol) HandleConnection(clientConn, serverConn RawConn, connID uint64, onQuery func(QueryEvent))
  • func (PGProtocol) Name() string
• type Proxy
  • func NewProxy(target string, collector *trace.Collector, correlator *Correlator) *Proxy
  • func (p *Proxy) Close() error
  • func (p *Proxy) Listen(ctx context.Context, addr string) error
  • func (p *Proxy) Serve() error
• type QueryEvent
• type RawConn

Functions

func ParseSQLComment

func ParseSQLComment(query string) (CommentResult, CommentStatus)

ParseSQLComment extracts a W3C traceparent from a trailing sqlcommenter comment (e.g. /*traceparent='00-...-...-01'*/). It returns CommentOK with the parsed result on success, CommentInvalid if a traceparent key exists but the value is malformed, and CommentAbsent if no traceparent key is found.

func StripSQLComment

func StripSQLComment(query string) string

StripSQLComment removes a trailing SQL block comment (such as a sqlcommenter comment) from the query. Non-trailing comments (e.g. optimizer hints) are preserved.

Types

type CommentResult

type CommentResult struct {
	TraceID  string
	ParentID string
}

CommentResult holds the parsed traceparent from a sqlcommenter comment.

type CommentStatus

type CommentStatus int

CommentStatus indicates the result of parsing a sqlcommenter traceparent.

const (
	// CommentAbsent means no trailing comment or no traceparent key was found.
	CommentAbsent CommentStatus = iota
	// CommentInvalid means a traceparent key was found but the value is malformed.
	CommentInvalid
	// CommentOK means a valid traceparent was extracted.
	CommentOK
)

type Correlator

type Correlator struct {
	// contains filtered or unexported fields
}

Correlator associates SQL spans with the most recently active HTTP/gRPC trace. It maintains a stack of active contexts so that concurrent requests are handled correctly: each SetActive pushes a context, ClearActive removes it, and Correlate returns the most recent non-expired entry.

func NewCorrelator

func NewCorrelator(ttl time.Duration) *Correlator

func (*Correlator) ClearActive

func (c *Correlator) ClearActive(traceID, spanID string)

ClearActive removes the entry matching the given traceID and spanID. Called when an HTTP or gRPC span completes.

func (*Correlator) Correlate

func (c *Correlator) Correlate() (traceID, parentID string)

Correlate returns the trace and parent span ID for a SQL query. It returns the most recent non-expired entry from the stack. If no active trace is found within the TTL, new IDs are generated.

func (*Correlator) SetActive

func (c *Correlator) SetActive(traceID, spanID string)

SetActive pushes a trace context onto the stack, typically called when an HTTP or gRPC span begins.

type DBProtocol

type DBProtocol interface {
	// Name returns the protocol name (e.g., "postgres", "mysql").
	Name() string

	// HandleConnection processes a single client connection, parsing the wire
	// protocol and emitting QueryEvents through the callback.
	HandleConnection(clientConn, serverConn RawConn, connID uint64, onQuery func(QueryEvent))
}

DBProtocol defines the interface for database wire protocol parsing. This allows future support for MySQL and other databases.

type PGProtocol

type PGProtocol struct{}

PGProtocol implements DBProtocol for PostgreSQL wire protocol.

func (PGProtocol) HandleConnection

func (PGProtocol) HandleConnection(clientConn, serverConn RawConn, connID uint64, onQuery func(QueryEvent))

func (PGProtocol) Name

func (PGProtocol) Name() string

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

func NewProxy

func NewProxy(target string, collector *trace.Collector, correlator *Correlator) *Proxy

func (*Proxy) Close

func (p *Proxy) Close() error

func (*Proxy) Listen

func (p *Proxy) Listen(ctx context.Context, addr string) error

func (*Proxy) Serve

func (p *Proxy) Serve() error

type QueryEvent

type QueryEvent struct {
	Query    string
	Start    time.Time
	Duration float64 // milliseconds
	RowCount int
	Error    string
	ConnID   uint64
}

QueryEvent represents a captured SQL query.

type RawConn

type RawConn interface {
	Read(b []byte) (n int, err error)
	Write(b []byte) (n int, err error)
	Close() error
}

RawConn abstracts a network connection for protocol handlers.