feat: auto register logger middleware tags

Author: ReneWerner87

docs/middleware/logger.md

@@ -10,6 +10,8 @@ Logger middleware for [Fiber](https://github.com/gofiber/fiber) that logs HTTP r
 
 ```go
 func New(config ...Config) fiber.Handler
+func RegisterTag(tag string, fn LogFunc) error
+func MustRegisterTag(tag string, fn LogFunc)
 ```
 
 ## Examples
@@ -43,13 +45,7 @@ app.Use(logger.New(logger.Config{
 // Logging Request ID
 app.Use(requestid.New()) // Ensure requestid middleware is used before the logger
 app.Use(logger.New(logger.Config{
-    CustomTags: map[string]logger.LogFunc{
-        "requestid": func(output logger.Buffer, c fiber.Ctx, data *logger.Data, extraParam string) (int, error) {
-            return output.WriteString(requestid.FromContext(c))
-        },
-    },
-    // For more options, see the Config section
-    // Use the custom tag ${requestid} as defined above.
+    // requestid.New() registers ${requestid} automatically.
     Format: "${pid} ${requestid} ${status} - ${method} ${path}\n",
 }))
 
@@ -118,6 +114,90 @@ app.Use(logger.New(logger.Config{
 }))
 ```
 
+### Auto-Registered Tags
+
+Some Fiber middleware registers logger middleware tags automatically. Register the producing middleware before `logger.New()` and then use the tag in `Format`.
+
+```go
+app.Use(requestid.New())
+app.Use(logger.New(logger.Config{
+    Format: "${requestid} ${status} ${method} ${path}\n",
+}))
+```
+
+The logger middleware resolves tags in this order:
+
+1. Built-in logger tags, such as `${method}`, `${path}`, and `${status}`.
+2. Globally registered tags from Fiber middleware or `logger.RegisterTag`.
+3. `Config.CustomTags`, which override tags with the same name for that logger instance.
+
+The following tags are registered by Fiber middleware when the middleware is initialized:
+
+| Tag | Registered by | Value |
+| :-- | :------------ | :---- |
+| `${requestid}` | `requestid.New()` | Request ID stored by the requestid middleware. |
+| `${username}` | `basicauth.New()` | Authenticated username stored by the basicauth middleware. |
+| `${api-key}` | `keyauth.New()` | Redacted API key stored by the keyauth middleware. |
+| `${csrf-token}` | `csrf.New()` | Redacted marker when the csrf middleware stores a token. |
+| `${session-id}` | `session.New()` or `session.NewWithStore()` | Redacted session ID stored by the session middleware. |
+
+:::note
+Auto-registered tags are access-log tags for `middleware/logger`. Application logs from the `log` package use their own context tag registry.
+:::
+
+### Register Tags from Custom Middleware
+
+Third-party middleware can expose logger tags with `logger.RegisterTag` or `logger.MustRegisterTag`. Use `sync.Once` so the tag is registered once even when the middleware is initialized multiple times.
+
+```go
+package tenantmw
+
+import (
+    "sync"
+
+    "github.com/gofiber/fiber/v3"
+    "github.com/gofiber/fiber/v3/middleware/logger"
+)
+
+var registerLoggerTagsOnce sync.Once
+
+func New() fiber.Handler {
+    registerLoggerTagsOnce.Do(func() {
+        logger.MustRegisterTag("tenant", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+            tenant, _ := c.Locals("tenant").(string)
+            return output.WriteString(tenant)
+        })
+    })
+
+    return func(c fiber.Ctx) error {
+        c.Locals("tenant", "acme")
+        return c.Next()
+    }
+}
+```
+
+Use the registered tag in the logger format after installing the middleware:
+
+```go
+app.Use(tenantmw.New())
+app.Use(logger.New(logger.Config{
+    Format: "${tenant} ${status} ${method} ${path}\n",
+}))
+```
+
+Use `Config.CustomTags` when one logger instance needs a local override without changing the global tag registration:
+
+```go
+app.Use(logger.New(logger.Config{
+    Format: "${tenant} ${status} ${method} ${path}\n",
+    CustomTags: map[string]logger.LogFunc{
+        "tenant": func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+            return output.WriteString("override")
+        },
+    },
+}))
+```
+
 ### Use Logger Middleware with Other Loggers
 
 To combine the logger middleware with loggers like Zerolog, Zap, or Logrus, use the `LoggerToWriter` helper to adapt them to an `io.Writer`.
@@ -167,7 +247,7 @@ Writing to `os.File` is goroutine-safe, but custom streams may require locking t
 | Next          | `func(fiber.Ctx) bool`                            | Next defines a function to skip this middleware when it returns true.                                                                           | `nil`                                                                 |
 | Skip          | `func(fiber.Ctx) bool`                            | Skip is a function to determine if logging is skipped or written to Stream.                                                                   | `nil`                                                                 |
 | Done          | `func(fiber.Ctx, []byte)`                         | Done is a function that is called after the log string for a request is written to Stream, and pass the log string as parameter.              | `nil`                                                                 |
-| CustomTags    | `map[string]LogFunc`                              | tagFunctions defines the custom tag action.                                                                                                   | `map[string]LogFunc`                                                  |
+| CustomTags    | `map[string]LogFunc`                              | Defines custom tag actions for this logger instance. These tags override built-in and globally registered tags with the same name.             | `map[string]LogFunc`                                                  |
 | `Format`   | `string`  | Defines the logging tags. See more in [Predefined Formats](#predefined-formats), or create your own using [Tags](#constants). | `[${time}] ${ip} ${status} - ${latency} ${method} ${path} ${error}\n` (same as `DefaultFormat`) |
 | TimeFormat    | `string`                                          | TimeFormat defines the time format for log timestamps.                                                                                        | `15:04:05`                                                            |
 | TimeZone      | `string`                                          | TimeZone can be specified, such as "UTC" and "America/New_York" and "Asia/Chongqing", etc                                                     | `"Local"`                                                             |

middleware/basicauth/basicauth.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/gofiber/fiber/v3"
 	fiberlog "github.com/gofiber/fiber/v3/log"
+	"github.com/gofiber/fiber/v3/middleware/logger"
 	"github.com/gofiber/utils/v2"
 	"golang.org/x/text/unicode/norm"
 )
@@ -120,6 +121,9 @@ func registerLogContextTags() {
 	fiberlog.MustRegisterContextTag("username", func(output fiberlog.Buffer, ctx any, _ *fiberlog.ContextData, _ string) (int, error) {
 		return output.WriteString(UsernameFromContext(ctx))
 	})
+	logger.MustRegisterTag("username", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+		return output.WriteString(UsernameFromContext(c))
+	})
 }
 
 func containsCTL(s string) bool {

middleware/csrf/csrf.go

@@ -15,6 +15,7 @@ import (
 	"github.com/gofiber/fiber/v3"
 	"github.com/gofiber/fiber/v3/extractors"
 	fiberlog "github.com/gofiber/fiber/v3/log"
+	"github.com/gofiber/fiber/v3/middleware/logger"
 )
 
 var (
@@ -234,6 +235,12 @@ func registerLogContextTags() {
 		}
 		return output.WriteString(redactedKey)
 	})
+	logger.MustRegisterTag("csrf-token", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+		if TokenFromContext(c) == "" {
+			return 0, nil
+		}
+		return output.WriteString(redactedKey)
+	})
 }
 
 // TokenFromContext returns the token found in the context.

middleware/keyauth/keyauth.go

@@ -9,6 +9,7 @@ import (
 	"github.com/gofiber/fiber/v3"
 	"github.com/gofiber/fiber/v3/extractors"
 	fiberlog "github.com/gofiber/fiber/v3/log"
+	"github.com/gofiber/fiber/v3/middleware/logger"
 	"github.com/gofiber/utils/v2"
 )
 
@@ -107,6 +108,13 @@ func registerLogContextTags() {
 		}
 		return output.WriteString(redactContextValue(token))
 	})
+	logger.MustRegisterTag("api-key", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+		token := TokenFromContext(c)
+		if token == "" {
+			return 0, nil
+		}
+		return output.WriteString(redactContextValue(token))
+	})
 }
 
 func redactContextValue(value string) string {

middleware/logger/config.go

@@ -32,7 +32,8 @@ type Config struct {
 	// Optional. Default: nil
 	Done func(c fiber.Ctx, logString []byte)
 
-	// tagFunctions defines the custom tag action
+	// CustomTags defines per-middleware tag functions.
+	// CustomTags override built-in and globally registered tags with the same name.
 	//
 	// Optional. Default: map[string]LogFunc
 	CustomTags map[string]LogFunc

middleware/logger/logger_test.go

@@ -24,7 +24,6 @@ import (
 
 	"github.com/gofiber/fiber/v3"
 	fiberlog "github.com/gofiber/fiber/v3/log"
-	"github.com/gofiber/fiber/v3/middleware/requestid"
 )
 
 const (
@@ -884,11 +883,10 @@ func Test_Response_Header(t *testing.T) {
 
 	app := fiber.New()
 
-	app.Use(requestid.New(requestid.Config{
-		Next:      nil,
-		Header:    fiber.HeaderXRequestID,
-		Generator: func() string { return "Hello fiber!" },
-	}))
+	app.Use(func(c fiber.Ctx) error {
+		c.Response().Header.Set(fiber.HeaderXRequestID, "Hello fiber!")
+		return c.Next()
+	})
 	app.Use(New(Config{
 		Format: "${respHeader:X-Request-ID}",
 		Stream: buf,
@@ -904,6 +902,74 @@ func Test_Response_Header(t *testing.T) {
 	require.Equal(t, "Hello fiber!", buf.String())
 }
 
+func Test_Logger_RegisteredTag(t *testing.T) {
+	t.Parallel()
+
+	const tag = "registered-test-tag"
+
+	require.NoError(t, RegisterTag(tag, func(output Buffer, _ fiber.Ctx, _ *Data, _ string) (int, error) {
+		return output.WriteString("registered")
+	}))
+
+	buf := bytebufferpool.Get()
+	defer bytebufferpool.Put(buf)
+
+	app := fiber.New()
+	app.Use(New(Config{
+		Format: "${" + tag + "}",
+		Stream: buf,
+	}))
+	app.Get("/", func(c fiber.Ctx) error {
+		return c.SendStatus(fiber.StatusOK)
+	})
+
+	resp, err := app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+	require.NoError(t, err)
+	require.Equal(t, fiber.StatusOK, resp.StatusCode)
+	require.Equal(t, "registered", buf.String())
+}
+
+func Test_Logger_CustomTagOverridesRegisteredTag(t *testing.T) {
+	t.Parallel()
+
+	const tag = "registered-override-test-tag"
+
+	require.NoError(t, RegisterTag(tag, func(output Buffer, _ fiber.Ctx, _ *Data, _ string) (int, error) {
+		return output.WriteString("registered")
+	}))
+
+	buf := bytebufferpool.Get()
+	defer bytebufferpool.Put(buf)
+
+	app := fiber.New()
+	app.Use(New(Config{
+		Format: "${" + tag + "}",
+		CustomTags: map[string]LogFunc{
+			tag: func(output Buffer, _ fiber.Ctx, _ *Data, _ string) (int, error) {
+				return output.WriteString("override")
+			},
+		},
+		Stream: buf,
+	}))
+	app.Get("/", func(c fiber.Ctx) error {
+		return c.SendStatus(fiber.StatusOK)
+	})
+
+	resp, err := app.Test(httptest.NewRequest(fiber.MethodGet, "/", http.NoBody))
+	require.NoError(t, err)
+	require.Equal(t, fiber.StatusOK, resp.StatusCode)
+	require.Equal(t, "override", buf.String())
+}
+
+func Test_Logger_RegisterTagRejectsInvalidInput(t *testing.T) {
+	t.Parallel()
+
+	require.ErrorIs(t, RegisterTag("", func(output Buffer, _ fiber.Ctx, _ *Data, _ string) (int, error) {
+		return output.WriteString("ignored")
+	}), errTagInvalid)
+	require.ErrorIs(t, RegisterTag("missing", nil), errTagInvalid)
+}
+
 // go test -run Test_Req_Header
 func Test_Req_Header(t *testing.T) {
 	t.Parallel()

middleware/logger/tags.go

@@ -1,9 +1,11 @@
 package logger
 
 import (
+	"errors"
 	"fmt"
 	"maps"
 	"strings"
+	"sync"
 
 	"github.com/gofiber/fiber/v3"
 )
@@ -50,6 +52,38 @@ const (
 	TagReset             = "reset"
 )
 
+var errTagInvalid = errors.New("logger: tag name and function are required")
+
+var registeredTags = struct {
+	m map[string]LogFunc
+	sync.RWMutex
+}{
+	m: make(map[string]LogFunc),
+}
+
+// RegisterTag registers a global logger middleware tag.
+// Registered tags are available to logger middleware instances created after
+// registration and can be overridden per instance with Config.CustomTags.
+// Re-registering a tag replaces the existing tag function.
+func RegisterTag(tag string, fn LogFunc) error {
+	if tag == "" || fn == nil {
+		return errTagInvalid
+	}
+
+	registeredTags.Lock()
+	defer registeredTags.Unlock()
+
+	registeredTags.m[tag] = fn
+	return nil
+}
+
+// MustRegisterTag registers a global logger middleware tag and panics on failure.
+func MustRegisterTag(tag string, fn LogFunc) {
+	if err := RegisterTag(tag, fn); err != nil {
+		panic(err)
+	}
+}
+
 // createTagMap function merged the default with the custom tags
 func createTagMap(cfg *Config) map[string]LogFunc {
 	// Set default tags
@@ -204,6 +238,10 @@ func createTagMap(cfg *Config) map[string]LogFunc {
 			return output.WriteString(data.Timestamp.Load().(string)) //nolint:forcetypeassert,errcheck // We always store a string in here
 		},
 	}
+	registeredTags.RLock()
+	maps.Copy(tagFunctions, registeredTags.m)
+	registeredTags.RUnlock()
+
 	// merge with custom tags from user
 	maps.Copy(tagFunctions, cfg.CustomTags)
 

middleware/requestid/requestid.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/gofiber/fiber/v3"
 	fiberlog "github.com/gofiber/fiber/v3/log"
+	"github.com/gofiber/fiber/v3/middleware/logger"
 	"github.com/gofiber/utils/v2"
 )
 
@@ -51,6 +52,9 @@ func registerLogContextTags() {
 	}
 	fiberlog.MustRegisterContextTag("requestid", tag)
 	fiberlog.MustRegisterContextTag("request-id", tag)
+	logger.MustRegisterTag("requestid", func(output logger.Buffer, c fiber.Ctx, _ *logger.Data, _ string) (int, error) {
+		return output.WriteString(FromContext(c))
+	})
 }
 
 // sanitizeRequestID returns the provided request ID when it is valid, otherwise