fix: various bugs in observability / OTel (#1564)

backend/internal/bootstrap/bootstrap.go

@@ -19,29 +19,18 @@ import (
 )
 
 func Bootstrap(ctx context.Context) error {
-	var (
-		shutdownFns       []servicerunner.Service
-		closeDatabasePool func()
-	)
-	defer func() { //nolint:contextcheck
-		// Invoke all shutdown functions on exit
-		shutdownCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
-		defer cancel()
-		shutdownErr := servicerunner.NewServiceRunner(shutdownFns...).Run(shutdownCtx)
-		if shutdownErr != nil {
-			slog.Error("Error during graceful shutdown", "error", shutdownErr)
-		}
-		// Close the database connection pool only after the shutdown functions have run: some of them (e.g. releasing the application lock) still need to query the database.
-		if closeDatabasePool != nil {
-			closeDatabasePool()
-		}
-	}()
+	// List of services to run
+	services := make([]servicerunner.Service, 0, 3)
+	shutdowns := &shutdownManager{
+		fns: make([]servicerunner.Service, 0, 4),
+	}
 
 	// Initialize the observability stack, including the logger, distributed tracing, and metrics
-	shutdownFns, httpClient, err := initObservability(ctx, common.EnvConfig.MetricsEnabled, common.EnvConfig.TracingEnabled)
+	shutdownFns, httpClient, err := initObservability(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to initialize OpenTelemetry: %w", err)
 	}
+	shutdowns.Add(shutdownFns...)
 
 	slog.InfoContext(ctx, "Pocket ID is starting")
 
@@ -51,7 +40,10 @@ func Bootstrap(ctx context.Context) error {
 		return fmt.Errorf("failed to initialize database: %w", err)
 	}
 	if pg != nil {
-		closeDatabasePool = pg.Close
+		defer func() {
+			// Close the database connection pool only after the shutdown functions have run: some of them (e.g. releasing the application lock) still need to query the database.
+			pg.Close()
+		}()
 	}
 
 	// Init storage
@@ -77,6 +69,7 @@ func Bootstrap(ctx context.Context) error {
 	if err != nil {
 		return fmt.Errorf("failed to initialize services: %w", err)
 	}
+	services = append(services, svc.appLockService.RunRenewal)
 
 	// Acquire the lock from the app lock service
 	waitUntil, err := svc.appLockService.Acquire(ctx, false)
@@ -92,14 +85,13 @@ func Bootstrap(ctx context.Context) error {
 	case <-time.After(time.Until(waitUntil)):
 	}
 
-	shutdownFn := func(shutdownCtx context.Context) error {
+	shutdowns.Add(func(shutdownCtx context.Context) error {
 		sErr := svc.appLockService.Release(shutdownCtx)
 		if sErr != nil {
 			return fmt.Errorf("failed to release application lock: %w", sErr)
 		}
 		return nil
-	}
-	shutdownFns = append(shutdownFns, shutdownFn)
+	})
 
 	// Init the actors
 	actorsOpts := NewActorsOpts{
@@ -121,11 +113,15 @@ func Bootstrap(ctx context.Context) error {
 	if err != nil {
 		return fmt.Errorf("failed to initialize actors: %w", err)
 	}
+	services = append(services, actors.Run)
 
-	// Register scheduled jobs
-	err = registerScheduledJobs(ctx, db, svc, scheduler)
-	if err != nil {
-		return fmt.Errorf("failed to register scheduled jobs: %w", err)
+	// Register scheduled jobs, only in non-test mode
+	if common.EnvConfig.AppEnv != "test" {
+		err = registerScheduledJobs(ctx, db, svc, scheduler)
+		if err != nil {
+			return fmt.Errorf("failed to register scheduled jobs: %w", err)
+		}
+		services = append(services, scheduler.Run)
 	}
 
 	// Init the router
@@ -135,24 +131,18 @@ func Bootstrap(ctx context.Context) error {
 	if err != nil {
 		return fmt.Errorf("failed to initialize router: %w", err)
 	}
+	services = append(services, router)
 
 	// Run all background services
 	// This call blocks until the context is canceled
-	services := []servicerunner.Service{
-		svc.appLockService.RunRenewal,
-		actors.Run,
-		router,
-	}
-
-	if common.EnvConfig.AppEnv != "test" {
-		services = append(services, scheduler.Run)
-	}
-
 	err = servicerunner.NewServiceRunner(services...).Run(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to run services: %w", err)
 	}
 
+	// Run all shutdown functions
+	shutdowns.Run(ctx)
+
 	return nil
 }
 
@@ -183,3 +173,30 @@ func InitStorage(ctx context.Context, db *gorm.DB) (fileStorage storage.FileStor
 
 	return fileStorage, nil
 }
+
+type shutdownManager struct {
+	fns []servicerunner.Service
+}
+
+func (s *shutdownManager) Add(fns ...servicerunner.Service) {
+	for _, fn := range fns {
+		if fn == nil {
+			continue
+		}
+
+		s.fns = append(s.fns, fn)
+	}
+}
+
+func (s *shutdownManager) Run(ctx context.Context) {
+	// Cleanup functions are one-shot and must each run to completion independently, so we set WaitAll to true
+	sr := servicerunner.NewServiceRunner(s.fns...)
+	sr.WaitAll = true
+
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+	defer shutdownCancel()
+	err := sr.Run(shutdownCtx)
+	if err != nil {
+		slog.ErrorContext(ctx, "Error shutting down services", slog.Any("error", err))
+	}
+}

backend/internal/bootstrap/db_bootstrap.go

@@ -6,13 +6,11 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
-	"net/url"
-	"os"
 	"path/filepath"
-	"strings"
 	"time"
 
 	_ "github.com/golang-migrate/migrate/v4/source/github"
+	sqlitekit "github.com/italypaleale/go-sql-utils/sqlite"
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/jackc/pgx/v5/stdlib"
 	"github.com/libtnb/sqlite"
@@ -20,6 +18,7 @@ import (
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
 	gormLogger "gorm.io/gorm/logger"
+	tracingGorm "gorm.io/plugin/opentelemetry/tracing"
 
 	"github.com/pocket-id/pocket-id/backend/internal/common"
 	"github.com/pocket-id/pocket-id/backend/internal/utils"
@@ -59,19 +58,19 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
 
 		sqliteutil.RegisterSqliteFunctions()
 
-		connString, dbPath, isMemoryDB, err := parseSqliteConnectionString(common.EnvConfig.DbConnectionString)
+		connString, dbPath, isMemoryDB, err := sqlitekit.ParseConnectionString(common.EnvConfig.DbConnectionString, slog.Default())
 		if err != nil {
 			return nil, nil, err
 		}
 
 		if !isMemoryDB {
-			err = ensureSqliteDatabaseDir(dbPath)
+			err = sqlitekit.EnsureDatabaseDir(dbPath)
 			if err != nil {
 				return nil, nil, err
 			}
 
 			var sqliteNetworkFilesystem bool
-			sqliteNetworkFilesystem, err = utils.IsNetworkedFileSystem(filepath.Dir(dbPath))
+			sqliteNetworkFilesystem, err = sqlitekit.IsNetworkedFileSystem(filepath.Dir(dbPath))
 			if err != nil {
 				// Log the error only
 				slog.Warn("Failed to detect filesystem type for the SQLite database directory", slog.String("path", filepath.Dir(dbPath)), slog.Any("error", err))
@@ -81,7 +80,7 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
 		}
 
 		// Before we connect, also make sure that there's a temporary folder for SQLite to write its data
-		err = ensureSqliteTempDir(filepath.Dir(dbPath))
+		err = sqlitekit.EnsureTempDir(filepath.Dir(dbPath), slog.Default())
 		if err != nil {
 			return nil, nil, err
 		}
@@ -132,6 +131,12 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
 		if err == nil {
 			slog.Info("Connected to database", slog.String("provider", string(common.EnvConfig.DbProvider)))
 
+			// Configure tracing and metrics
+			err = db.Use(tracingGorm.NewPlugin())
+			if err != nil {
+				return nil, nil, fmt.Errorf("failed to configure tracing for DB: %w", err)
+			}
+
 			// Invoke the onConnFn callback if any
 			if onConnFn != nil {
 				conn, err := db.DB()
@@ -162,249 +167,6 @@ func ConnectDatabase(ctx context.Context) (db *gorm.DB, pg *pgxpool.Pool, err er
 	return nil, nil, err
 }
 
-func parseSqliteConnectionString(connString string) (parsedConnString string, dbPath string, isMemoryDB bool, err error) {
-	if !strings.HasPrefix(connString, "file:") {
-		connString = "file:" + connString
-	}
-
-	// Check if we're using an in-memory database
-	isMemoryDB = isSqliteInMemory(connString)
-
-	// Parse the connection string
-	connStringUrl, err := url.Parse(connString)
-	if err != nil {
-		return "", "", false, fmt.Errorf("failed to parse SQLite connection string: %w", err)
-	}
-
-	// Convert options for the old SQLite driver to the new one
-	convertSqlitePragmaArgs(connStringUrl)
-
-	// Add the default and required params
-	err = addSqliteDefaultParameters(connStringUrl, isMemoryDB)
-	if err != nil {
-		return "", "", false, fmt.Errorf("invalid SQLite connection string: %w", err)
-	}
-
-	// Get the absolute path to the database
-	// Here, we know for a fact that the ? is present
-	parsedConnString = connStringUrl.String()
-	idx := strings.IndexRune(parsedConnString, '?')
-	dbPath, err = filepath.Abs(parsedConnString[len("file:"):idx])
-	if err != nil {
-		return "", "", false, fmt.Errorf("failed to determine absolute path to the database: %w", err)
-	}
-
-	return parsedConnString, dbPath, isMemoryDB, nil
-}
-
-// The official C implementation of SQLite allows some additional properties in the connection string
-// that are not supported in the in the modernc.org/sqlite driver, and which must be passed as PRAGMA args instead.
-// To ensure that people can use similar args as in the C driver, which was also used by Pocket ID
-// previously (via github.com/mattn/go-sqlite3), we are converting some options.
-// Note this function updates connStringUrl.
-func convertSqlitePragmaArgs(connStringUrl *url.URL) {
-	// Reference: https://github.com/mattn/go-sqlite3?tab=readme-ov-file#connection-string
-	// This only includes a subset of options, excluding those that are not relevant to us
-	qs := make(url.Values, len(connStringUrl.Query()))
-	for k, v := range connStringUrl.Query() {
-		switch strings.ToLower(k) {
-		case "_auto_vacuum", "_vacuum":
-			qs.Add("_pragma", "auto_vacuum("+v[0]+")")
-		case "_busy_timeout", "_timeout":
-			qs.Add("_pragma", "busy_timeout("+v[0]+")")
-		case "_case_sensitive_like", "_cslike":
-			qs.Add("_pragma", "case_sensitive_like("+v[0]+")")
-		case "_foreign_keys", "_fk":
-			qs.Add("_pragma", "foreign_keys("+v[0]+")")
-		case "_locking_mode", "_locking":
-			qs.Add("_pragma", "locking_mode("+v[0]+")")
-		case "_secure_delete":
-			qs.Add("_pragma", "secure_delete("+v[0]+")")
-		case "_synchronous", "_sync":
-			qs.Add("_pragma", "synchronous("+v[0]+")")
-		default:
-			// Pass other query-string args as-is
-			qs[k] = v
-		}
-	}
-
-	// Update the connStringUrl object
-	connStringUrl.RawQuery = qs.Encode()
-}
-
-// Adds the default (and some required) parameters to the SQLite connection string.
-// Note this function updates connStringUrl.
-func addSqliteDefaultParameters(connStringUrl *url.URL, isMemoryDB bool) error {
-	// This function include code adapted from https://github.com/dapr/components-contrib/blob/v1.14.6/
-	// Copyright (C) 2023 The Dapr Authors
-	// License: Apache2
-	const defaultBusyTimeout = 2500 * time.Millisecond
-
-	// Get the "query string" from the connection string if present
-	qs := connStringUrl.Query()
-	if len(qs) == 0 {
-		qs = make(url.Values, 2)
-	}
-
-	// Check if the database is read-only or immutable
-	isReadOnly := false
-	if len(qs["mode"]) > 0 {
-		// Keep the first value only
-		qs["mode"] = []string{
-			strings.ToLower(qs["mode"][0]),
-		}
-		if qs["mode"][0] == "ro" {
-			isReadOnly = true
-		}
-	}
-	if len(qs["immutable"]) > 0 {
-		// Keep the first value only
-		qs["immutable"] = []string{
-			strings.ToLower(qs["immutable"][0]),
-		}
-		if qs["immutable"][0] == "1" {
-			isReadOnly = true
-		}
-	}
-
-	// We do not want to override a _txlock if set, but we'll show a warning if it's not "immediate"
-	if len(qs["_txlock"]) > 0 {
-		// Keep the first value only
-		qs["_txlock"] = []string{
-			strings.ToLower(qs["_txlock"][0]),
-		}
-		if qs["_txlock"][0] != "immediate" {
-			slog.Warn("SQLite connection is being created with a _txlock different from the recommended value 'immediate'")
-		}
-	} else {
-		qs["_txlock"] = []string{"immediate"}
-	}
-
-	// Add pragma values
-	var hasBusyTimeout, hasJournalMode bool
-	if len(qs["_pragma"]) == 0 {
-		qs["_pragma"] = make([]string, 0, 3)
-	} else {
-		for _, p := range qs["_pragma"] {
-			p = strings.ToLower(p)
-			switch {
-			case strings.HasPrefix(p, "busy_timeout"):
-				hasBusyTimeout = true
-			case strings.HasPrefix(p, "journal_mode"):
-				hasJournalMode = true
-			case strings.HasPrefix(p, "foreign_keys"):
-				return errors.New("found forbidden option '_pragma=foreign_keys' in the connection string")
-			}
-		}
-	}
-	if !hasBusyTimeout {
-		qs["_pragma"] = append(qs["_pragma"], fmt.Sprintf("busy_timeout(%d)", defaultBusyTimeout.Milliseconds()))
-	}
-	if !hasJournalMode {
-		switch {
-		case isMemoryDB:
-			// For in-memory databases, set the journal to MEMORY, the only allowed option besides OFF (which would make transactions ineffective)
-			qs["_pragma"] = append(qs["_pragma"], "journal_mode(MEMORY)")
-		case isReadOnly:
-			// Set the journaling mode to "DELETE" (the default) if the database is read-only
-			qs["_pragma"] = append(qs["_pragma"], "journal_mode(DELETE)")
-		default:
-			// Enable WAL
-			qs["_pragma"] = append(qs["_pragma"], "journal_mode(WAL)")
-		}
-	}
-
-	// Forcefully enable foreign keys
-	qs["_pragma"] = append(qs["_pragma"], "foreign_keys(1)")
-
-	// Update the connStringUrl object
-	connStringUrl.RawQuery = qs.Encode()
-
-	return nil
-}
-
-// isSqliteInMemory returns true if the connection string is for an in-memory database.
-func isSqliteInMemory(connString string) bool {
-	lc := strings.ToLower(connString)
-
-	// First way to define an in-memory database is to use ":memory:" or "file::memory:" as connection string
-	if strings.HasPrefix(lc, ":memory:") || strings.HasPrefix(lc, "file::memory:") {
-		return true
-	}
-
-	// Another way is to pass "mode=memory" in the "query string"
-	idx := strings.IndexRune(lc, '?')
-	if idx < 0 {
-		return false
-	}
-	qs, _ := url.ParseQuery(lc[(idx + 1):])
-
-	return len(qs["mode"]) > 0 && qs["mode"][0] == "memory"
-}
-
-// ensureSqliteDatabaseDir creates the parent directory for the SQLite database file if it doesn't exist yet
-func ensureSqliteDatabaseDir(dbPath string) error {
-	dir := filepath.Dir(dbPath)
-
-	info, err := os.Stat(dir)
-	switch {
-	case err == nil:
-		if !info.IsDir() {
-			return fmt.Errorf("SQLite database directory '%s' is not a directory", dir)
-		}
-		return nil
-	case os.IsNotExist(err):
-		if err := os.MkdirAll(dir, 0700); err != nil {
-			return fmt.Errorf("failed to create SQLite database directory '%s': %w", dir, err)
-		}
-		return nil
-	default:
-		return fmt.Errorf("failed to check SQLite database directory '%s': %w", dir, err)
-	}
-}
-
-// ensureSqliteTempDir ensures that SQLite has a directory where it can write temporary files if needed
-// The default directory may not be writable when using a container with a read-only root file system
-// See: https://www.sqlite.org/tempfiles.html
-func ensureSqliteTempDir(dbPath string) error {
-	// Per docs, SQLite tries these folders in order (excluding those that aren't applicable to us):
-	//
-	// - The SQLITE_TMPDIR environment variable
-	// - The TMPDIR environment variable
-	// - /var/tmp
-	// - /usr/tmp
-	// - /tmp
-	//
-	// Source: https://www.sqlite.org/tempfiles.html#temporary_file_storage_locations
-	//
-	// First, let's check if SQLITE_TMPDIR or TMPDIR are set, in which case we trust the user has taken care of the problem already
-	if os.Getenv("SQLITE_TMPDIR") != "" || os.Getenv("TMPDIR") != "" {
-		return nil
-	}
-
-	// Now, let's check if /var/tmp, /usr/tmp, or /tmp exist and are writable
-	for _, dir := range []string{"/var/tmp", "/usr/tmp", "/tmp"} {
-		ok, err := utils.IsWritableDir(dir)
-		if err != nil {
-			return fmt.Errorf("failed to check if %s is writable: %w", dir, err)
-		}
-		if ok {
-			// We found a folder that's writable
-			return nil
-		}
-	}
-
-	// If we're here, there's no temporary directory that's writable (not unusual for containers with a read-only root file system), so we set SQLITE_TMPDIR to the folder where the SQLite database is set
-	err := os.Setenv("SQLITE_TMPDIR", dbPath)
-	if err != nil {
-		return fmt.Errorf("failed to set SQLITE_TMPDIR environmental variable: %w", err)
-	}
-
-	slog.Debug("Set SQLITE_TMPDIR to the database directory", "path", dbPath)
-
-	return nil
-}
-
 func getGormLogger() gormLogger.Interface {
 	loggerOpts := make([]slogGorm.Option, 0, 5)
 	loggerOpts = append(loggerOpts,

backend/internal/bootstrap/db_bootstrap_test.go

@@ -1,349 +0,0 @@
-package bootstrap
-
-import (
-	"net/url"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestIsSqliteInMemory(t *testing.T) {
-	tests := []struct {
-		name     string
-		connStr  string
-		expected bool
-	}{
-		{
-			name:     "memory database with :memory:",
-			connStr:  ":memory:",
-			expected: true,
-		},
-		{
-			name:     "memory database with file::memory:",
-			connStr:  "file::memory:",
-			expected: true,
-		},
-		{
-			name:     "memory database with :MEMORY: (uppercase)",
-			connStr:  ":MEMORY:",
-			expected: true,
-		},
-		{
-			name:     "memory database with FILE::MEMORY: (uppercase)",
-			connStr:  "FILE::MEMORY:",
-			expected: true,
-		},
-		{
-			name:     "memory database with mixed case",
-			connStr:  ":Memory:",
-			expected: true,
-		},
-		{
-			name:     "has mode=memory",
-			connStr:  "file:data?mode=memory",
-			expected: true,
-		},
-		{
-			name:     "file database",
-			connStr:  "data.db",
-			expected: false,
-		},
-		{
-			name:     "file database with path",
-			connStr:  "/path/to/data.db",
-			expected: false,
-		},
-		{
-			name:     "file database with file: prefix",
-			connStr:  "file:data.db",
-			expected: false,
-		},
-		{
-			name:     "empty string",
-			connStr:  "",
-			expected: false,
-		},
-		{
-			name:     "string containing memory but not at start",
-			connStr:  "data:memory:.db",
-			expected: false,
-		},
-		{
-			name:     "has mode=ro",
-			connStr:  "file:data?mode=ro",
-			expected: false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := isSqliteInMemory(tt.connStr)
-			assert.Equal(t, tt.expected, result)
-		})
-	}
-}
-
-func TestEnsureSqliteDatabaseDir(t *testing.T) {
-	t.Run("creates missing directory", func(t *testing.T) {
-		tempDir := t.TempDir()
-		dbPath := filepath.Join(tempDir, "nested", "pocket-id.db")
-
-		err := ensureSqliteDatabaseDir(dbPath)
-		require.NoError(t, err)
-
-		info, err := os.Stat(filepath.Dir(dbPath))
-		require.NoError(t, err)
-		assert.True(t, info.IsDir())
-	})
-
-	t.Run("fails when parent is file", func(t *testing.T) {
-		tempDir := t.TempDir()
-		filePath := filepath.Join(tempDir, "file.txt")
-		require.NoError(t, os.WriteFile(filePath, []byte("test"), 0o600))
-
-		err := ensureSqliteDatabaseDir(filepath.Join(filePath, "data.db"))
-		require.Error(t, err)
-	})
-}
-
-func TestConvertSqlitePragmaArgs(t *testing.T) {
-	tests := []struct {
-		name     string
-		input    string
-		expected string
-	}{
-		{
-			name:     "basic file path",
-			input:    "file:test.db",
-			expected: "file:test.db",
-		},
-		{
-			name:     "converts _busy_timeout to pragma",
-			input:    "file:test.db?_busy_timeout=5000",
-			expected: "file:test.db?_pragma=busy_timeout%285000%29",
-		},
-		{
-			name:     "converts _timeout to pragma",
-			input:    "file:test.db?_timeout=5000",
-			expected: "file:test.db?_pragma=busy_timeout%285000%29",
-		},
-		{
-			name:     "converts _foreign_keys to pragma",
-			input:    "file:test.db?_foreign_keys=1",
-			expected: "file:test.db?_pragma=foreign_keys%281%29",
-		},
-		{
-			name:     "converts _fk to pragma",
-			input:    "file:test.db?_fk=1",
-			expected: "file:test.db?_pragma=foreign_keys%281%29",
-		},
-		{
-			name:     "converts _synchronous to pragma",
-			input:    "file:test.db?_synchronous=NORMAL",
-			expected: "file:test.db?_pragma=synchronous%28NORMAL%29",
-		},
-		{
-			name:     "converts _sync to pragma",
-			input:    "file:test.db?_sync=NORMAL",
-			expected: "file:test.db?_pragma=synchronous%28NORMAL%29",
-		},
-		{
-			name:     "converts _auto_vacuum to pragma",
-			input:    "file:test.db?_auto_vacuum=FULL",
-			expected: "file:test.db?_pragma=auto_vacuum%28FULL%29",
-		},
-		{
-			name:     "converts _vacuum to pragma",
-			input:    "file:test.db?_vacuum=FULL",
-			expected: "file:test.db?_pragma=auto_vacuum%28FULL%29",
-		},
-		{
-			name:     "converts _case_sensitive_like to pragma",
-			input:    "file:test.db?_case_sensitive_like=1",
-			expected: "file:test.db?_pragma=case_sensitive_like%281%29",
-		},
-		{
-			name:     "converts _cslike to pragma",
-			input:    "file:test.db?_cslike=1",
-			expected: "file:test.db?_pragma=case_sensitive_like%281%29",
-		},
-		{
-			name:     "converts _locking_mode to pragma",
-			input:    "file:test.db?_locking_mode=EXCLUSIVE",
-			expected: "file:test.db?_pragma=locking_mode%28EXCLUSIVE%29",
-		},
-		{
-			name:     "converts _locking to pragma",
-			input:    "file:test.db?_locking=EXCLUSIVE",
-			expected: "file:test.db?_pragma=locking_mode%28EXCLUSIVE%29",
-		},
-		{
-			name:     "converts _secure_delete to pragma",
-			input:    "file:test.db?_secure_delete=1",
-			expected: "file:test.db?_pragma=secure_delete%281%29",
-		},
-		{
-			name:     "preserves unrecognized parameters",
-			input:    "file:test.db?mode=rw&cache=shared",
-			expected: "file:test.db?cache=shared&mode=rw",
-		},
-		{
-			name:     "handles multiple parameters",
-			input:    "file:test.db?_fk=1&mode=rw&_timeout=5000",
-			expected: "file:test.db?_pragma=foreign_keys%281%29&_pragma=busy_timeout%285000%29&mode=rw",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			resultURL, _ := url.Parse(tt.input)
-			convertSqlitePragmaArgs(resultURL)
-
-			// Parse both URLs to compare components independently
-			expectedURL, err := url.Parse(tt.expected)
-			require.NoError(t, err)
-
-			// Compare scheme and path components
-			compareQueryStrings(t, expectedURL, resultURL)
-		})
-	}
-}
-
-func TestAddSqliteDefaultParameters(t *testing.T) {
-	tests := []struct {
-		name        string
-		input       string
-		isMemoryDB  bool
-		expected    string
-		expectError bool
-	}{
-		{
-			name:       "basic file database",
-			input:      "file:test.db",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_txlock=immediate",
-		},
-		{
-			name:       "in-memory database",
-			input:      "file::memory:",
-			isMemoryDB: true,
-			expected:   "file::memory:?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28MEMORY%29&_txlock=immediate",
-		},
-		{
-			name:       "read-only database with mode=ro",
-			input:      "file:test.db?mode=ro",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28DELETE%29&_txlock=immediate&mode=ro",
-		},
-		{
-			name:       "immutable database",
-			input:      "file:test.db?immutable=1",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28DELETE%29&_txlock=immediate&immutable=1",
-		},
-		{
-			name:       "database with existing _txlock",
-			input:      "file:test.db?_txlock=deferred",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_txlock=deferred",
-		},
-		{
-			name:       "database with existing busy_timeout pragma",
-			input:      "file:test.db?_pragma=busy_timeout%285000%29",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%285000%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_txlock=immediate",
-		},
-		{
-			name:       "database with existing journal_mode pragma",
-			input:      "file:test.db?_pragma=journal_mode%28DELETE%29",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28DELETE%29&_txlock=immediate",
-		},
-		{
-			name:        "database with forbidden foreign_keys pragma",
-			input:       "file:test.db?_pragma=foreign_keys%280%29",
-			isMemoryDB:  false,
-			expectError: true,
-		},
-		{
-			name:       "database with multiple existing pragmas",
-			input:      "file:test.db?_pragma=busy_timeout%283000%29&_pragma=journal_mode%28TRUNCATE%29&_pragma=synchronous%28NORMAL%29",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%283000%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28TRUNCATE%29&_pragma=synchronous%28NORMAL%29&_txlock=immediate",
-		},
-		{
-			name:       "database with mode=rw (not read-only)",
-			input:      "file:test.db?mode=rw",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_txlock=immediate&mode=rw",
-		},
-		{
-			name:       "database with immutable=0 (not immutable)",
-			input:      "file:test.db?immutable=0",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_txlock=immediate&immutable=0",
-		},
-		{
-			name:       "database with mixed case mode=RO",
-			input:      "file:test.db?mode=RO",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28DELETE%29&_txlock=immediate&mode=ro",
-		},
-		{
-			name:       "database with mixed case immutable=1",
-			input:      "file:test.db?immutable=1",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28DELETE%29&_txlock=immediate&immutable=1",
-		},
-		{
-			name:       "complex database configuration",
-			input:      "file:test.db?cache=shared&mode=rwc&_txlock=immediate&_pragma=synchronous%28FULL%29",
-			isMemoryDB: false,
-			expected:   "file:test.db?_pragma=busy_timeout%282500%29&_pragma=foreign_keys%281%29&_pragma=journal_mode%28WAL%29&_pragma=synchronous%28FULL%29&_txlock=immediate&cache=shared&mode=rwc",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			resultURL, err := url.Parse(tt.input)
-			require.NoError(t, err)
-
-			err = addSqliteDefaultParameters(resultURL, tt.isMemoryDB)
-
-			if tt.expectError {
-				require.Error(t, err)
-				return
-			}
-
-			require.NoError(t, err)
-
-			expectedURL, err := url.Parse(tt.expected)
-			require.NoError(t, err)
-
-			compareQueryStrings(t, expectedURL, resultURL)
-		})
-	}
-}
-
-func compareQueryStrings(t *testing.T, expectedURL *url.URL, resultURL *url.URL) {
-	t.Helper()
-
-	// Compare scheme and path components
-	assert.Equal(t, expectedURL.Scheme, resultURL.Scheme)
-	assert.Equal(t, expectedURL.Path, resultURL.Path)
-
-	// Compare query parameters regardless of order
-	expectedQuery := expectedURL.Query()
-	resultQuery := resultURL.Query()
-
-	assert.Len(t, expectedQuery, len(resultQuery))
-
-	for key, expectedValues := range expectedQuery {
-		resultValues, ok := resultQuery[key]
-		_ = assert.True(t, ok) &&
-			assert.ElementsMatch(t, expectedValues, resultValues)
-	}
-}

backend/internal/bootstrap/observability_boostrap.go

@@ -17,14 +17,12 @@ import (
 	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
 	"go.opentelemetry.io/otel"
 	globallog "go.opentelemetry.io/otel/log/global"
-	metricnoop "go.opentelemetry.io/otel/metric/noop"
 	"go.opentelemetry.io/otel/propagation"
 	sdklog "go.opentelemetry.io/otel/sdk/log"
 	"go.opentelemetry.io/otel/sdk/metric"
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"
-	tracenoop "go.opentelemetry.io/otel/trace/noop"
 
 	"github.com/pocket-id/pocket-id/backend/internal/common"
 )
@@ -39,13 +37,13 @@ func defaultResource() (*resource.Resource, error) {
 	)
 }
 
-func initObservability(ctx context.Context, metrics, traces bool) (shutdownFns []servicerunner.Service, httpClient *http.Client, err error) {
+func initObservability(ctx context.Context) (shutdownFns []servicerunner.Service, httpClient *http.Client, err error) {
 	resource, err := defaultResource()
 	if err != nil {
 		return nil, nil, fmt.Errorf("failed to create OpenTelemetry resource: %w", err)
 	}
 
-	shutdownFns = make([]servicerunner.Service, 0, 2)
+	shutdownFns = make([]servicerunner.Service, 0, 3)
 
 	httpClient = &http.Client{}
 	defaultTransport, ok := http.DefaultTransport.(*http.Transport)
@@ -56,13 +54,15 @@ func initObservability(ctx context.Context, metrics, traces bool) (shutdownFns [
 	httpClient.Transport = defaultTransport.Clone()
 
 	// Logging
-	err = initOtelLogging(ctx, resource)
+	loggingShutdownFn, err := initOtelLogging(ctx, resource)
 	if err != nil {
 		return nil, nil, err
+	} else if loggingShutdownFn != nil {
+		shutdownFns = append(shutdownFns, loggingShutdownFn)
 	}
 
 	// Tracing
-	tracingShutdownFn, err := initOtelTracing(ctx, traces, resource, httpClient)
+	tracingShutdownFn, err := initOtelTracing(ctx, resource, httpClient)
 	if err != nil {
 		return nil, nil, err
 	} else if tracingShutdownFn != nil {
@@ -70,7 +70,7 @@ func initObservability(ctx context.Context, metrics, traces bool) (shutdownFns [
 	}
 
 	// Metrics
-	metricsShutdownFn, err := initOtelMetrics(ctx, metrics, resource)
+	metricsShutdownFn, err := initOtelMetrics(ctx, resource)
 	if err != nil {
 		return nil, nil, err
 	} else if metricsShutdownFn != nil {
@@ -80,19 +80,19 @@ func initObservability(ctx context.Context, metrics, traces bool) (shutdownFns [
 	return shutdownFns, httpClient, nil
 }
 
-func initOtelLogging(ctx context.Context, resource *resource.Resource) error {
+func initOtelLogging(ctx context.Context, resource *resource.Resource) (shutdownFn servicerunner.Service, err error) {
 	// If the env var OTEL_LOGS_EXPORTER is empty, we set it to "none", for autoexport to work
 	if os.Getenv("OTEL_LOGS_EXPORTER") == "" {
 		os.Setenv("OTEL_LOGS_EXPORTER", "none")
 	}
 	exp, err := autoexport.NewLogExporter(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to initialize OpenTelemetry log exporter: %w", err)
+		return nil, fmt.Errorf("failed to initialize OpenTelemetry log exporter: %w", err)
 	}
 
 	level, _ := sloggin.ParseLevel(common.EnvConfig.LogLevel)
 
-	// Create the handler
+	// Create the console handler
 	var handler slog.Handler
 	if common.EnvConfig.LogJSON {
 		handler = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
@@ -106,21 +106,35 @@ func initOtelLogging(ctx context.Context, resource *resource.Resource) error {
 		})
 	}
 
-	// Create the logger provider
-	provider := sdklog.NewLoggerProvider(
-		sdklog.WithProcessor(
-			sdklog.NewBatchProcessor(exp),
-		),
-		sdklog.WithResource(resource),
-	)
+	// When log export is enabled, also send logs to OpenTelemetry through a batch processor.
+	// When it's disabled (the exporter is a no-op), we skip the OTel handler entirely so we don't convert and buffer every log record just to drop it.
+	if !autoexport.IsNoneLogExporter(exp) {
+		// Create the logger provider
+		provider := sdklog.NewLoggerProvider(
+			sdklog.WithProcessor(
+				sdklog.NewBatchProcessor(exp),
+			),
+			sdklog.WithResource(resource),
+		)
 
-	// Set the logger provider globally
-	globallog.SetLoggerProvider(provider)
+		// Set the logger provider globally
+		globallog.SetLoggerProvider(provider)
 
-	handler = slog.NewMultiHandler(
-		handler,
-		otelslog.NewHandler(common.Name, otelslog.WithLoggerProvider(provider)),
-	)
+		handler = slog.NewMultiHandler(
+			handler,
+			otelslog.NewHandler(common.Name, otelslog.WithLoggerProvider(provider)),
+		)
+
+		shutdownFn = func(shutdownCtx context.Context) error { //nolint:contextcheck
+			lpCtx, lpCancel := context.WithTimeout(shutdownCtx, 10*time.Second)
+			defer lpCancel()
+			shutdownErr := provider.Shutdown(lpCtx)
+			if shutdownErr != nil {
+				return fmt.Errorf("failed to gracefully shut down logs exporter: %w", shutdownErr)
+			}
+			return nil
+		}
+	}
 
 	// Set the default slog to send logs to OTel and add the app name
 	log := slog.New(handler).
@@ -128,13 +142,13 @@ func initOtelLogging(ctx context.Context, resource *resource.Resource) error {
 		With(slog.String("version", common.Version))
 	slog.SetDefault(log)
 
-	return nil
+	return shutdownFn, nil
 }
 
-func initOtelTracing(ctx context.Context, traces bool, resource *resource.Resource, httpClient *http.Client) (shutdownFn servicerunner.Service, err error) {
-	if !traces {
-		otel.SetTracerProvider(tracenoop.NewTracerProvider())
-		return nil, nil
+func initOtelTracing(ctx context.Context, resource *resource.Resource, httpClient *http.Client) (shutdownFn servicerunner.Service, err error) {
+	// If the env var OTEL_TRACES_EXPORTER is empty, we set it to "none"
+	if os.Getenv("OTEL_TRACES_EXPORTER") == "" {
+		os.Setenv("OTEL_TRACES_EXPORTER", "none")
 	}
 
 	tr, err := autoexport.NewSpanExporter(ctx)
@@ -170,10 +184,10 @@ func initOtelTracing(ctx context.Context, traces bool, resource *resource.Resour
 	return shutdownFn, nil
 }
 
-func initOtelMetrics(ctx context.Context, metrics bool, resource *resource.Resource) (shutdownFn servicerunner.Service, err error) {
-	if !metrics {
-		otel.SetMeterProvider(metricnoop.NewMeterProvider())
-		return nil, nil
+func initOtelMetrics(ctx context.Context, resource *resource.Resource) (shutdownFn servicerunner.Service, err error) {
+	// If the env var OTEL_METRICS_EXPORTER is empty, we set it to "none"
+	if os.Getenv("OTEL_METRICS_EXPORTER") == "" {
+		os.Setenv("OTEL_METRICS_EXPORTER", "none")
 	}
 
 	mr, err := autoexport.NewMetricReader(ctx)

backend/internal/bootstrap/router_bootstrap.go

@@ -26,6 +26,7 @@ import (
 	"github.com/pocket-id/pocket-id/backend/internal/common"
 	"github.com/pocket-id/pocket-id/backend/internal/controller"
 	"github.com/pocket-id/pocket-id/backend/internal/middleware"
+	"github.com/pocket-id/pocket-id/backend/internal/tracing"
 	"github.com/pocket-id/pocket-id/backend/internal/utils/systemd"
 )
 
@@ -94,8 +95,24 @@ func configureEngine(r *gin.Engine) {
 		r.TrustedPlatform = common.EnvConfig.TrustedPlatform
 	}
 
-	if common.EnvConfig.TracingEnabled {
-		r.Use(otelgin.Middleware(common.Name))
+	r.Use(otelgin.Middleware(
+		common.Name,
+		otelgin.WithFilter(shouldTraceRequest)),
+	)
+}
+
+// shouldTraceRequest reports whether an incoming request should be traced.
+// It traces only requests handled by real backend routes (the API, the OIDC/OAuth endpoints, and the well-known documents).
+// Everything else falls through to the frontend NoRoute handler, which serves the SPA shell and static assets; tracing those would produce noisy, unparented spans named just "GET" with an empty http.route.
+func shouldTraceRequest(r *http.Request) bool {
+	p := r.URL.Path
+	switch {
+	case strings.HasPrefix(p, "/api/"),
+		strings.HasPrefix(p, "/.well-known/"),
+		p == "/authorize":
+		return true
+	default:
+		return false
 	}
 }
 
@@ -159,6 +176,10 @@ func registerRoutes(r *gin.Engine, db *gorm.DB, svc *services, rateLimitServices
 	// These are not rate-limited.
 	controller.NewHealthzController(r)
 
+	// Receives OTLP trace payloads from the browser SPA (POST /internal/telemetry/traces) and forwards them to the collector, when trace export is enabled.
+	// Outside /api, so it's unauthenticated and not traced, but it is rate-limited.
+	tracing.NewTelemetryController(r, rateLimitMiddleware.Add(middleware.RateLimitInternal))
+
 	return nil
 }