feat: add route exclusion for health check endpoints (#27)

* feat: add route exclusion to skip tracing health check endpoints

Health check endpoints (/health, /metrics, /ready, etc.) generate noise
and inflate trace volume. This adds configurable path exclusion that
leverages each OTel middleware's native filter mechanism (WithFilter/
WithSkipper), so excluded paths never create spans.

Three-layer matcher (exact, prefix, glob) configured via env vars:
- LAST9_EXCLUDED_PATHS (default: /health,/healthz,/metrics,/ready,/live,/ping)
- LAST9_EXCLUDED_PATH_PREFIXES (default: none)
- LAST9_EXCLUDED_PATH_PATTERNS (default: /*/health,/*/healthz,/*/metrics,/*/ready,/*/live,/*/ping)

Set any env var to "" to opt out of its defaults.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve lint errors in routematcher tests

Fix fieldalignment (govet) and gofmt issues:
- Reorder struct fields for optimal GC pointer scanning
- Use named fields in TestIsEmpty struct literals
- Run gofmt for consistent formatting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add route exclusion section to README

Document the route exclusion feature including default excluded paths,
configuration env vars, usage examples, and matching behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(config): reorder Config struct fields to satisfy fieldalignment lint

Move SampleRate and SamplerRatio (float64, non-pointer) after all slice
fields so the GC scan range shrinks from 184 to 168 bytes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(instrumentation): prefer var declaration over empty slice literal

Replace `opts := []T{}` with `var opts []T` in echo, gin, and gorilla
middleware — idiomatic Go for nil-initialized slices that may stay empty.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: karthikeyangs9 <karthikeyan@last9.io>

Author: 3 people

README.md

