Zax

https://github.com/yuseferi/zax
Admin
Zax is a Go library that integrates Uber's Zap logger with context.Context to enable context-aware...
Tokens:5,829
Snippets:47
Trust Score:8.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Zax

Source: https://github.com/yuseferi/zax/blob/master/README.md

Use the go get command to add the Zax package to your Go project.

```bash
go get -u github.com/yuseferi/zax/v2
```

--------------------------------

### Install Task

Source: https://github.com/yuseferi/zax/blob/master/README.md

Install the Task task runner to manage local development commands.

```bash
go run github.com/go-task/task/v3/cmd/task@latest --version
```

--------------------------------

### Quick Start Logging with Context

Source: https://github.com/yuseferi/zax/blob/master/README.md

Demonstrates setting, appending, and retrieving zap fields from context to ensure consistent logging across function calls.

```go
package main

import (
    "context"
    
    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()
    
    ctx := context.Background()
    
    // Add trace_id to context
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
        zap.String("user_id", "user-456"),
    })
    
    // Log with context fields - automatically includes trace_id and user_id
    logger.With(zax.Get(ctx)...).Info("request started")
    
    // Pass context to other functions
    processRequest(ctx, logger)
}

func processRequest(ctx context.Context, logger *zap.Logger) {
    // All logs automatically include trace_id and user_id!
    logger.With(zax.Get(ctx)...).Info("processing request")
    
    // Append additional fields without losing existing ones
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("step", "validation"),
    })
    
    logger.With(zax.Get(ctx)...).Info("validation complete")
}
```

--------------------------------

### HTTP Middleware with Distributed Tracing

Source: https://github.com/yuseferi/zax/blob/master/README.md

Example of using Zax in an HTTP middleware to inject trace context into request handlers.

```go
package main

import (
    "context"
    "net/http"
    
    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

type Server struct {
    logger *zap.Logger
}

// Middleware injects trace context into all requests
func (s *Server) TracingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        
        // Extract or generate trace ID
        traceID := r.Header.Get("X-Trace-ID")
        if traceID == "" {
            traceID = generateTraceID()
        }
        
        // Store in context
        ctx = zax.Set(ctx, []zap.Field{
            zap.String("trace_id", traceID),
            zap.String("method", r.Method),
            zap.String("path", r.URL.Path),
        })
        
        s.logger.With(zax.Get(ctx)...).Info("request received")
        
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// Handler automatically has access to trace context
func (s *Server) HandleUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    
    // Add handler-specific context
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("handler", "user"),
    })
    
    user, err := s.fetchUser(ctx)
    if err != nil {
        s.logger.With(zax.Get(ctx)...).Error("failed to fetch user", zap.Error(err))
        http.Error(w, "Internal Error", 500)
        return
    }
    
    s.logger.With(zax.Get(ctx)...).Info("user fetched successfully",
        zap.String("user_id", user.ID),
    )
}

func (s *Server) fetchUser(ctx context.Context) (*User, error) {
    // All logs here include trace_id, method, path, and handler!
    s.logger.With(zax.Get(ctx)...).Debug("querying database")
    // ... database logic
    return &User{}, nil
}
```

--------------------------------

### GetSugared - Get Fields for SugaredLogger

Source: https://context7.com/yuseferi/zax/llms.txt

Converts zap.Fields stored in context to key-value pairs compatible with zap.SugaredLogger.With().

```APIDOC
## GetSugared

### Description
The `GetSugared` function converts zap.Fields stored in context to key-value pairs compatible with `zap.SugaredLogger.With()`. It handles common field types including strings, bools, numbers, errors, durations, and times.

### Parameters
- **ctx** (context.Context) - Required - The context containing the zap fields.

### Response
- **fields** ([]interface{}) - A slice of key-value pairs suitable for use with SugaredLogger.With().
```

--------------------------------

### Development Commands

Source: https://github.com/yuseferi/zax/blob/master/README.md

Provides essential commands for developing the Zax project, including cloning the repository, running tests, executing benchmarks, and using the linter.

```bash
# Clone the repository
git clone https://github.com/yuseferi/zax.git
cd zax

# Run tests
go test -v ./...

# Run benchmarks
go test -bench=. -benchmem

# Run linter
golangci-lint run
```

--------------------------------

### Run Benchmarks

Source: https://github.com/yuseferi/zax/blob/master/README.md

Command to execute performance benchmarks for the package.

```bash
go test -bench . -run '^$' ./...
```

--------------------------------

### Preview Release

