Skip to content

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.go
index 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.AllRepos
services *services.AllServices
bus *eventbus.EventBus
+ otel *otel.Provider
}
func new(conf *config.Config) *app {
diff --git a/backend/app/api/main.go b/backend/app/api/main.go
index 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.go
index 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 Services
r.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.mod
index 1c6eb236..b071a839 100644
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -4,6 +4,7 @@ go 1.25
require (
entgo.io/ent v0.14.5
+ github.com/XSAM/otelsql v0.41.0
github.com/ardanlabs/conf/v3 v3.10.0
github.com/containrrr/shoutrrr v0.8.0
github.com/coreos/go-oidc/v3 v3.17.0
@@ -34,6 +35,14 @@ require (
github.com/yeqown/go-qrcode/writer/standard v1.3.0
github.com/zeebo/blake3 v0.2.4
go.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.0
gocloud.dev v0.44.0
gocloud.dev/pubsub/kafkapubsub v0.44.0
gocloud.dev/pubsub/natspubsub v0.44.0
@@ -42,6 +51,7 @@ require (
golang.org/x/image v0.35.0
golang.org/x/oauth2 v0.34.0
golang.org/x/text v0.33.0
+ google.golang.org/grpc v1.78.0
modernc.org/sqlite v1.44.2
)
@@ -96,6 +106,7 @@ require (
github.com/aws/aws-sdk-go-v2/service/sts v1.39.1 // indirect
github.com/aws/smithy-go v1.23.2 // indirect
github.com/bmatcuk/doublestar v1.3.4 // indirect
+ github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/cncf/xds/go v0.0.0-20251022180443-0feb69152e9f // indirect
github.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 // indirect
github.com/googleapis/gax-go/v2 v2.16.0 // indirect
github.com/gorilla/websocket v1.5.3 // indirect
+ github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.3 // indirect
github.com/hashicorp/go-uuid v1.0.3 // indirect
github.com/hashicorp/hcl/v2 v2.18.1 // indirect
github.com/jcmturner/aescts/v2 v2.0.0 // indirect
@@ -178,12 +190,9 @@ require (
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib/detectors/gcp v1.38.0 // indirect
go.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 // indirect
go.opentelemetry.io/otel/metric v1.39.0 // indirect
- go.opentelemetry.io/otel/sdk v1.39.0 // indirect
go.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 // indirect
go.uber.org/multierr v1.11.0 // indirect
go.yaml.in/yaml/v3 v3.0.4 // indirect
golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
@@ -198,7 +207,6 @@ require (
google.golang.org/genproto v0.0.0-20251202230838-ff82c1b0f217 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20251202230838-ff82c1b0f217 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260114163908-3f89685c29c3 // indirect
- google.golang.org/grpc v1.78.0 // indirect
google.golang.org/protobuf v1.36.11 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
modernc.org/libc v1.67.6 // indirect
diff --git a/backend/go.sum b/backend/go.sum
index 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/TAikspPl3ozPI6iY
go.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+2W
go.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.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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))
+ }
+}