feat: add telemetry support with prometheus metrics and opentelemetry tracing

Author: mx-gp

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.23-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 WORKDIR /app
 COPY go.mod ./

cmd/sqlens/main.go

@@ -12,12 +12,21 @@ import (
 	"github.com/sqlens/sqlens/config"
 	"github.com/sqlens/sqlens/proxy"
 	"github.com/sqlens/sqlens/store"
+	"github.com/sqlens/sqlens/telemetry"
 	"github.com/sqlens/sqlens/web"
 )
 
 func main() {
 	cfg := config.LoadConfig()
 
+	// Initialize Telemetry
+	tp, err := telemetry.InitTracer()
+	if err != nil {
+		slog.Error("Failed to initialize tracer", "err", err)
+		os.Exit(1)
+	}
+	defer telemetry.Shutdown(context.Background(), tp)
+
 	// Initialize Storage
 	memStore := store.NewMemoryStore()
 

go.mod

@@ -1,5 +1,29 @@
 module github.com/sqlens/sqlens
 
-go 1.23.4
+go 1.25.0
 
-require github.com/lib/pq v1.11.2 // indirect
+require (
+	github.com/lib/pq v1.11.2
+	github.com/prometheus/client_golang v1.23.2
+	go.opentelemetry.io/otel v1.42.0
+	go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.42.0
+	go.opentelemetry.io/otel/sdk v1.42.0
+	go.opentelemetry.io/otel/trace v1.42.0
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.42.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	google.golang.org/protobuf v1.36.8 // indirect
+)

go.sum

@@ -1,2 +1,68 @@
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lib/pq v1.11.2 h1:x6gxUeu39V0BHZiugWe8LXZYZ+Utk7hSJGThs8sdzfs=
 github.com/lib/pq v1.11.2/go.mod h1:/p+8NSbOcwzAEI7wiMXFlgydTwcgTr3OSKMsD2BitpA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
+github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
+github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
+github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
+github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/otel v1.42.0 h1:lSQGzTgVR3+sgJDAU/7/ZMjN9Z+vUip7leaqBKy4sho=
+go.opentelemetry.io/otel v1.42.0/go.mod h1:lJNsdRMxCUIWuMlVJWzecSMuNjE7dOYyWlqOXWkdqCc=
+go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.42.0 h1:s/1iRkCKDfhlh1JF26knRneorus8aOwVIDhvYx9WoDw=
+go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.42.0/go.mod h1:UI3wi0FXg1Pofb8ZBiBLhtMzgoTm1TYkMvn71fAqDzs=
+go.opentelemetry.io/otel/metric v1.42.0 h1:2jXG+3oZLNXEPfNmnpxKDeZsFI5o4J+nz6xUlaFdF/4=
+go.opentelemetry.io/otel/metric v1.42.0/go.mod h1:RlUN/7vTU7Ao/diDkEpQpnz3/92J9ko05BIwxYa2SSI=
+go.opentelemetry.io/otel/sdk v1.42.0 h1:LyC8+jqk6UJwdrI/8VydAq/hvkFKNHZVIWuslJXYsDo=
+go.opentelemetry.io/otel/sdk v1.42.0/go.mod h1:rGHCAxd9DAph0joO4W6OPwxjNTYWghRWmkHuGbayMts=
+go.opentelemetry.io/otel/sdk/metric v1.42.0 h1:D/1QR46Clz6ajyZ3G8SgNlTJKBdGp84q9RKCAZ3YGuA=
+go.opentelemetry.io/otel/sdk/metric v1.42.0/go.mod h1:Ua6AAlDKdZ7tdvaQKfSmnFTdHx37+J4ba8MwVCYM5hc=
+go.opentelemetry.io/otel/trace v1.42.0 h1:OUCgIPt+mzOnaUTpOQcBiM/PLQ/Op7oq6g4LenLmOYY=
+go.opentelemetry.io/otel/trace v1.42.0/go.mod h1:f3K9S+IFqnumBkKhRJMeaZeNk9epyhnCmQh/EysQCdc=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
+go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
+google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

metrics/prometheus.go

@@ -0,0 +1,65 @@
+package metrics
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+	QueriesTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "sqlens_queries_total",
+		Help: "Total number of SQL queries intercepted",
+	}, []string{"n1_flag", "has_violations"})
+
+	QueryLatency = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "sqlens_query_latency_seconds",
+		Help:    "Latency of SQL queries in seconds",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"fingerprint"})
+
+	N1IncidentsTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "sqlens_n1_incidents_total",
+		Help: "Total number of N+1 incidents detected",
+	}, []string{"fingerprint"})
+
+	ViolationsTotal = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "sqlens_violations_total",
+		Help: "Total number of SQL guardrail violations detected",
+	}, []string{"violation_type"})
+)
+
+func RecordEvent(n1 bool, violations []string, latency float64, fingerprint string) {
+	hasViolations := "false"
+	if len(violations) > 0 {
+		hasViolations = "true"
+	}
+
+	n1Flag := "false"
+	if n1 {
+		n1Flag = "true"
+		N1IncidentsTotal.WithLabelValues(fingerprint).Inc()
+	}
+
+	QueriesTotal.WithLabelValues(n1Flag, hasViolations).Inc()
+	QueryLatency.WithLabelValues(fingerprint).Observe(latency)
+
+	for _, v := range violations {
+		// Basic violation type extraction (e.g., from "SLOW: ...")
+		vType := "unknown"
+		if i := len(v); i > 0 {
+			if parts := splitViolation(v); len(parts) > 0 {
+				vType = parts[0]
+			}
+		}
+		ViolationsTotal.WithLabelValues(vType).Inc()
+	}
+}
+
+func splitViolation(v string) []string {
+	for i := 0; i < len(v); i++ {
+		if v[i] == ':' {
+			return []string{v[:i]}
+		}
+	}
+	return nil
+}