Source: https://github.com/yuseferi/zax/blob/master/README.md

Perform a dry run of the release process to preview the next version.

```bash
task release:dry-run
```

--------------------------------

### Run Task Commands

Source: https://github.com/yuseferi/zax/blob/master/README.md

Execute common development tasks using the Task runner.

```bash
task build
task test
task test:race
task lint
task bench
task ci
```

--------------------------------

### Set Context Fields

Source: https://github.com/yuseferi/zax/blob/master/README.md

Replaces any existing fields in the context with the provided zap fields.

```go
ctx = zax.Set(ctx, []zap.Field{
    zap.String("trace_id", "my-trace-id"),
    zap.Int("request_num", 42),
})
```

--------------------------------

### Full Benchmark Results

Source: https://github.com/yuseferi/zax/blob/master/README.md

Displays the detailed results of performance benchmarks comparing Zax V2, Zax V1, and pure Zap. Shows operations per second, bytes per operation, and allocations per operation.

```text
pkg: github.com/yuseferi/zax/v2
BenchmarkLoggingWithOnlyZap-10          103801226               35.56 ns/op          112 B/op          1 allocs/op
BenchmarkLoggingWithOnlyZap-10          98576570                35.56 ns/op          112 B/op          1 allocs/op
BenchmarkLoggingWithOnlyZap-10          100000000               35.24 ns/op          112 B/op          1 allocs/op
BenchmarkLoggingWithOnlyZap-10          100000000               34.85 ns/op          112 B/op          1 allocs/op
BenchmarkLoggingWithOnlyZap-10          100000000               34.98 ns/op          112 B/op          1 allocs/op
BenchmarkLoggingWithZaxV2-10            64324434                56.02 ns/op           72 B/op          2 allocs/op
BenchmarkLoggingWithZaxV2-10            63939517                56.98 ns/op           72 B/op          2 allocs/op
BenchmarkLoggingWithZaxV2-10            63374052                57.60 ns/op           72 B/op          2 allocs/op
BenchmarkLoggingWithZaxV2-10            63417358                57.37 ns/op           72 B/op          2 allocs/op
BenchmarkLoggingWithZaxV2-10            57964246                57.97 ns/op           72 B/op          2 allocs/op
BenchmarkLoggingWithZaxV1-10            54062712                66.40 ns/op          160 B/op          2 allocs/op
BenchmarkLoggingWithZaxV1-10            53155524                65.61 ns/op          160 B/op          2 allocs/op
BenchmarkLoggingWithZaxV1-10            54428521                64.19 ns/op          160 B/op          2 allocs/op
BenchmarkLoggingWithZaxV1-10            55420744                64.28 ns/op          160 B/op          2 allocs/op
BenchmarkLoggingWithZaxV1-10            55199061                64.50 ns/op          160 B/op          2 allocs/op
PASS
ok      github.com/yuseferi/zax/v2      56.919s
```

--------------------------------

### Set Fields in Context

Source: https://context7.com/yuseferi/zax/llms.txt

Use zax.Set to store zap fields in a context, replacing any existing fields previously stored.

```go
package main

import (
    "context"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    ctx := context.Background()

    // Store trace_id and user_id in context
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
        zap.String("user_id", "user-456"),
        zap.Int("request_num", 42),
    })

    // Log with context fields
    logger.With(zax.Get(ctx)...).Info("request started")
    // Output: {"level":"info","msg":"request started","trace_id":"abc-123","user_id":"user-456","request_num":42}

    // Setting new fields replaces all existing ones
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("new_trace_id", "xyz-789"),
    })

    logger.With(zax.Get(ctx)...).Info("new context")
    // Output: {"level":"info","msg":"new context","new_trace_id":"xyz-789"}
}
```

--------------------------------

### HTTP Middleware for Zax Tracing

Source: https://context7.com/yuseferi/zax/llms.txt

This middleware injects trace context into HTTP requests. It extracts or generates a trace ID and adds request details like method, path, and remote address to the context. Use this at the entry point of your HTTP server.

