Skip to content

Commit

Permalink
Clarify the godoc warning for Logger.UpdateContext (#566)
Browse files Browse the repository at this point in the history
  • Loading branch information
sdavispluto authored Jul 29, 2023
1 parent 873cbf1 commit 06ec071
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 1 deletion.
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -755,6 +755,8 @@ Log a static string, without any context or `printf`-style templating:

## Caveats

### Field duplication

Note that zerolog does no de-duplication of fields. Using the same key multiple times creates multiple keys in final JSON:

```go
Expand All @@ -766,3 +768,19 @@ logger.Info().
```

In this case, many consumers will take the last value, but this is not guaranteed; check yours if in doubt.

### Concurrency safety

Be careful when calling UpdateContext. It is not concurrency safe. Use the With method to create a child logger:

```go
func handler(w http.ResponseWriter, r *http.Request) {
// Create a child logger for concurrency safety
logger := log.Logger.With().Logger()

// Add context fields, for example User-Agent from HTTP headers
logger.UpdateContext(func(c zerolog.Context) zerolog.Context {
...
})
}
```
19 changes: 18 additions & 1 deletion log.go
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@
//
// # Caveats
//
// Field duplication:
//
// There is no fields deduplication out-of-the-box.
// Using the same key multiple times creates new key in final JSON each time.
//
Expand All @@ -95,6 +97,20 @@
//
// In this case, many consumers will take the last value,
// but this is not guaranteed; check yours if in doubt.
//
// Concurrency safety:
//
// Be careful when calling UpdateContext. It is not concurrency safe. Use the With method to create a child logger:
//
// func handler(w http.ResponseWriter, r *http.Request) {
// // Create a child logger for concurrency safety
// logger := log.Logger.With().Logger()
//
// // Add context fields, for example User-Agent from HTTP headers
// logger.UpdateContext(func(c zerolog.Context) zerolog.Context {
// ...
// })
// }
package zerolog

import (
Expand Down Expand Up @@ -276,7 +292,8 @@ func (l Logger) With() Context {

// UpdateContext updates the internal logger's context.
//
// Use this method with caution. If unsure, prefer the With method.
// Caution: This method is not concurrency safe.
// Use the With method to create a child logger before modifying the context from concurrent goroutines.
func (l *Logger) UpdateContext(update func(c Context) Context) {
if l == disabledLogger {
return
Expand Down

0 comments on commit 06ec071

Please sign in to comment.