metrics/prometheus_test.go

@@ -0,0 +1,29 @@
+package metrics
+
+import (
+	"testing"
+
+	"github.com/prometheus/client_golang/prometheus"
+	dto "github.com/prometheus/client_model/go"
+)
+
+func TestRecordEvent(t *testing.T) {
+	// We can't easily reset promauto-registered metrics in a simple test,
+	// but we can check if they increment.
+	
+	initialQueries := getCounterValue(QueriesTotal.WithLabelValues("false", "false"))
+	
+	RecordEvent(false, nil, 0.1, "test-fingerprint")
+	
+	finalQueries := getCounterValue(QueriesTotal.WithLabelValues("false", "false"))
+	
+	if finalQueries != initialQueries+1 {
+		t.Errorf("Expected QueriesTotal to increment, got %f -> %f", initialQueries, finalQueries)
+	}
+}
+
+func getCounterValue(counter prometheus.Counter) float64 {
+	var m dto.Metric
+	counter.Write(&m)
+	return m.GetCounter().GetValue()
+}

proxy/server.go

@@ -8,6 +8,10 @@ import (
 	"time"
 
 	"github.com/sqlens/sqlens/analyzer"
+	"github.com/sqlens/sqlens/metrics"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
 )
 
 type Server struct {
@@ -16,6 +20,7 @@ type Server struct {
 	pipeline        *analyzer.Pipeline
 	store           EventStore
 	redactSensitive bool
+	tracer          trace.Tracer
 }
 
 // EventStore represents an interface to save and retrieve query events
@@ -30,6 +35,7 @@ func NewServer(listen, target string, p *analyzer.Pipeline, s EventStore, redact
 		pipeline:        p,
 		store:           s,
 		redactSensitive: redact,
+		tracer:          otel.Tracer("sqlens-proxy"),
 	}
 }
 