@@ -17,6 +17,7 @@ A drop-in OpenTelemetry agent for Go applications that minimizes code changes wh
 - [Log-Trace Correlation (zap)](#-log-trace-correlation-zap) - zap
 - [Log-Trace Correlation (slog)](#-log-trace-correlation) - slog
 - [Metrics Support](#-metrics-support) - Automatic • Custom • Runtime
+- [Route Exclusion](#-route-exclusion) - Skip tracing for health checks & internal paths
 - [Configuration](#️-configuration)
 - [Requirements & Compatibility](#-requirements--compatibility)
 - [Testing](#-testing)
@@ -29,6 +30,7 @@ A drop-in OpenTelemetry agent for Go applications that minimizes code changes wh
 - 🎯 **Auto-instrumentation** - HTTP, gRPC, SQL, MongoDB, Redis, Kafka automatically traced with proper span nesting
 - 📊 **Automatic metrics** - Runtime (memory, GC, goroutines), HTTP, gRPC, database, MongoDB, Kafka, Redis metrics out-of-the-box
 - 📈 **Custom metrics** - Simple helpers for counters, histograms, gauges for business metrics
+- 🚫 **Route exclusion** - Automatically skips health checks and infrastructure endpoints from tracing
 - ⚙️ **Environment-based config** - Uses standard OpenTelemetry environment variables (no hardcoded config)
 - 🔗 **Log-trace correlation** - Automatic `trace_id`/`span_id` injection into `log/slog` log entries
 - 🔍 **Complete observability** - Full distributed tracing + metrics across all layers (HTTP → gRPC → DB → External APIs)
@@ -907,6 +909,45 @@ func processOrder(ctx context.Context, value float64) {
 }
 ```
 
+## 🚫 Route Exclusion
+
+The agent automatically skips tracing for common health check and infrastructure endpoints, reducing noise in your traces. This works across all supported frameworks (net/http, Gin, Chi, Echo, Gorilla Mux, gRPC-Gateway).
+
+### Default Excluded Routes
+
+Out of the box, the following paths are excluded from tracing:
+
+- **Exact paths**: `/health`, `/healthz`, `/metrics`, `/ready`, `/live`, `/ping`
+- **Glob patterns**: `/*/health`, `/*/healthz`, `/*/metrics`, `/*/ready`, `/*/live`, `/*/ping`
+
+### Configuration
+
+Three environment variables control route exclusion:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LAST9_EXCLUDED_PATHS` | `/health,/healthz,/metrics,/ready,/live,/ping` | Exact path matches |
+| `LAST9_EXCLUDED_PATH_PREFIXES` | *(none)* | Prefix matches (e.g., `/internal/`) |
+| `LAST9_EXCLUDED_PATH_PATTERNS` | `/*/health,/*/healthz,/*/metrics,/*/ready,/*/live,/*/ping` | Glob patterns using `path.Match` semantics |
+
+### Examples
+
+```bash
+# Add a prefix exclusion for internal debug endpoints
+export LAST9_EXCLUDED_PATH_PREFIXES="/internal/,/debug/"
+
+# Custom exact paths to exclude
+export LAST9_EXCLUDED_PATHS="/health,/healthz,/status,/version"
+
+# Disable all default exclusions (trace everything)
+export LAST9_EXCLUDED_PATHS=""
+export LAST9_EXCLUDED_PATH_PATTERNS=""
+```
+
+### How It Works
+
+Route matching is evaluated in order: exact match (O(1) map lookup) → prefix match → glob pattern match. The first match wins. Setting an environment variable to an empty string (`""`) disables its defaults, allowing you to opt out of default exclusions.
+
 ## ⚙️ Configuration
 
 The agent reads configuration from environment variables following OpenTelemetry standards:
@@ -919,6 +960,9 @@ The agent reads configuration from environment variables following OpenTelemetry
 | `OTEL_SERVICE_VERSION` | No | - | Service version (e.g., git commit SHA) |
 | `OTEL_RESOURCE_ATTRIBUTES` | No | - | Additional attributes (key=value pairs) |
 | `OTEL_TRACES_SAMPLER` | No | `always_on` | Sampling strategy |
+| `LAST9_EXCLUDED_PATHS` | No | `/health,/healthz,...` | Exact paths to exclude from tracing |
+| `LAST9_EXCLUDED_PATH_PREFIXES` | No | - | Path prefixes to exclude from tracing |
+| `LAST9_EXCLUDED_PATH_PATTERNS` | No | `/*/health,/*/healthz,...` | Glob patterns to exclude from tracing |
 
 ### Resource Attributes
 

agent.go

@@ -23,6 +23,7 @@ import (
 	"time"
 
 	"github.com/last9/go-agent/config"
+	"github.com/last9/go-agent/internal/routematcher"
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
@@ -109,6 +110,7 @@ func WithSamplingRate(rate float64) Option {
 // Agent represents the Last9 telemetry agent
 type Agent struct {
 	config         *config.Config
+	routeMatcher   *routematcher.RouteMatcher
 	tracerProvider *sdktrace.TracerProvider
 	meterProvider  *metric.MeterProvider
 	shutdown       func(context.Context) error
@@ -185,8 +187,11 @@ func Start(opts ...Option) error {
 			log.Printf("[Last9 Agent] Warning: Failed to start runtime metrics: %v", runtimeErr)
 		}
 
+		rm := routematcher.New(cfg.ExcludedPaths, cfg.ExcludedPathPrefixes, cfg.ExcludedPathPatterns)
+
 		globalAgent.Store(&Agent{
 			config:         cfg,
+			routeMatcher:   rm,
 			tracerProvider: tp,
 			meterProvider:  mp,
 			shutdown: func(ctx context.Context) error {
@@ -245,6 +250,15 @@ func GetConfig() *config.Config {
 	return globalAgent.Load().config
 }
 
+// GetRouteMatcher returns the route matcher for path exclusion (or nil if not initialized).
+// Nil is safe to use — RouteMatcher.ShouldExclude on nil returns false (no exclusion).
+func GetRouteMatcher() *routematcher.RouteMatcher {
+	if a := globalAgent.Load(); a != nil {
+		return a.routeMatcher
+	}
+	return nil
+}
+
 // createResource creates an OpenTelemetry resource with service information
 func createResource(cfg *config.Config) (*resource.Resource, error) {
 	// Build base attributes

agent_test.go

@@ -363,6 +363,52 @@ func TestSampleRateUnsetFallsBackToSampler(t *testing.T) {
 	}
 }
 
+func TestGetRouteMatcher(t *testing.T) {
+	defer Reset()
+
+	// Before Start, returns nil
+	rm := GetRouteMatcher()
+	if rm != nil {
+		t.Error("GetRouteMatcher() should return nil before Start()")
+	}
+	// Nil receiver is safe — should not exclude anything
+	if rm.ShouldExclude("/health") {
+		t.Error("nil RouteMatcher should not exclude /health")
+	}
+
+	os.Setenv("OTEL_SERVICE_NAME", "test-service")
+	defer os.Unsetenv("OTEL_SERVICE_NAME")
+	// Use defaults (health endpoints excluded)
+	os.Unsetenv("LAST9_EXCLUDED_PATHS")
+	os.Unsetenv("LAST9_EXCLUDED_PATH_PREFIXES")
+	os.Unsetenv("LAST9_EXCLUDED_PATH_PATTERNS")
+
+	if err := Start(); err != nil {
+		t.Fatalf("Start() failed: %v", err)
+	}
+
+	rm = GetRouteMatcher()
+	if rm == nil {
+		t.Fatal("GetRouteMatcher() should return non-nil after Start()")
+	}
+	if rm.IsEmpty() {
+		t.Error("RouteMatcher should not be empty with default exclusion rules")
+	}
+
+	// Default exact excludes /health
+	if !rm.ShouldExclude("/health") {
+		t.Error("default RouteMatcher should exclude /health")
+	}
+	// Default pattern excludes /v1/health
+	if !rm.ShouldExclude("/v1/health") {
+		t.Error("default RouteMatcher should exclude /v1/health via glob pattern")
+	}
+	// Should not exclude normal paths
+	if rm.ShouldExclude("/api/users") {
+		t.Error("default RouteMatcher should not exclude /api/users")
+	}
+}
+
 func TestParseSamplerRatio(t *testing.T) {
 	tests := []struct {
 		input string

config/config.go

@@ -19,7 +19,23 @@ type Config struct {
 	Endpoint           string
 	Sampler            string
 	ResourceAttributes []attribute.KeyValue
-	SampleRate         float64
+
+	// ExcludedPaths is a list of exact URL paths to exclude from tracing (from LAST9_EXCLUDED_PATHS).
+	// Default: /health,/healthz,/metrics,/ready,/live,/ping
+	// Set LAST9_EXCLUDED_PATHS="" to disable defaults.
+	ExcludedPaths []string
+
+	// ExcludedPathPrefixes is a list of URL path prefixes to exclude from tracing (from LAST9_EXCLUDED_PATH_PREFIXES).
+	// Default: none
+	ExcludedPathPrefixes []string
+
+	// ExcludedPathPatterns is a list of glob patterns to exclude from tracing (from LAST9_EXCLUDED_PATH_PATTERNS).
+	// Uses path.Match semantics (not filepath.Match).
+	// Default: /*/health,/*/healthz,/*/metrics,/*/ready,/*/live,/*/ping
+	// Set LAST9_EXCLUDED_PATH_PATTERNS="" to disable defaults.
+	ExcludedPathPatterns []string
+
+	SampleRate float64
 	// SamplerRatio is the sampling ratio for traceidratio samplers (0.0-1.0).
 	// Only used when Sampler is "traceidratio" or "parentbased_traceidratio".
 	// Set via WithSamplingRate() option. Zero value means use OTEL_TRACES_SAMPLER_ARG env var.
@@ -47,6 +63,20 @@ func Load() *Config {
 		cfg.ServiceVersion,
 	)
 
+	// Parse route exclusion configuration
+	cfg.ExcludedPaths = parseCommaSeparatedWithDefault(
+		"LAST9_EXCLUDED_PATHS",
+		"/health,/healthz,/metrics,/ready,/live,/ping",
+	)
+	cfg.ExcludedPathPrefixes = parseCommaSeparatedWithDefault(
+		"LAST9_EXCLUDED_PATH_PREFIXES",
+		"",
+	)
+	cfg.ExcludedPathPatterns = parseCommaSeparatedWithDefault(
+		"LAST9_EXCLUDED_PATH_PATTERNS",
+		"/*/health,/*/healthz,/*/metrics,/*/ready,/*/live,/*/ping",
+	)
+
 	// Validate configuration
 	if cfg.Endpoint == "" {
 		log.Println("[Last9 Agent] Warning: OTEL_EXPORTER_OTLP_ENDPOINT not set - telemetry will not be exported")
@@ -110,6 +140,28 @@ func parseResourceAttributes(attrsStr string, serviceVersion string) ([]attribut
 	return attrs, environment, serviceVersion
 }
 
+// parseCommaSeparatedWithDefault reads an env var and splits it by comma.
+// If the env var is not set, defaultVal is used. If the env var is explicitly
+// set to "", an empty slice is returned (opt-out of defaults).
+func parseCommaSeparatedWithDefault(envKey, defaultVal string) []string {
+	raw, ok := os.LookupEnv(envKey)
+	if !ok {
+		raw = defaultVal
+	}
+	if raw == "" {
+		return nil
+	}
+
+	parts := strings.Split(raw, ",")
+	result := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if v := strings.TrimSpace(p); v != "" {
+			result = append(result, v)
+		}
+	}
+	return result
+}
+
 // getEnvOrDefault returns the environment variable value or a default
 func getEnvOrDefault(key, defaultValue string) string {
 	if value := os.Getenv(key); value != "" {

config/config_test.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"os"
+	"reflect"
 	"testing"
 )
 
@@ -70,3 +71,134 @@ func TestLoad_SampleRate(t *testing.T) {
 		}
 	})
 }
+
+func TestParseCommaSeparatedWithDefault(t *testing.T) {
+	tests := []struct {
+		name       string
+		envKey     string
+		envVal     *string // nil = not set
+		defaultVal string
+		want       []string
+	}{
+		{
+			name:       "env not set uses default",
+			envKey:     "TEST_PARSE_CSV_1",
+			envVal:     nil,
+			defaultVal: "/health,/metrics",
+			want:       []string{"/health", "/metrics"},
+		},
+		{
+			name:       "env set to empty opts out",
+			envKey:     "TEST_PARSE_CSV_2",
+			envVal:     strPtr(""),
+			defaultVal: "/health,/metrics",
+			want:       nil,
+		},
+		{
+			name:       "env set to custom value",
+			envKey:     "TEST_PARSE_CSV_3",
+			envVal:     strPtr("/custom,/paths"),
+			defaultVal: "/health,/metrics",
+			want:       []string{"/custom", "/paths"},
+		},
+		{
+			name:       "whitespace trimmed",
+			envKey:     "TEST_PARSE_CSV_4",
+			envVal:     strPtr(" /health , /metrics "),
+			defaultVal: "",
+			want:       []string{"/health", "/metrics"},
+		},
+		{
+			name:       "empty default with env not set",
+			envKey:     "TEST_PARSE_CSV_5",
+			envVal:     nil,
+			defaultVal: "",
+			want:       nil,
+		},
+		{
+			name:       "trailing comma ignored",
+			envKey:     "TEST_PARSE_CSV_6",
+			envVal:     strPtr("/health,,/metrics,"),
+			defaultVal: "",
+			want:       []string{"/health", "/metrics"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			os.Unsetenv(tt.envKey)
+			if tt.envVal != nil {
+				os.Setenv(tt.envKey, *tt.envVal)
+				defer os.Unsetenv(tt.envKey)
+			}
+
+			got := parseCommaSeparatedWithDefault(tt.envKey, tt.defaultVal)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("parseCommaSeparatedWithDefault(%q) = %v, want %v", tt.envKey, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestLoadExcludedPathsDefaults(t *testing.T) {
+	// Ensure env vars are not set so defaults apply
+	os.Unsetenv("LAST9_EXCLUDED_PATHS")
+	os.Unsetenv("LAST9_EXCLUDED_PATH_PREFIXES")
+	os.Unsetenv("LAST9_EXCLUDED_PATH_PATTERNS")
+
+	cfg := Load()
+
+	expectedPaths := []string{"/health", "/healthz", "/metrics", "/ready", "/live", "/ping"}
+	if !reflect.DeepEqual(cfg.ExcludedPaths, expectedPaths) {
+		t.Errorf("ExcludedPaths = %v, want %v", cfg.ExcludedPaths, expectedPaths)
+	}
+
+	if cfg.ExcludedPathPrefixes != nil {
+		t.Errorf("ExcludedPathPrefixes = %v, want nil", cfg.ExcludedPathPrefixes)
+	}
+
+	expectedPatterns := []string{"/*/health", "/*/healthz", "/*/metrics", "/*/ready", "/*/live", "/*/ping"}
+	if !reflect.DeepEqual(cfg.ExcludedPathPatterns, expectedPatterns) {
+		t.Errorf("ExcludedPathPatterns = %v, want %v", cfg.ExcludedPathPatterns, expectedPatterns)
+	}
+}
+
+func TestLoadExcludedPathsOptOut(t *testing.T) {
+	// Set env vars to empty to opt out
+	os.Setenv("LAST9_EXCLUDED_PATHS", "")
+	os.Setenv("LAST9_EXCLUDED_PATH_PATTERNS", "")
+	defer os.Unsetenv("LAST9_EXCLUDED_PATHS")
+	defer os.Unsetenv("LAST9_EXCLUDED_PATH_PATTERNS")
+
+	cfg := Load()
+
+	if cfg.ExcludedPaths != nil {
+		t.Errorf("ExcludedPaths = %v, want nil (opted out)", cfg.ExcludedPaths)
+	}
+	if cfg.ExcludedPathPatterns != nil {
+		t.Errorf("ExcludedPathPatterns = %v, want nil (opted out)", cfg.ExcludedPathPatterns)
+	}
+}
+
+func TestLoadExcludedPathsCustom(t *testing.T) {
+	os.Setenv("LAST9_EXCLUDED_PATHS", "/custom-health")
+	os.Setenv("LAST9_EXCLUDED_PATH_PREFIXES", "/internal/")
+	os.Setenv("LAST9_EXCLUDED_PATH_PATTERNS", "/v*/status")
+	defer os.Unsetenv("LAST9_EXCLUDED_PATHS")
+	defer os.Unsetenv("LAST9_EXCLUDED_PATH_PREFIXES")
+	defer os.Unsetenv("LAST9_EXCLUDED_PATH_PATTERNS")
+
+	cfg := Load()
+
+	if !reflect.DeepEqual(cfg.ExcludedPaths, []string{"/custom-health"}) {
+		t.Errorf("ExcludedPaths = %v, want [/custom-health]", cfg.ExcludedPaths)
+	}
+	if !reflect.DeepEqual(cfg.ExcludedPathPrefixes, []string{"/internal/"}) {
+		t.Errorf("ExcludedPathPrefixes = %v, want [/internal/]", cfg.ExcludedPathPrefixes)
+	}
+	if !reflect.DeepEqual(cfg.ExcludedPathPatterns, []string{"/v*/status"}) {
+		t.Errorf("ExcludedPathPatterns = %v, want [/v*/status]", cfg.ExcludedPathPatterns)
+	}
+}
+
+func strPtr(s string) *string { return &s }