Skip to main content

Zap Logger

Zap Logger

High-performance structured logging for the Control Plane

The Control Plane uses Uber's Zap library for structured, high-performance logging.

Performance-focused logging

Zap provides extremely fast, allocation-free logging that enables comprehensive system observability without sacrificing performance.

Overview​

Zap is a fast, structured logging library for Go, designed with performance in mind. The Control Plane uses Zap for:

📊 Structured JSON Logging

Machine-parseable logs with consistent field formats for automated analysis.

🧩 Contextual Fields

Rich metadata attached to log messages for improved debugging and tracing.

🌳 Hierarchical Logging

Component-based logger organization reflecting system architecture.

⚡ High Performance

Minimal allocations and optimized processing for performance-critical paths.

🔍 Sampling

Intelligent log sampling for high-volume events to reduce overhead.

🔄 Level Control

Dynamic log level adjustment without restarts for operational flexibility.

Zap Logo

Why Zap?​

Performance comparison

In benchmark tests, Zap can be up to 10x faster than other structured logging libraries while allocating far fewer objects, which is critical for high-throughput services.

Performance Metrics

Zap significantly outperforms other logging libraries:

  • 10x faster than logrus in some scenarios
  • Near-zero memory allocations
  • Optimized JSON encoding
  • Minimal CPU overhead
  • Efficient level checking

Feature Comparison

Advantages over other logging solutions:

  • Strongly typed fields preventing runtime errors
  • Flexible configuration options
  • Multiple output encoders (JSON, console)
  • Built-in sampling capabilities
  • Field namespacing for organization

Integration with Kubernetes​

logr compatibility

The Control Plane integrates Zap with Kubernetes' logging abstractions through the logr interface, enabling seamless integration with controller-runtime and other Kubernetes libraries.

Logging Architecture​

Logging flow

The Control Plane implements a consistent logging architecture from application code through to log aggregation and analysis.

Log Levels​

Environment-specific configuration

The Control Plane uses different log levels for different environments, balancing verbosity with performance needs.

Dynamic Log Level Management​

Runtime adjustment

The Control Plane supports dynamic log level adjustment during runtime, allowing operators to increase logging verbosity temporarily for troubleshooting.

Structured Logging​

Log as data

Structured logging treats log messages as data records rather than text strings, making them machine-readable and enabling sophisticated filtering and analysis.

Performance Considerations​

Optimization techniques

The Control Plane employs several techniques to maximize logging performance while maintaining comprehensive observability.

The Control Plane uses Zap's performance optimizations:

🔄 Pre-allocated Fields

Base loggers with common fields to reduce per-log allocations.

🧮 Minimal Allocations

Strongly typed fields and reused buffers to reduce GC pressure.

⚡ Fast Marshaling

Optimized JSON encoders for efficient serialization.

🔍 Level Checking

Early level checks to avoid unnecessary processing of disabled logs.

📊 Sampling

Intelligent sampling for high-frequency events.

📦 Object Pooling

Internal object pools to minimize memory churn.

Logging Best Practices​

Consistent approach

The Control Plane follows these logging best practices to ensure logs are informative, consistent, and useful for debugging and monitoring.

Log Levels​

Debug

Fine-grained development information useful during development and troubleshooting. Examples: variable values, function entry/exit, detailed flow control.

Info

General operational events describing normal system behavior. Examples: service startup/shutdown, user actions, task completion.

Warning

Non-critical issues that might indicate problems but don't interrupt operation. Examples: deprecated API usage, unexpected but handled conditions.

Error

Runtime errors that require attention but don't crash the system. Examples: API failures, rejected requests, database errors.

Fatal/Panic

Critical errors causing application shutdown or panic. Examples: missing configuration, failed startup requirements, internal inconsistencies.

Contextual Information​

🔑 Request IDs

Include unique identifiers for each request to trace through the system.

👤 User Information

Add user identifiers when available for user-specific troubleshooting.

📦 Resource Identifiers

Include IDs for affected resources like files, databases, or API endpoints.

🔄 Operation Names

Specify the high-level operation being performed for context.

⏱️ Timing Information

Include duration for long-running operations or performance-critical paths.

🌍 Environment Context

Add environment, region, or zone information for multi-environment setups.

Standardized Format​

Field Naming Conventions

Standard field names used across the Control Plane:

  • request_id: Unique request identifier
  • user_id: User identifier
  • service: Service name
  • component: Component within service
  • operation: Operation being performed
  • duration_ms: Operation duration in milliseconds
  • error: Error message or type
  • version: Software version

Metadata Standards

Additional standards for log metadata:

  • ISO 8601 timestamps with timezone
  • Hierarchical logger names (service.component.subcomponent)
  • Source code file and line numbers
  • Consistent error formats
  • JSON format for all production logs
  • Human-readable format for development
  • Standard severity levels

Configuration Management​

Flexible configuration

The Control Plane provides multiple ways to configure logging based on deployment needs and environments.

Environment Variables

Logger configuration through environment:

LOG_LEVEL=debug LOG_FORMAT=json LOG_OUTPUT=stdout LOG_SAMPLING_INITIAL=100 LOG_SAMPLING_THEREAFTER=100

Configuration File

YAML-based configuration:

logging: level: info encoding: json outputPaths: - stdout - /var/log/service.log errorOutputPaths: - stderr encoderConfig: timeKey: ts timeEncoder: iso8601

Programmatic Configuration

Dynamic configuration in code:

config := zap.Config{ Level: zap.NewAtomicLevelAt(zap.InfoLevel), Development: false, Sampling: &zap.SamplingConfig{ Initial: 100, Thereafter: 100, }, Encoding: "json", // Additional configuration... } logger, _ := config.Build()

Runtime Level Management

HTTP endpoint for dynamic level adjustment:

app.Get("/loglevel", func(c *fiber.Ctx) error { // Get current level return c.JSON(fiber.Map{ "level": atomicLevel.String(), }) }) app.Post("/loglevel", func(c *fiber.Ctx) error { // Parse new level from request level := c.FormValue("level") zapLevel, err := zapcore.ParseLevel(level) if err == nil { atomicLevel.SetLevel(zapLevel) } return c.SendStatus(200) })

Prometheus Metrics

Learn about the metrics collection system used alongside Zap logging.

View Prometheus Metrics

Architecture

Understand how logging fits into the overall Control Plane architecture.

View Architecture