@@ -84,6 +90,8 @@ func (s *Server) handleConnection(ctx context.Context, clientConn net.Conn) {
 
 	var lastQueryStart time.Time
 	var lastQueryStr string
+	var lastQueryCtx context.Context
+	var lastQuerySpan trace.Span
 	var mu sync.Mutex
 
 	var wg sync.WaitGroup
@@ -107,13 +115,23 @@ func (s *Server) handleConnection(ctx context.Context, clientConn net.Conn) {
 			// Sniff PostgreSQL 'Q' (Simple Query)
 			if n > 5 && buf[0] == 'Q' {
 				mu.Lock()
+				if lastQuerySpan != nil {
+					lastQuerySpan.End()
+				}
 				lastQueryStart = time.Now()
 				// Basic safety: limit query string size to avoid huge allocations
 				end := n - 1
 				if end > 2048 {
 					end = 2048
 				}
 				lastQueryStr = string(buf[5:end])
+				
+				// Start OpenTelemetry span
+				qCtx, span := s.tracer.Start(ctx, "sql_query", 
+					trace.WithAttributes(attribute.String("sql.query", lastQueryStr)))
+				lastQueryCtx = qCtx
+				lastQuerySpan = span
+				
 				mu.Unlock()
 			}
 
@@ -143,10 +161,14 @@ func (s *Server) handleConnection(ctx context.Context, clientConn net.Conn) {
 			if !lastQueryStart.IsZero() {
 				latency := time.Since(lastQueryStart)
 				query := lastQueryStr
+				qCtx := lastQueryCtx
+				qSpan := lastQuerySpan
 				lastQueryStart = time.Time{}
+				lastQueryCtx = nil
+				lastQuerySpan = nil
 				mu.Unlock()
 
-				go func(q string, l time.Duration) {
+				go func(q string, l time.Duration, ctx context.Context, span trace.Span) {
 					defer func() { recover() }() // Async processing safety
 					event := analyzer.QueryEvent{
 						ConnectionID: connID,
@@ -156,15 +178,28 @@ func (s *Server) handleConnection(ctx context.Context, clientConn net.Conn) {
 					}
 
 					// Reassign event to the one that's been through the pipeline
-					event = s.pipeline.Process(context.Background(), event)
+					event = s.pipeline.Process(ctx, event)
+
+					// Record Prometheus metrics
+					metrics.RecordEvent(event.N1Flag, event.Violations, l.Seconds(), event.Fingerprint)
+
+					// Update and End Span
+					if span != nil {
+						span.SetAttributes(
+							attribute.String("sql.fingerprint", event.Fingerprint),
+							attribute.Bool("sqlens.n1_flag", event.N1Flag),
+							attribute.StringSlice("sqlens.violations", event.Violations),
+						)
+						span.End()
+					}
 
 					// If redaction is enabled, mask the raw SQL
 					if s.redactSensitive {
 						event.RawQuery = event.Fingerprint
 					}
 
 					s.store.Save(event)
-				}(query, latency)
+				}(query, latency, qCtx, qSpan)
 			} else {
 				mu.Unlock()
 			}

telemetry/otel.go

@@ -0,0 +1,47 @@
+package telemetry
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
+	"go.opentelemetry.io/otel/sdk/resource"
+	"go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
+)
+
+func InitTracer() (*trace.TracerProvider, error) {
+	exporter, err := stdouttrace.New(
+		stdouttrace.WithPrettyPrint(),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("creating stdout exporter: %w", err)
+	}
+
+	res, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			resource.Default().SchemaURL(),
+			semconv.ServiceNameKey.String("sqlens"),
+		),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("creating resource: %w", err)
+	}
+
+	tp := trace.NewTracerProvider(
+		trace.WithBatcher(exporter),
+		trace.WithResource(res),
+	)
+	otel.SetTracerProvider(tp)
+
+	return tp, nil
+}
+
+func Shutdown(ctx context.Context, tp *trace.TracerProvider) {
+	if err := tp.Shutdown(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Error shutting down tracer provider: %v\n", err)
+	}
+}

telemetry/otel_test.go

@@ -0,0 +1,17 @@
+package telemetry
+
+import (
+	"context"
+	"testing"
+)
+
+func TestInitTracer(t *testing.T) {
+	tp, err := InitTracer()
+	if err != nil {
+		t.Fatalf("Failed to initialize tracer: %v", err)
+	}
+	if tp == nil {
+		t.Fatal("Expected TracerProvider to be non-nil")
+	}
+	defer Shutdown(context.Background(), tp)
+}