Logging

Platforma provides structured logging built on Go’s standard log/slog package with automatic context enrichment.

Overview

The logging system provides:

Structured logging with key-value pairs
Context-aware logging with automatic field injection
Multiple output formats (JSON, text)
Configurable log levels
Trace ID support for request correlation
Integration with other Platforma components

Basic Usage

Use the package-level functions for simple logging:

import "github.com/platforma-dev/platforma/log"

log.Info("application started", "port", 8080)
log.Error("failed to connect", "error", err, "host", host)
log.Warn("rate limit approaching", "requests", count, "limit", max)
log.Debug("cache hit", "key", key)

Each function accepts a message string followed by key-value pairs for structured data.

Context-Aware Logging

Use context variants to automatically include context values:

log.InfoContext(ctx, "request started")
log.ErrorContext(ctx, "database query failed", "error", err)
log.WarnContext(ctx, "slow query detected", "duration", duration)
log.DebugContext(ctx, "cache miss", "key", key)

Context logging automatically extracts and includes:

Trace ID
User ID
Worker ID
Domain name
Service name
Startup task name

Context Keys

Platforma defines standard context keys for enrichment:

const (
	// TraceIDKey is the context key for trace ID
	TraceIDKey contextKey = "traceId"
	
	// UserIDKey is the context key for user ID
	UserIDKey contextKey = "userId"
	
	// WorkerIDKey is the context key for queue worker ID
	WorkerIDKey contextKey = "workerId"
	
	// ServiceNameKey is the context key for service name
	ServiceNameKey contextKey = "serviceName"
	
	// DomainNameKey is the context key for domain name
	DomainNameKey contextKey = "domainName"
	
	// StartupTaskKey is the context key for startup task
	StartupTaskKey contextKey = "startupTask"
)

Adding Context Values

Add context values to enable automatic enrichment:

import "github.com/google/uuid"

// Add trace ID
traceID := uuid.NewString()
ctx = context.WithValue(ctx, log.TraceIDKey, traceID)

// Add user ID
ctx = context.WithValue(ctx, log.UserIDKey, user.ID)

// Log with enriched context
log.InfoContext(ctx, "processing request")
// Output includes: traceId=xxx userId=yyy

Trace IDs

Trace IDs enable request correlation across logs:

Manual Trace ID

import "github.com/google/uuid"

func handleRequest(w http.ResponseWriter, r *http.Request) {
	traceID := uuid.NewString()
	ctx := context.WithValue(r.Context(), log.TraceIDKey, traceID)
	
	log.InfoContext(ctx, "request started")
	// ... process request ...
	log.InfoContext(ctx, "request completed")
	// Both logs include the same traceId
}

Automatic Trace ID with Middleware

Platforma’s HTTP server includes trace ID middleware:

import (
	"github.com/platforma-dev/platforma/httpserver"
	"github.com/google/uuid"
)

// This middleware is typically included by default
traceMiddleware := httpserver.MiddlewareFunc(func(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		traceID := uuid.NewString()
		ctx := context.WithValue(r.Context(), log.TraceIDKey, traceID)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
})

server.Use(traceMiddleware)

Creating a Logger

Create a custom logger with specific configuration:

import (
	"os"
	"log/slog"
	"github.com/platforma-dev/platforma/log"
)

// JSON logger at Info level
logger := log.New(os.Stdout, "json", slog.LevelInfo, nil)

// Text logger at Debug level
logger := log.New(os.Stdout, "text", slog.LevelDebug, nil)

// With custom context keys
customKeys := map[string]any{
	"requestId": myRequestIDKey,
	"tenantId":  myTenantIDKey,
}
logger := log.New(os.Stdout, "json", slog.LevelInfo, customKeys)

Logger Parameters

w io.Writer: Output destination (usually os.Stdout or os.Stderr)
loggerType string: Format type - “json” or “text”
level slog.Level: Minimum level - LevelDebug, LevelInfo, LevelWarn, LevelError
contextKeys map[string]any: Additional context keys to extract

Setting the Default Logger

Replace the default logger used by package functions:

customLogger := log.New(os.Stdout, "json", slog.LevelInfo, nil)
log.SetDefault(customLogger)

// Now package functions use the custom logger
log.Info("using custom logger")

Log Levels

Control log verbosity with levels:

import "log/slog"

// Production: Info level (hides Debug)
log.New(os.Stdout, "json", slog.LevelInfo, nil)

// Development: Debug level (shows everything)
log.New(os.Stdout, "text", slog.LevelDebug, nil)

// Critical only: Error level
log.New(os.Stdout, "json", slog.LevelError, nil)

Levels in order:

LevelDebug - Most verbose, for development
LevelInfo - General information, default for production
LevelWarn - Warning conditions
LevelError - Error conditions

Output Formats

Text Format

Human-readable format for development:

logger := log.New(os.Stdout, "text", slog.LevelInfo, nil)
log.SetDefault(logger)

log.InfoContext(ctx, "user logged in", "userId", "123")
// Output: time=2026-02-28T10:30:00Z level=INFO msg="user logged in" userId=123 traceId=abc-def

JSON Format

Structured format for log aggregation:

logger := log.New(os.Stdout, "json", slog.LevelInfo, nil)
log.SetDefault(logger)