```go
package main

import (
    "context"
    "net/http"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

type Server struct {
    logger *zap.Logger
}

// TracingMiddleware injects trace context into all requests
func (s *Server) TracingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        // Extract trace ID from header or generate new one
        traceID := r.Header.Get("X-Trace-ID")
        if traceID == "" {
            traceID = "generated-trace-id-12345"
        }

        // Store request context fields
        ctx = zax.Set(ctx, []zap.Field{
            zap.String("trace_id", traceID),
            zap.String("method", r.Method),
            zap.String("path", r.URL.Path),
            zap.String("remote_addr", r.RemoteAddr),
        })

        s.logger.With(zax.Get(ctx)...).Info("request received")
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// HandleUser automatically has access to trace context
func (s *Server) HandleUser(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    // Add handler-specific context
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("handler", "user"),
    })

    user, err := s.fetchUser(ctx, "user-123")
    if err != nil {
        s.logger.With(zax.Get(ctx)...).Error("failed to fetch user", zap.Error(err))
        http.Error(w, "Internal Error", http.StatusInternalServerError)
        return
    }

    s.logger.With(zax.Get(ctx)...).Info("user fetched successfully",
        zap.String("user_id", user.ID),
    )
    w.Write([]byte("User: " + user.ID))
}

func (s *Server) fetchUser(ctx context.Context, userID string) (*User, error) {
    // Add database layer context
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("layer", "repository"),
        zap.String("operation", "fetch_user"),
    })

    // All logs here include: trace_id, method, path, remote_addr, handler, layer, operation
    s.logger.With(zax.Get(ctx)...).Debug("querying database")

    return &User{ID: userID}, nil
}

type User struct {
    ID string
}

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    server := &Server{logger: logger}

    mux := http.NewServeMux()
    mux.HandleFunc("/user", server.HandleUser)

    handler := server.TracingMiddleware(mux)
    http.ListenAndServe(":8080", handler)
}

```

--------------------------------

### Retrieve Context Fields

Source: https://github.com/yuseferi/zax/blob/master/README.md

Extracts all stored fields from the context for use with a logger.

```go
fields := zax.Get(ctx)
logger.With(fields...).Info("message")
```

--------------------------------

### Append Context Fields

Source: https://github.com/yuseferi/zax/blob/master/README.md

Adds new fields to the context while preserving existing ones.

```go
// Existing: trace_id
ctx = zax.Append(ctx, []zap.Field{
    zap.String("span_id", "my-span-id"),
})
// Now has: trace_id + span_id
```

--------------------------------

### Convert Context Fields for SugaredLogger with GetSugared

Source: https://context7.com/yuseferi/zax/llms.txt

Transform zap.Fields stored in context into a slice of interface{} compatible with zap.SugaredLogger.With(). Supports various types including errors, durations, and primitives.

```go
package main

import (
    "context"
    "errors"
    "time"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    sugar := logger.Sugar()
    defer logger.Sync()

    ctx := context.Background()
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
        zap.Bool("sampled", true),
        zap.Int("attempt", 2),
        zap.Duration("latency", 150*time.Millisecond),
        zap.Error(errors.New("connection timeout")),
    })

    // Use with SugaredLogger
    sugar.With(zax.GetSugared(ctx)...).Info("request completed")
    // Output includes all fields: trace_id, sampled, attempt, latency, error

    // GetSugared returns key-value pairs as []interface{}
    // ["trace_id", "abc-123", "sampled", true, "attempt", 2, "latency", "150ms", "error", error]

    sugar.With(zax.GetSugared(ctx)...).Errorf("failed after %d attempts", 3)
    // Output: {"level":"error","msg":"failed after 3 attempts","trace_id":"abc-123","sampled":true,"attempt":2,"latency":"150ms","error":"connection timeout"}
}
```

--------------------------------

### Retrieve Specific Field

Source: https://github.com/yuseferi/zax/blob/master/README.md

Fetches a single zap field from the context by its key.

```go
traceField := zax.GetField(ctx, "trace_id")
fmt.Println(traceField.String) // "my-trace-id"
```

--------------------------------

### GetField - Retrieve a Specific Field by Key

Source: https://context7.com/yuseferi/zax/llms.txt

Retrieves a specific zap field from the context by its key. Returns a zero-value field if the key is not found.

```APIDOC
## GetField

### Description
The `GetField` function retrieves a specific zap field from context by its key. This is useful when you need to access a particular field's value without retrieving all fields.

### Parameters
- **ctx** (context.Context) - Required - The context containing the zap fields.
- **key** (string) - Required - The key of the field to retrieve.

### Response
- **field** (zap.Field) - The retrieved field or a zero-value field if not found.
```

--------------------------------

### Retrieve a Specific Field by Key with GetField

Source: https://context7.com/yuseferi/zax/llms.txt

Access a specific zap.Field from the context by its key. Returns a zero-value field if the key is not found or the context is empty.

