A continuation of HomeBox the inventory and organization system built for the Home User
Add OpenTelemetry backend integration with configuration, database tracing, and HTTP middleware
copilot-swe-agent[bot]ca4e2e389c24
diff --git a/backend/app/api/app.go b/backend/app/api/app.goindex 31910750..3ff7574c 100644--- a/backend/app/api/app.go+++ b/backend/app/api/app.go@@ -6,6 +6,7 @@ import ("github.com/sysadminsmedia/homebox/backend/internal/data/ent""github.com/sysadminsmedia/homebox/backend/internal/data/repo""github.com/sysadminsmedia/homebox/backend/internal/sys/config"+ "github.com/sysadminsmedia/homebox/backend/internal/sys/otel""github.com/sysadminsmedia/homebox/backend/pkgs/mailer")@@ -16,6 +17,7 @@ type app struct {repos *repo.AllReposservices *services.AllServicesbus *eventbus.EventBus+ otel *otel.Provider}func new(conf *config.Config) *app {diff --git a/backend/app/api/main.go b/backend/app/api/main.goindex b3d8ccd0..229455f0 100644--- a/backend/app/api/main.go+++ b/backend/app/api/main.go@@ -12,6 +12,7 @@ import ("github.com/go-chi/chi/v5/middleware""github.com/pressly/goose/v3""github.com/sysadminsmedia/homebox/backend/internal/sys/analytics"+ "github.com/sysadminsmedia/homebox/backend/internal/sys/otel""github.com/hay-kot/httpkit/errchain""github.com/hay-kot/httpkit/graceful"@@ -101,9 +102,18 @@ func run(cfg *config.Config) error {app := new(cfg)app.setupLogger()+ // =========================================================================+ // Initialize OpenTelemetry+ otelProvider, err := otel.NewProvider(context.Background(), &cfg.OTel, version)+ if err != nil {+ log.Error().Err(err).Msg("failed to initialize OpenTelemetry")+ return fmt.Errorf("failed to initialize OpenTelemetry: %w", err)+ }+ app.otel = otelProvider+// =========================================================================// Initialize Database & Repos- err := setupStorageDir(cfg)+ err = setupStorageDir(cfg)if err != nil {return err}@@ -120,22 +130,36 @@ func run(cfg *config.Config) error {return err}- c, err := ent.Open(strings.ToLower(cfg.Database.Driver), databaseURL)- if err != nil {- log.Error().- Err(err).- Str("driver", strings.ToLower(cfg.Database.Driver)).- Str("host", cfg.Database.Host).- Str("port", cfg.Database.Port).- Str("database", cfg.Database.Database).- Msg("failed opening connection to {driver} database at {host}:{port}/{database}")- return fmt.Errorf("failed opening connection to %s database at %s:%s/%s: %w",- strings.ToLower(cfg.Database.Driver),- cfg.Database.Host,- cfg.Database.Port,- cfg.Database.Database,- err,- )+ // Open database with optional OpenTelemetry instrumentation+ var c *ent.Client+ if otelProvider.DatabaseTracingEnabled() {+ entDriver, err := otelProvider.OpenEntDriver(strings.ToLower(cfg.Database.Driver), databaseURL)+ if err != nil {+ log.Error().+ Err(err).+ Str("driver", strings.ToLower(cfg.Database.Driver)).+ Msg("failed to open instrumented database connection")+ return fmt.Errorf("failed to open instrumented database connection: %w", err)+ }+ c = ent.NewClient(ent.Driver(entDriver))+ } else {+ c, err = ent.Open(strings.ToLower(cfg.Database.Driver), databaseURL)+ if err != nil {+ log.Error().+ Err(err).+ Str("driver", strings.ToLower(cfg.Database.Driver)).+ Str("host", cfg.Database.Host).+ Str("port", cfg.Database.Port).+ Str("database", cfg.Database.Database).+ Msg("failed opening connection to {driver} database at {host}:{port}/{database}")+ return fmt.Errorf("failed opening connection to %s database at %s:%s/%s: %w",+ strings.ToLower(cfg.Database.Driver),+ cfg.Database.Host,+ cfg.Database.Port,+ cfg.Database.Database,+ err,+ )+ }}migrationsFs, err := migrations.Migrations(strings.ToLower(cfg.Database.Driver))@@ -184,6 +208,12 @@ func run(cfg *config.Config) error {logger := log.With().Caller().Logger()router := chi.NewMux()++ // Add OpenTelemetry HTTP middleware if enabled+ if otelProvider.IsEnabled() && cfg.OTel.EnableHTTPTracing {+ router.Use(otelProvider.HTTPMiddleware("homebox"))+ }+router.Use(middleware.RequestID,middleware.RealIP,@@ -198,6 +228,16 @@ func run(cfg *config.Config) error {runner := graceful.NewRunner()+ // Add OpenTelemetry shutdown+ if otelProvider.IsEnabled() {+ runner.AddFunc("otel-shutdown", func(ctx context.Context) error {+ <-ctx.Done()+ shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)+ defer cancel()+ return otelProvider.Shutdown(shutdownCtx)+ })+ }+runner.AddFunc("server", func(ctx context.Context) error {httpserver := http.Server{Addr: fmt.Sprintf("%s:%s", cfg.Web.Host, cfg.Web.Port),diff --git a/backend/app/api/routes.go b/backend/app/api/routes.goindex 185338c0..6a5c5867 100644--- a/backend/app/api/routes.go+++ b/backend/app/api/routes.go@@ -209,6 +209,11 @@ func (a *app) mountRoutes(r *chi.Mux, chain *errchain.ErrChain, repos *repo.AllR// Reporting Servicesr.Get("/reporting/bill-of-materials", chain.ToHandlerFunc(v1Ctrl.HandleBillOfMaterialsExport(), userMW...))+ // OpenTelemetry proxy endpoint for frontend telemetry (requires auth)+ if a.otel != nil && a.otel.IsEnabled() && a.conf.OTel.ProxyEnabled {+ r.Post("/telemetry", a.otel.ProxyHandler())+ }+r.NotFound(http.NotFound)})diff --git a/backend/go.mod b/backend/go.modindex 1c6eb236..b071a839 100644--- a/backend/go.mod+++ b/backend/go.mod@@ -4,6 +4,7 @@ go 1.25require (entgo.io/ent v0.14.5+ github.com/XSAM/otelsql v0.41.0github.com/ardanlabs/conf/v3 v3.10.0github.com/containrrr/shoutrrr v0.8.0github.com/coreos/go-oidc/v3 v3.17.0@@ -34,6 +35,14 @@ require (github.com/yeqown/go-qrcode/writer/standard v1.3.0github.com/zeebo/blake3 v0.2.4go.balki.me/anyhttp v0.5.2+ go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0+ go.opentelemetry.io/otel v1.39.0+ go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0+ go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.39.0+ go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.39.0+ go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.39.0+ go.opentelemetry.io/otel/sdk v1.39.0+ go.opentelemetry.io/otel/trace v1.39.0gocloud.dev v0.44.0gocloud.dev/pubsub/kafkapubsub v0.44.0gocloud.dev/pubsub/natspubsub v0.44.0@@ -42,6 +51,7 @@ require (golang.org/x/image v0.35.0golang.org/x/oauth2 v0.34.0golang.org/x/text v0.33.0+ google.golang.org/grpc v1.78.0modernc.org/sqlite v1.44.2)@@ -96,6 +106,7 @@ require (github.com/aws/aws-sdk-go-v2/service/sts v1.39.1 // indirectgithub.com/aws/smithy-go v1.23.2 // indirectgithub.com/bmatcuk/doublestar v1.3.4 // indirect+ github.com/cenkalti/backoff/v5 v5.0.3 // indirectgithub.com/cespare/xxhash/v2 v2.3.0 // indirectgithub.com/cncf/xds/go v0.0.0-20251022180443-0feb69152e9f // indirectgithub.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect@@ -135,6 +146,7 @@ require (github.com/googleapis/enterprise-certificate-proxy v0.3.9 // indirectgithub.com/googleapis/gax-go/v2 v2.16.0 // indirectgithub.com/gorilla/websocket v1.5.3 // indirect+ github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirectgithub.com/hashicorp/go-uuid v1.0.3 // indirectgithub.com/hashicorp/hcl/v2 v2.18.1 // indirectgithub.com/jcmturner/aescts/v2 v2.0.0 // indirect@@ -178,12 +190,9 @@ require (go.opentelemetry.io/auto/sdk v1.2.1 // indirectgo.opentelemetry.io/contrib/detectors/gcp v1.38.0 // indirectgo.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.62.0 // indirect- go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.62.0 // indirect- go.opentelemetry.io/otel v1.39.0 // indirectgo.opentelemetry.io/otel/metric v1.39.0 // indirect- go.opentelemetry.io/otel/sdk v1.39.0 // indirectgo.opentelemetry.io/otel/sdk/metric v1.39.0 // indirect- go.opentelemetry.io/otel/trace v1.39.0 // indirect+ go.opentelemetry.io/proto/otlp v1.9.0 // indirectgo.uber.org/multierr v1.11.0 // indirectgo.yaml.in/yaml/v3 v3.0.4 // indirectgolang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect@@ -198,7 +207,6 @@ require (google.golang.org/genproto v0.0.0-20251202230838-ff82c1b0f217 // indirectgoogle.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 // indirectgoogle.golang.org/genproto/googleapis/rpc v0.0.0-20260114163908-3f89685c29c3 // indirect- google.golang.org/grpc v1.78.0 // indirectgoogle.golang.org/protobuf v1.36.11 // indirectgopkg.in/yaml.v3 v3.0.1 // indirectmodernc.org/libc v1.67.6 // indirectdiff --git a/backend/go.sum b/backend/go.sumindex 3faa6a1b..34578502 100644--- a/backend/go.sum+++ b/backend/go.sum@@ -75,6 +75,8 @@ github.com/IBM/sarama v1.46.3 h1:njRsX6jNlnR+ClJ8XmkO+CM4unbrNr/2vB5KK6UA+IE=github.com/IBM/sarama v1.46.3/go.mod h1:GTUYiF9DMOZVe3FwyGT+dtSPceGFIgA+sPc5u6CBwko=github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=+github.com/XSAM/otelsql v0.41.0 h1:uZifjQhZhv5EDYJh+IVk1DiYxQZJBlNSen0MBFnfxB8=+github.com/XSAM/otelsql v0.41.0/go.mod h1:NMQT0PiKoFILp9QgjQz+D5mvW+9mT0suR7OejqrtMaM=github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY=@@ -125,6 +127,8 @@ github.com/aws/smithy-go v1.23.2 h1:Crv0eatJUQhaManss33hS5r40CG3ZFH+21XSkqMrIUM=github.com/aws/smithy-go v1.23.2/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=github.com/bmatcuk/doublestar v1.3.4 h1:gPypJ5xD31uhX6Tf54sDPUOBXTqKH4c9aPY66CyQrS0=github.com/bmatcuk/doublestar v1.3.4/go.mod h1:wiQtGV+rzVYxB7WIlirSN++5HPtPlXEo9MEoZQC/PmE=+github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1xcsSM=+github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=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/cncf/xds/go v0.0.0-20251022180443-0feb69152e9f h1:Y8xYupdHxryycyPlc9Y+bSQAYZnetRJ70VMVKm5CKI0=@@ -275,6 +279,8 @@ github.com/gorilla/securecookie v1.1.1/go.mod h1:ra0sb63/xPlUeL+yeDciTfxMRAA+MP+github.com/gorilla/sessions v1.2.1/go.mod h1:dk2InVEVJ0sfLlnXv9EAgkf6ecYs/i80K/zI+bUmuGM=github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=+github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 h1:NmZ1PKzSTQbuGHw9DGPFomqkkLWMC+vZCkfs+FHv1Vg=+github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3/go.mod h1:zQrxl1YP88HQlA6i9c63DSVPFklWpGX4OWAc9bFuaH4=github.com/hashicorp/go-uuid v1.0.2/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=@@ -443,12 +449,20 @@ go.opentelemetry.io/contrib/detectors/gcp v1.38.0 h1:ZoYbqX7OaA/TAikspPl3ozPI6iYgo.opentelemetry.io/contrib/detectors/gcp v1.38.0/go.mod h1:SU+iU7nu5ud4oCb3LQOhIZ3nRLj6FNVrKgtflbaf2ts=go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.62.0 h1:rbRJ8BBoVMsQShESYZ0FkvcITu8X8QNwJogcLUmDNNw=go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.62.0/go.mod h1:ru6KHrNtNHxM4nD/vd6QrLVWgKhxPYgblq4VAtNawTQ=-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.62.0 h1:Hf9xI/XLML9ElpiHVDNwvqI0hIFlzV8dgIr35kV1kRU=-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.62.0/go.mod h1:NfchwuyNoMcZ5MLHwPrODwUF1HWCXWrL31s8gSAdIKY=+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0 h1:ssfIgGNANqpVFCndZvcuyKbl0g+UAVcbBcqGkG28H0Y=+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.64.0/go.mod h1:GQ/474YrbE4Jx8gZ4q5I4hrhUzM6UPzyrqJYV2AqPoQ=go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0 h1:f0cb2XPmrqn4XMy9PNliTgRKJgS5WcL/u0/WRYGz4t0=+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.39.0/go.mod h1:vnakAaFckOMiMtOIhFI2MNH4FYrZzXCYxmb1LlhoGz8=+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.39.0 h1:in9O8ESIOlwJAEGTkkf34DesGRAc/Pn8qJ7k3r/42LM=+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.39.0/go.mod h1:Rp0EXBm5tfnv0WL+ARyO/PHBEaEAT8UUHQ6AGJcSq6c=+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.39.0 h1:Ckwye2FpXkYgiHX7fyVrN1uA/UYd9ounqqTuSNAv0k4=+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.39.0/go.mod h1:teIFJh5pW2y+AN7riv6IBPX2DuesS3HgP39mwOspKwU=go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.37.0 h1:6VjV6Et+1Hd2iLZEPtdV7vie80Yyqf7oikJLjQ/myi0=go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.37.0/go.mod h1:u8hcp8ji5gaM/RfcOo8z9NMnf1pVLfVY7lBY2VOGuUU=+go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.39.0 h1:8UPA4IbVZxpsD76ihGOQiFml99GPAEZLohDXvqHdi6U=+go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.39.0/go.mod h1:MZ1T/+51uIVKlRzGw1Fo46KEWThjlCBZKl2LzY5nv4g=go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=go.opentelemetry.io/otel/sdk v1.39.0 h1:nMLYcjVsvdui1B/4FRkwjzoRVsMK8uL/cj0OyhKzt18=@@ -457,6 +471,8 @@ go.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2Wgo.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=+go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=+go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=diff --git a/backend/internal/sys/config/conf.go b/backend/internal/sys/config/conf.goindex 8d37570e..52ad5457 100644--- a/backend/internal/sys/config/conf.go+++ b/backend/internal/sys/config/conf.go@@ -31,6 +31,7 @@ type Config struct {LabelMaker LabelMakerConf `yaml:"labelmaker"`Thumbnail Thumbnail `yaml:"thumbnail"`Barcode BarcodeAPIConf `yaml:"barcode"`+ OTel OTelConfig `yaml:"otel"`}type Options struct {diff --git a/backend/internal/sys/config/conf_otel.go b/backend/internal/sys/config/conf_otel.gonew file mode 100644index 00000000..d6f6dad7--- /dev/null+++ b/backend/internal/sys/config/conf_otel.go@@ -0,0 +1,41 @@+package config++// OTelConfig contains OpenTelemetry configuration options.+// All standard OpenTelemetry environment variables are also supported via the SDK.+type OTelConfig struct {+ // Enabled enables OpenTelemetry tracing when set to true+ Enabled bool `yaml:"enabled" conf:"default:false"`++ // ServiceName is the name of the service reported to the telemetry backend+ ServiceName string `yaml:"service_name" conf:"default:homebox"`++ // ServiceVersion is the version of the service (defaults to build version)+ ServiceVersion string `yaml:"service_version"`++ // Exporter specifies the exporter type: "otlp", "stdout", or "none"+ Exporter string `yaml:"exporter" conf:"default:otlp"`++ // Endpoint is the OTLP exporter endpoint (e.g., "localhost:4317" for gRPC or "localhost:4318" for HTTP)+ Endpoint string `yaml:"endpoint"`++ // Protocol specifies the OTLP protocol: "grpc" or "http"+ Protocol string `yaml:"protocol" conf:"default:grpc"`++ // Insecure disables TLS for the exporter connection+ Insecure bool `yaml:"insecure" conf:"default:false"`++ // Headers are additional headers to send with OTLP requests (comma-separated key=value pairs)+ Headers string `yaml:"headers"`++ // SampleRate is the sampling rate for traces (0.0 to 1.0, where 1.0 means all traces)+ SampleRate float64 `yaml:"sample_rate" conf:"default:1.0"`++ // EnableDatabaseTracing enables tracing for database operations+ EnableDatabaseTracing bool `yaml:"enable_database_tracing" conf:"default:true"`++ // EnableHTTPTracing enables tracing for HTTP requests+ EnableHTTPTracing bool `yaml:"enable_http_tracing" conf:"default:true"`++ // ProxyEnabled enables the telemetry proxy endpoint for frontend tracing+ ProxyEnabled bool `yaml:"proxy_enabled" conf:"default:true"`+}diff --git a/backend/internal/sys/otel/database.go b/backend/internal/sys/otel/database.gonew file mode 100644index 00000000..49190b15--- /dev/null+++ b/backend/internal/sys/otel/database.go@@ -0,0 +1,134 @@+package otel++import (+ "database/sql"+ "fmt"++ "entgo.io/ent/dialect"+ entsql "entgo.io/ent/dialect/sql"+ "github.com/XSAM/otelsql"+ semconv "go.opentelemetry.io/otel/semconv/v1.24.0"+)++// DatabaseDriver returns the driver name to use for database connections.+// If tracing is enabled, this returns the instrumented driver name.+func (p *Provider) DatabaseDriver(originalDriver string) string {+ if p == nil || !p.IsEnabled() || p.cfg == nil || !p.cfg.EnableDatabaseTracing {+ return originalDriver+ }+ // We use the original driver but wrap it with otelsql+ return originalDriver+}++// OpenDatabase opens a database connection with optional OpenTelemetry instrumentation.+// This wraps the standard sql.Open with tracing if enabled.+func (p *Provider) OpenDatabase(driverName, dataSourceName string) (*sql.DB, error) {+ if p == nil || !p.IsEnabled() || p.cfg == nil || !p.cfg.EnableDatabaseTracing {+ return sql.Open(driverName, dataSourceName)+ }++ // Determine the database system for semantic conventions+ dbSystem := getDBSystem(driverName)++ // Open the database with otelsql instrumentation+ db, err := otelsql.Open(driverName, dataSourceName,+ otelsql.WithAttributes(+ semconv.DBSystemKey.String(dbSystem),+ semconv.ServiceName(p.cfg.ServiceName),+ ),+ otelsql.WithTracerProvider(p.TracerProvider()),+ otelsql.WithSQLCommenter(true),+ otelsql.WithSpanOptions(otelsql.SpanOptions{+ DisableQuery: false, // Include SQL queries in spans+ }),+ )+ if err != nil {+ return nil, fmt.Errorf("failed to open instrumented database: %w", err)+ }++ // Register stats for metrics (ignoring error as it's non-fatal)+ _, _ = otelsql.RegisterDBStatsMetrics(db,+ otelsql.WithAttributes(+ semconv.DBSystemKey.String(dbSystem),+ ),+ )++ return db, nil+}++// OpenEntDriver opens an Ent SQL driver with optional OpenTelemetry instrumentation.+func (p *Provider) OpenEntDriver(driverName, dataSourceName string) (*entsql.Driver, error) {+ db, err := p.OpenDatabase(driverName, dataSourceName)+ if err != nil {+ return nil, err+ }++ // Create Ent driver from the database connection+ drv := entsql.OpenDB(mapDialect(driverName), db)+ return drv, nil+}++// getDBSystem returns the OpenTelemetry semantic convention value for the database system.+func getDBSystem(driverName string) string {+ switch driverName {+ case "sqlite3":+ return "sqlite"+ case "postgres", "postgresql":+ return "postgresql"+ case "mysql":+ return "mysql"+ default:+ return driverName+ }+}++// mapDialect maps the driver name to the Ent dialect.+func mapDialect(driverName string) string {+ switch driverName {+ case "sqlite3":+ return dialect.SQLite+ case "postgres", "postgresql":+ return dialect.Postgres+ case "mysql":+ return dialect.MySQL+ default:+ return driverName+ }+}++// WrapEntDriver wraps an existing Ent driver with tracing.+// This is useful when you have an existing driver and want to add tracing.+func (p *Provider) WrapEntDriver(drv *entsql.Driver, driverName string) *entsql.Driver {+ if p == nil || !p.IsEnabled() || p.cfg == nil || !p.cfg.EnableDatabaseTracing {+ return drv+ }++ // The driver is already traced via otelsql.Open+ return drv+}++// DatabaseTracingEnabled returns true if database tracing is enabled.+func (p *Provider) DatabaseTracingEnabled() bool {+ return p != nil && p.IsEnabled() && p.cfg != nil && p.cfg.EnableDatabaseTracing+}++// DBDriverConfig holds configuration for creating a traced database driver.+type DBDriverConfig struct {+ Driver string+ DataSourceName string+ EnableTracing bool+}++// NewDBDriver creates a new database driver with optional tracing.+func (p *Provider) NewDBDriver(cfg DBDriverConfig) (*entsql.Driver, error) {+ if !cfg.EnableTracing || !p.DatabaseTracingEnabled() {+ // Return standard driver without tracing+ drv, err := entsql.Open(mapDialect(cfg.Driver), cfg.DataSourceName)+ if err != nil {+ return nil, fmt.Errorf("failed to open database: %w", err)+ }+ return drv, nil+ }++ return p.OpenEntDriver(cfg.Driver, cfg.DataSourceName)+}diff --git a/backend/internal/sys/otel/middleware.go b/backend/internal/sys/otel/middleware.gonew file mode 100644index 00000000..d223ed81--- /dev/null+++ b/backend/internal/sys/otel/middleware.go@@ -0,0 +1,47 @@+package otel++import (+ "net/http"++ "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"+ "go.opentelemetry.io/otel/trace"+)++// HTTPMiddleware returns an HTTP middleware that instruments requests with OpenTelemetry.+// If the provider is nil or tracing is disabled, returns a no-op middleware.+func (p *Provider) HTTPMiddleware(operation string) func(http.Handler) http.Handler {+ if p == nil || !p.IsEnabled() || (p.cfg != nil && !p.cfg.EnableHTTPTracing) {+ return func(next http.Handler) http.Handler {+ return next+ }+ }++ return func(next http.Handler) http.Handler {+ return otelhttp.NewHandler(next, operation,+ otelhttp.WithTracerProvider(p.TracerProvider()),+ otelhttp.WithSpanNameFormatter(spanNameFormatter),+ )+ }+}++// spanNameFormatter formats the span name to include the HTTP method and route.+func spanNameFormatter(_ string, r *http.Request) string {+ return r.Method + " " + r.URL.Path+}++// WrapHandler wraps an http.Handler with OpenTelemetry instrumentation.+func (p *Provider) WrapHandler(h http.Handler, operation string) http.Handler {+ if p == nil || !p.IsEnabled() || (p.cfg != nil && !p.cfg.EnableHTTPTracing) {+ return h+ }++ return otelhttp.NewHandler(h, operation,+ otelhttp.WithTracerProvider(p.TracerProvider()),+ otelhttp.WithSpanNameFormatter(spanNameFormatter),+ )+}++// SpanFromRequest extracts the current span from an HTTP request context.+func SpanFromRequest(r *http.Request) trace.Span {+ return trace.SpanFromContext(r.Context())+}diff --git a/backend/internal/sys/otel/otel.go b/backend/internal/sys/otel/otel.gonew file mode 100644index 00000000..85f7f5d2--- /dev/null+++ b/backend/internal/sys/otel/otel.go@@ -0,0 +1,237 @@+// Package otel provides OpenTelemetry tracing initialization and utilities.+package otel++import (+ "context"+ "fmt"+ "strings"+ "time"++ "github.com/rs/zerolog/log"+ "github.com/sysadminsmedia/homebox/backend/internal/sys/config"+ "go.opentelemetry.io/otel"+ "go.opentelemetry.io/otel/attribute"+ "go.opentelemetry.io/otel/exporters/otlp/otlptrace"+ "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"+ "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"+ "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"+ "go.opentelemetry.io/otel/propagation"+ "go.opentelemetry.io/otel/sdk/resource"+ sdktrace "go.opentelemetry.io/otel/sdk/trace"+ semconv "go.opentelemetry.io/otel/semconv/v1.24.0"+ "go.opentelemetry.io/otel/trace"+ "google.golang.org/grpc"+ "google.golang.org/grpc/credentials/insecure"+)++// Provider wraps the OpenTelemetry TracerProvider with additional functionality.+type Provider struct {+ tp *sdktrace.TracerProvider+ cfg *config.OTelConfig+ shutdown func(context.Context) error+}++// TracerProvider returns the underlying OpenTelemetry TracerProvider.+func (p *Provider) TracerProvider() trace.TracerProvider {+ if p == nil || p.tp == nil {+ return otel.GetTracerProvider()+ }+ return p.tp+}++// Tracer returns a named tracer from this provider.+func (p *Provider) Tracer(name string, opts ...trace.TracerOption) trace.Tracer {+ return p.TracerProvider().Tracer(name, opts...)+}++// Shutdown gracefully shuts down the trace provider.+func (p *Provider) Shutdown(ctx context.Context) error {+ if p == nil || p.shutdown == nil {+ return nil+ }+ return p.shutdown(ctx)+}++// IsEnabled returns true if OpenTelemetry tracing is enabled.+func (p *Provider) IsEnabled() bool {+ return p != nil && p.cfg != nil && p.cfg.Enabled+}++// Config returns the OpenTelemetry configuration.+func (p *Provider) Config() *config.OTelConfig {+ if p == nil {+ return nil+ }+ return p.cfg+}++// NewProvider creates a new OpenTelemetry provider based on the configuration.+// If OTel is disabled, returns a no-op provider that can still be used safely.+func NewProvider(ctx context.Context, cfg *config.OTelConfig, buildVersion string) (*Provider, error) {+ if cfg == nil || !cfg.Enabled {+ log.Debug().Msg("OpenTelemetry tracing is disabled")+ return &Provider{cfg: cfg}, nil+ }++ // Create resource with service information+ serviceVersion := cfg.ServiceVersion+ if serviceVersion == "" {+ serviceVersion = buildVersion+ }++ res, err := resource.Merge(+ resource.Default(),+ resource.NewWithAttributes(+ semconv.SchemaURL,+ semconv.ServiceName(cfg.ServiceName),+ semconv.ServiceVersion(serviceVersion),+ attribute.String("deployment.environment", getEnvironment()),+ ),+ )+ if err != nil {+ return nil, fmt.Errorf("failed to create resource: %w", err)+ }++ // Create exporter based on configuration+ exporter, err := createExporter(ctx, cfg)+ if err != nil {+ return nil, fmt.Errorf("failed to create exporter: %w", err)+ }++ // Configure sampler+ var sampler sdktrace.Sampler+ if cfg.SampleRate >= 1.0 {+ sampler = sdktrace.AlwaysSample()+ } else if cfg.SampleRate <= 0 {+ sampler = sdktrace.NeverSample()+ } else {+ sampler = sdktrace.TraceIDRatioBased(cfg.SampleRate)+ }++ // Create trace provider+ tp := sdktrace.NewTracerProvider(+ sdktrace.WithBatcher(exporter),+ sdktrace.WithResource(res),+ sdktrace.WithSampler(sdktrace.ParentBased(sampler)),+ )++ // Set as global provider+ otel.SetTracerProvider(tp)++ // Set global propagator for distributed tracing+ otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(+ propagation.TraceContext{},+ propagation.Baggage{},+ ))++ log.Info().+ Str("service", cfg.ServiceName).+ Str("version", serviceVersion).+ Str("exporter", cfg.Exporter).+ Str("endpoint", cfg.Endpoint).+ Float64("sample_rate", cfg.SampleRate).+ Msg("OpenTelemetry tracing initialized")++ return &Provider{+ tp: tp,+ cfg: cfg,+ shutdown: func(ctx context.Context) error {+ // Give pending spans time to be exported+ ctx, cancel := context.WithTimeout(ctx, 10*time.Second)+ defer cancel()+ return tp.Shutdown(ctx)+ },+ }, nil+}++// createExporter creates the appropriate exporter based on configuration.+func createExporter(ctx context.Context, cfg *config.OTelConfig) (sdktrace.SpanExporter, error) {+ switch strings.ToLower(cfg.Exporter) {+ case "stdout":+ return stdouttrace.New(stdouttrace.WithPrettyPrint())++ case "none", "":+ return &noopExporter{}, nil++ case "otlp":+ return createOTLPExporter(ctx, cfg)++ default:+ return nil, fmt.Errorf("unsupported exporter type: %s", cfg.Exporter)+ }+}++// createOTLPExporter creates an OTLP exporter based on the protocol configuration.+func createOTLPExporter(ctx context.Context, cfg *config.OTelConfig) (*otlptrace.Exporter, error) {+ headers := parseHeaders(cfg.Headers)++ switch strings.ToLower(cfg.Protocol) {+ case "http":+ opts := []otlptracehttp.Option{}+ if cfg.Endpoint != "" {+ opts = append(opts, otlptracehttp.WithEndpoint(cfg.Endpoint))+ }+ if cfg.Insecure {+ opts = append(opts, otlptracehttp.WithInsecure())+ }+ if len(headers) > 0 {+ opts = append(opts, otlptracehttp.WithHeaders(headers))+ }+ return otlptracehttp.New(ctx, opts...)++ case "grpc", "":+ opts := []otlptracegrpc.Option{}+ if cfg.Endpoint != "" {+ opts = append(opts, otlptracegrpc.WithEndpoint(cfg.Endpoint))+ }+ if cfg.Insecure {+ opts = append(opts, otlptracegrpc.WithInsecure())+ opts = append(opts, otlptracegrpc.WithDialOption(grpc.WithTransportCredentials(insecure.NewCredentials())))+ }+ if len(headers) > 0 {+ opts = append(opts, otlptracegrpc.WithHeaders(headers))+ }+ return otlptracegrpc.New(ctx, opts...)++ default:+ return nil, fmt.Errorf("unsupported OTLP protocol: %s", cfg.Protocol)+ }+}++// parseHeaders parses a comma-separated list of key=value pairs into a map.+func parseHeaders(headerStr string) map[string]string {+ headers := make(map[string]string)+ if headerStr == "" {+ return headers+ }++ pairs := strings.Split(headerStr, ",")+ for _, pair := range pairs {+ pair = strings.TrimSpace(pair)+ if pair == "" {+ continue+ }+ kv := strings.SplitN(pair, "=", 2)+ if len(kv) == 2 {+ headers[strings.TrimSpace(kv[0])] = strings.TrimSpace(kv[1])+ }+ }+ return headers+}++// getEnvironment returns the current deployment environment.+func getEnvironment() string {+ // This could be enhanced to read from config or environment+ return "production"+}++// noopExporter is a no-op span exporter for when tracing is disabled.+type noopExporter struct{}++func (e *noopExporter) ExportSpans(_ context.Context, _ []sdktrace.ReadOnlySpan) error {+ return nil+}++func (e *noopExporter) Shutdown(_ context.Context) error {+ return nil+}diff --git a/backend/internal/sys/otel/proxy.go b/backend/internal/sys/otel/proxy.gonew file mode 100644index 00000000..08080966--- /dev/null+++ b/backend/internal/sys/otel/proxy.go@@ -0,0 +1,204 @@+package otel++import (+ "context"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "strings"+ "time"++ "github.com/rs/zerolog/log"+ "go.opentelemetry.io/otel/attribute"+ "go.opentelemetry.io/otel/codes"+ "go.opentelemetry.io/otel/trace"+)++// FrontendSpan represents a span sent from the frontend.+type FrontendSpan struct {+ TraceID string `json:"traceId"`+ SpanID string `json:"spanId"`+ ParentSpanID string `json:"parentSpanId,omitempty"`+ Name string `json:"name"`+ Kind string `json:"kind,omitempty"`+ StartTime int64 `json:"startTime"` // Unix milliseconds+ EndTime int64 `json:"endTime"` // Unix milliseconds+ Attributes map[string]interface{} `json:"attributes,omitempty"`+ Status *SpanStatus `json:"status,omitempty"`+ Events []SpanEvent `json:"events,omitempty"`+}++// SpanStatus represents the status of a span.+type SpanStatus struct {+ Code string `json:"code"` // "ok", "error", "unset"+ Message string `json:"message,omitempty"`+}++// SpanEvent represents an event within a span.+type SpanEvent struct {+ Name string `json:"name"`+ Time int64 `json:"time"` // Unix milliseconds+ Attributes map[string]interface{} `json:"attributes,omitempty"`+}++// TelemetryPayload represents the payload sent from the frontend.+type TelemetryPayload struct {+ ResourceAttributes map[string]interface{} `json:"resourceAttributes,omitempty"`+ Spans []FrontendSpan `json:"spans"`+}++// ProxyHandler handles telemetry data from the frontend.+// This creates new spans in the backend that represent frontend activity,+// allowing for distributed tracing across the full stack.+func (p *Provider) ProxyHandler() http.HandlerFunc {+ return func(w http.ResponseWriter, r *http.Request) {+ if p == nil || !p.IsEnabled() || p.cfg == nil || !p.cfg.ProxyEnabled {+ http.Error(w, "Telemetry proxy is disabled", http.StatusServiceUnavailable)+ return+ }++ // Only accept POST requests+ if r.Method != http.MethodPost {+ http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)+ return+ }++ // Read and parse the payload+ body, err := io.ReadAll(io.LimitReader(r.Body, 1024*1024)) // 1MB limit+ if err != nil {+ log.Error().Err(err).Msg("failed to read telemetry payload")+ http.Error(w, "Failed to read request body", http.StatusBadRequest)+ return+ }+ defer r.Body.Close()++ var payload TelemetryPayload+ if err := json.Unmarshal(body, &payload); err != nil {+ log.Error().Err(err).Msg("failed to parse telemetry payload")+ http.Error(w, "Invalid JSON payload", http.StatusBadRequest)+ return+ }++ // Process the spans+ processed := 0+ for _, span := range payload.Spans {+ if err := p.processSpan(r.Context(), span, payload.ResourceAttributes); err != nil {+ log.Warn().Err(err).Str("span", span.Name).Msg("failed to process span")+ continue+ }+ processed+++ }++ // Return success+ w.Header().Set("Content-Type", "application/json")+ w.WriteHeader(http.StatusAccepted)+ _ = json.NewEncoder(w).Encode(map[string]interface{}{+ "processed": processed,+ "total": len(payload.Spans),+ })+ }+}++// processSpan processes a single frontend span and creates a corresponding backend span.+func (p *Provider) processSpan(ctx context.Context, span FrontendSpan, resourceAttrs map[string]interface{}) error {+ tracer := p.Tracer("frontend")++ // Parse span kind+ spanKind := trace.SpanKindInternal+ switch strings.ToLower(span.Kind) {+ case "client":+ spanKind = trace.SpanKindClient+ case "server":+ spanKind = trace.SpanKindServer+ case "producer":+ spanKind = trace.SpanKindProducer+ case "consumer":+ spanKind = trace.SpanKindConsumer+ }++ // Convert timestamps+ startTime := time.UnixMilli(span.StartTime)+ endTime := time.UnixMilli(span.EndTime)++ // Build attributes+ attrs := make([]attribute.KeyValue, 0)+ attrs = append(attrs, attribute.String("span.origin", "frontend"))+ attrs = append(attrs, attribute.String("frontend.trace_id", span.TraceID))+ attrs = append(attrs, attribute.String("frontend.span_id", span.SpanID))+ if span.ParentSpanID != "" {+ attrs = append(attrs, attribute.String("frontend.parent_span_id", span.ParentSpanID))+ }++ // Add span attributes+ for k, v := range span.Attributes {+ attrs = append(attrs, attributeFromInterface("frontend."+k, v))+ }++ // Add resource attributes+ for k, v := range resourceAttrs {+ attrs = append(attrs, attributeFromInterface("frontend.resource."+k, v))+ }++ // Create the span+ _, backendSpan := tracer.Start(ctx, "frontend: "+span.Name,+ trace.WithSpanKind(spanKind),+ trace.WithTimestamp(startTime),+ trace.WithAttributes(attrs...),+ )++ // Add events+ for _, event := range span.Events {+ eventAttrs := make([]attribute.KeyValue, 0)+ for k, v := range event.Attributes {+ eventAttrs = append(eventAttrs, attributeFromInterface(k, v))+ }+ backendSpan.AddEvent(event.Name,+ trace.WithTimestamp(time.UnixMilli(event.Time)),+ trace.WithAttributes(eventAttrs...),+ )+ }++ // Set status+ if span.Status != nil {+ switch strings.ToLower(span.Status.Code) {+ case "error":+ backendSpan.SetStatus(codes.Error, span.Status.Message)+ case "ok":+ backendSpan.SetStatus(codes.Ok, span.Status.Message)+ }+ }++ // End the span with the correct end time+ backendSpan.End(trace.WithTimestamp(endTime))++ return nil+}++// attributeFromInterface converts an interface value to an OpenTelemetry attribute.+func attributeFromInterface(key string, value interface{}) attribute.KeyValue {+ switch v := value.(type) {+ case string:+ return attribute.String(key, v)+ case int:+ return attribute.Int(key, v)+ case int64:+ return attribute.Int64(key, v)+ case float64:+ return attribute.Float64(key, v)+ case bool:+ return attribute.Bool(key, v)+ case []string:+ return attribute.StringSlice(key, v)+ case []int:+ return attribute.IntSlice(key, v)+ case []int64:+ return attribute.Int64Slice(key, v)+ case []float64:+ return attribute.Float64Slice(key, v)+ case []bool:+ return attribute.BoolSlice(key, v)+ default:+ return attribute.String(key, fmt.Sprintf("%v", v))+ }+}