log.InfoContext(ctx, "user logged in", "userId", "123")
// Output: {"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"user logged in","userId":"123","traceId":"abc-def"}

Integration with Platforma Components

Queue Workers

Worker IDs are automatically added:

// In queue/processor.go
workerCtx := context.WithValue(ctx, log.WorkerIDKey, uuid.NewString())

// In your handler
func (h *Handler) Handle(ctx context.Context, job Job) {
	log.InfoContext(ctx, "processing job", "jobId", job.ID)
	// Output includes: workerId=xxx
}

Scheduler Tasks

Trace IDs are automatically added to each run:

// In scheduler/scheduler.go
runCtx := context.WithValue(ctx, log.TraceIDKey, uuid.NewString())
log.InfoContext(runCtx, "scheduler task started")

err := runner.Run(runCtx)
if err != nil {
	log.ErrorContext(runCtx, "error in scheduler", "error", err)
}

Auth Middleware

User IDs are automatically added:

// In auth/middleware.go
ctxWithUserId := context.WithValue(ctx, log.UserIDKey, user.ID)

// In your handler
func handler(w http.ResponseWriter, r *http.Request) {
	log.InfoContext(r.Context(), "accessing profile")
	// Output includes: userId=xxx
}

Best Practices

Use context variants

Always use InfoContext, ErrorContext, etc. when you have a context available. This enables automatic enrichment:

// Good
log.InfoContext(ctx, "user registered", "username", user.Username)

// Less useful - missing trace ID, user ID, etc.
log.Info("user registered", "username", user.Username)

Use structured fields

Pass data as key-value pairs, not in the message:

// Good - structured and searchable
log.ErrorContext(ctx, "database query failed", "error", err, "query", query)

// Bad - unstructured, hard to search
log.ErrorContext(ctx, fmt.Sprintf("database query failed: %v, query: %s", err, query))

Choose the right level

Debug: Detailed information for debugging (disabled in production)
Info: General informational messages about normal operation
Warn: Warning conditions that should be reviewed
Error: Error conditions that need attention

Use JSON in production

JSON format is better for log aggregation systems like ELK, Datadog, etc.:

if os.Getenv("ENV") == "production" {
    logger := log.New(os.Stdout, "json", slog.LevelInfo, nil)
    log.SetDefault(logger)
}

Complete Example

package main

import (
	"context"
	"log/slog"
	"os"
	"github.com/platforma-dev/platforma/log"
	"github.com/google/uuid"
)

func main() {
	// Configure logger
	logger := log.New(os.Stdout, "json", slog.LevelInfo, nil)
	log.SetDefault(logger)

	// Create context with trace ID
	ctx := context.Background()
	traceID := uuid.NewString()
	ctx = context.WithValue(ctx, log.TraceIDKey, traceID)

	log.InfoContext(ctx, "application started", "version", "1.0.0")

	// Simulate some work
	if err := processRequest(ctx); err != nil {
		log.ErrorContext(ctx, "request failed", "error", err)
		return
	}

	log.InfoContext(ctx, "application finished")
}

func processRequest(ctx context.Context) error {
	log.InfoContext(ctx, "processing request")
	
	// Add user ID to context
	userID := "user123"
	ctx = context.WithValue(ctx, log.UserIDKey, userID)
	
	log.InfoContext(ctx, "user authenticated")
	log.DebugContext(ctx, "fetching user data")
	
	// Simulate work...
	
	log.InfoContext(ctx, "request completed", "duration", "250ms")
	return nil
}

Output (JSON format):

{"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"application started","version":"1.0.0","traceId":"abc-123"}
{"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"processing request","traceId":"abc-123"}
{"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"user authenticated","traceId":"abc-123","userId":"user123"}
{"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"request completed","duration":"250ms","traceId":"abc-123","userId":"user123"}
{"time":"2026-02-28T10:30:00Z","level":"INFO","msg":"application finished","traceId":"abc-123"}

Get Started

Core Concepts

Guides

Overview

Basic Usage

Context-Aware Logging

Context Keys

Adding Context Values

Trace IDs

Manual Trace ID

Automatic Trace ID with Middleware

Creating a Logger

Logger Parameters

Setting the Default Logger

Log Levels

Output Formats

Text Format

JSON Format

Integration with Platforma Components

Queue Workers

Scheduler Tasks

Auth Middleware

Best Practices

Complete Example

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Overview

​Basic Usage

​Context-Aware Logging

​Context Keys

​Adding Context Values

​Trace IDs

​Manual Trace ID

​Automatic Trace ID with Middleware

​Creating a Logger

​Logger Parameters

​Setting the Default Logger

​Log Levels

​Output Formats

​Text Format

​JSON Format

​Integration with Platforma Components

​Queue Workers

​Scheduler Tasks

​Auth Middleware

​Best Practices

​Complete Example

Build docs developers (and LLMs) love

Overview

Basic Usage

Context-Aware Logging

Context Keys

Adding Context Values

Trace IDs

Manual Trace ID

Automatic Trace ID with Middleware

Creating a Logger

Logger Parameters

Setting the Default Logger

Log Levels

Output Formats

Text Format

JSON Format

Integration with Platforma Components

Queue Workers

Scheduler Tasks

Auth Middleware

Best Practices

Complete Example