```go
package main

import (
    "context"
    "fmt"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    ctx := context.Background()
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
        zap.String("user_id", "user-456"),
        zap.Int("attempt", 3),
    })

    // Get specific field by key
    traceField := zax.GetField(ctx, "trace_id")
    fmt.Println(traceField.Key)    // "trace_id"
    fmt.Println(traceField.String) // "abc-123"

    userField := zax.GetField(ctx, "user_id")
    fmt.Println(userField.String) // "user-456"

    // Returns zero-value field if key not found
    notFound := zax.GetField(ctx, "nonexistent")
    fmt.Println(notFound.Key) // "" (empty string)

    // Works with empty context too
    emptyField := zax.GetField(context.Background(), "any_key")
    fmt.Println(emptyField.Key) // "" (empty string)
}
```

--------------------------------

### Retrieve Sugared Fields

Source: https://github.com/yuseferi/zax/blob/master/README.md

Returns fields formatted for use with a SugaredLogger.

```go
sugar := logger.Sugar()
sugar.With(zax.GetSugared(ctx)...).Info("sugared log")
```

--------------------------------

### Retrieve Fields from Context

Source: https://context7.com/yuseferi/zax/llms.txt

Use zax.Get to retrieve a cloned slice of zap.Field from the context. The returned slice is safe from external mutation.

```go
package main

import (
    "context"
    "fmt"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    ctx := context.Background()
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
        zap.String("user_id", "user-456"),
        zap.Bool("authenticated", true),
    })

    // Get all fields and use with logger
    fields := zax.Get(ctx)
    logger.With(fields...).Info("processing request")
    // Output: {"level":"info","msg":"processing request","trace_id":"abc-123","user_id":"user-456","authenticated":true}

    // Fields are cloned - mutations don't affect context
    fields[0] = zap.String("trace_id", "mutated")
    originalFields := zax.Get(ctx)
    fmt.Println(originalFields[0].String) // "abc-123" - original unchanged

    // Get returns nil for empty context
    emptyFields := zax.Get(context.Background())
    fmt.Println(emptyFields == nil) // true
}
```

--------------------------------

### Core Zax Functions

Source: https://github.com/yuseferi/zax/blob/master/README.md

Functions for managing and retrieving zap fields within a context.

```APIDOC
## Set(ctx, fields)

### Description
Stores zap fields in context. Replaces any existing fields.

### Parameters
- **ctx** (context.Context) - Required - The context to store fields in.
- **fields** ([]zap.Field) - Required - The fields to store.

## Append(ctx, fields)

### Description
Appends fields to existing context fields. Preserves previously set fields.

### Parameters
- **ctx** (context.Context) - Required - The context to append fields to.
- **fields** ([]zap.Field) - Required - The fields to append.

## Get(ctx)

### Description
Retrieves all stored fields from context.

### Parameters
- **ctx** (context.Context) - Required - The context to retrieve fields from.

## GetField(ctx, key)

### Description
Retrieves a specific field by key.

### Parameters
- **ctx** (context.Context) - Required - The context to search.
- **key** (string) - Required - The field key to look for.

## GetSugared(ctx)

### Description
Returns fields as key-value pairs for SugaredLogger.

### Parameters
- **ctx** (context.Context) - Required - The context to retrieve fields from.
```

--------------------------------

### Append Fields to Context

Source: https://context7.com/yuseferi/zax/llms.txt

Use zax.Append to add fields to existing context fields without overwriting them. This is useful for incremental logging across application layers.

```go
package main

import (
    "context"

    "github.com/yuseferi/zax/v2"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    ctx := context.Background()

    // Initial fields set in middleware
    ctx = zax.Set(ctx, []zap.Field{
        zap.String("trace_id", "abc-123"),
    })

    // Append span_id in service layer - preserves trace_id
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("span_id", "span-001"),
    })

    // Append more context in repository layer
    ctx = zax.Append(ctx, []zap.Field{
        zap.String("db_query", "SELECT * FROM users"),
    })

    // All fields are present: trace_id + span_id + db_query
    logger.With(zax.Get(ctx)...).Info("database query executed")
    // Output: {"level":"info","msg":"database query executed","trace_id":"abc-123","span_id":"span-001","db_query":"SELECT * FROM users"}

    // Append works on empty context too
    emptyCtx := context.Background()
    emptyCtx = zax.Append(emptyCtx, []zap.Field{zap.String("key", "value")})
    logger.With(zax.Get(emptyCtx)...).Info("appended to empty context")
    // Output: {"level":"info","msg":"appended to empty context","key":"value"}
}
```
Tokens:
Raw