Documentation
¶
Overview ¶
Package logging provides structured logging infrastructure for CloudZero Agent operations.
Package logging provides structured logging infrastructure for CloudZero Agent operations. This package implements a comprehensive logging framework built on Zerolog that enables consistent, structured logging across all CloudZero Agent components with configurable output destinations, log levels, and contextual information.
The logging infrastructure supports CloudZero Agent operational requirements including development debugging, production monitoring, audit compliance, and performance analysis through structured log events with consistent formatting and metadata.
Key capabilities:
- Structured logging: JSON-formatted log events with consistent field structure
- Multiple sinks: Simultaneous output to multiple destinations (stdout, files, external systems)
- Level control: Configurable log levels for development and production environments
- Context integration: Automatic correlation with request contexts and tracing information
- Hook system: Extensible logging pipeline with custom processing hooks
- Attribute injection: Consistent metadata addition across all log events
Configuration patterns:
- Development: Human-readable console output with debug information
- Production: JSON-structured logs for aggregation and analysis
- Testing: Filtered output for deterministic test execution
- Integration: Custom sinks for external monitoring and alerting systems
The logging framework integrates with CloudZero Agent operational monitoring, providing the observability foundation for debugging, performance analysis, and compliance reporting across all agent components and deployment environments.
Package logging provides structured logging infrastructure for CloudZero Agent operations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewFieldFilterWriter ¶
NewFieldFilterWriter creates a JSON log field filtering writer for CloudZero Agent logging. This constructor creates a writer that removes specified fields from JSON log events, enabling selective field filtering for security, privacy, and output customization.
Field filtering use cases:
- Security filtering: Remove authentication tokens, API keys, passwords
- Privacy protection: Filter user IDs, email addresses, personal information
- Trace cleanup: Remove tracing fields (spanId, parentSpanId) for cleaner output
- Environment filtering: Remove development-specific fields in production
- Volume reduction: Filter verbose fields to reduce log storage requirements
Parameters:
- w: Underlying writer for filtered output (stdout, files, external systems)
- fieldsToSkip: Field names to remove from JSON log events
Filtering behavior:
- Only affects JSON log events; non-JSON content passes through unchanged
- Preserves all other fields and log structure
- Maintains newline formatting for consistent output
- Thread-safe for concurrent logging operations
The returned writer implements io.Writer and can be used anywhere standard writers are accepted in the CloudZero Agent logging pipeline.
func NewLogger ¶
NewLogger creates a configured CloudZero Agent logger with comprehensive operational capabilities. This constructor applies functional options to build a Zerolog-based logger optimized for CloudZero Agent operational requirements including structured logging, multiple outputs, and consistent metadata injection.
Default configuration:
- Log level: Info (filters out debug and trace events)
- Output sink: Filtered stdout with sensitive field removal
- Version: Automatic detection from build information
- Timestamp: UTC timestamps for consistent time representation
- Caller information: File and line number for debugging
Configuration validation:
- All options are applied and validated during construction
- Invalid configurations return descriptive errors
- Partial failures prevent logger creation
- Default values ensure operational logger even with minimal configuration
Operational features:
- Multi-sink output: Simultaneous logging to multiple destinations
- Hook processing: Extensible event processing pipeline
- Attribute injection: Consistent metadata across all log events
- Context integration: Sets global context logger for request correlation
Error conditions:
- Invalid log level strings
- Failed option application
- Sink or hook configuration errors
Returns a fully configured Zerolog logger ready for CloudZero Agent operations, or an error describing configuration failures.
func StoreWriter ¶ added in v1.2.0
func StoreWriter( ctx context.Context, store types.WritableStore, clusterName string, cloudAccountID string, ) io.Writer
StoreWriter creates a CloudZero metric storage writer for log event integration. This constructor creates a writer that transforms structured log events into CloudZero metrics, enabling log data to be processed through the CloudZero cost allocation and analysis pipeline.
Integration benefits:
- Unified data pipeline: Log events stored alongside other CloudZero metrics
- Cost attribution: Log volume attributed to specific clusters and cloud accounts
- Operational insights: Log patterns integrated with CloudZero analytics
- Storage efficiency: Leverages CloudZero metric storage and compression
Parameters:
- ctx: Context for storage operations and lifecycle management
- store: WritableStore for CloudZero metric persistence
- clusterName: Kubernetes cluster identification for cost attribution
- cloudAccountID: Cloud provider account for billing correlation
The returned writer transforms every log event into a CloudZero metric with:
- Metric name: "log"
- Value: Log message content
- Labels: All log event fields as key-value pairs
- Timestamps: Preserved from original log events
- Context: Cluster and cloud account attribution
This enables CloudZero platform to analyze log patterns, volume, and costs alongside other infrastructure and application metrics.
Types ¶
type Attr ¶
Attr provides dynamic attribute injection for CloudZero Agent logger configuration. This function type enables flexible addition of contextual information to log events, supporting consistent metadata across different logging contexts and operational scenarios.
Attribute patterns:
- Service identification: Component names, versions, and deployment information
- Request correlation: Request IDs, trace IDs, and user contexts
- Operational context: Environment, region, and cluster information
- Business context: Customer IDs, cost allocation metadata
The function receives a zerolog.Context and returns an enhanced context with additional fields, enabling chainable attribute addition and flexible logger customization.
type LoggerOpt ¶
type LoggerOpt = func(logger *internalLogger) error
LoggerOpt defines functional options for CloudZero Agent logger configuration. This type enables flexible, validated logger setup through composable configuration functions that modify the internal logger state during construction.
The functional options pattern provides:
- Type safety: Compile-time validation of configuration options
- Composability: Multiple options can be combined and reused
- Error handling: Each option can validate and report configuration errors
- Extensibility: New options can be added without breaking existing code
Options modify the internalLogger during construction and return errors for invalid configurations, enabling robust logger setup with comprehensive validation.
func WithAttrs ¶
WithAttrs configures consistent attribute injection for all CloudZero Agent log events. This option enables automatic addition of contextual information to every log event, ensuring consistent metadata across all logging operations for operational visibility and correlation.
Attribute injection patterns:
- Service identification: Component names, service versions, deployment information
- Request correlation: Request IDs, trace IDs, session identifiers
- Operational context: Environment, region, cluster, namespace information
- Business context: Customer IDs, cost allocation metadata, resource identifiers
Example usage:
logger := NewLogger(
WithAttrs(
func(ctx zerolog.Context) zerolog.Context {
return ctx.Str("component", "webhook-controller").
Str("environment", "production").
Str("cluster", "us-west-2")
},
),
)
Multiple attribute functions:
- Multiple Attr functions can be provided to this single call
- Functions are applied in order to build cumulative context
- Later functions can reference fields added by earlier functions
- All attributes are added to every log event automatically
Performance considerations:
- Attribute functions execute for every log event
- Keep attribute logic simple and efficient
- Consider caching expensive computations
- Avoid I/O operations within attribute functions
func WithHook ¶
WithHook adds a processing hook to the CloudZero Agent logging pipeline. This option enables custom log event processing, transformation, and routing for advanced logging requirements including external system integration and custom formatting.
Hook capabilities:
- Event filtering: Custom logic for conditional log event processing
- Field transformation: Modify or enhance log event fields
- External routing: Send specific events to external systems
- Compliance processing: Add regulatory or audit-specific information
- Performance monitoring: Track logging performance and patterns
Common hook use cases:
- Security filtering: Remove sensitive information from log events
- Alerting integration: Forward critical events to alerting systems
- Audit compliance: Add regulatory metadata for compliance requirements
- Performance tracking: Measure and report logging performance metrics
- Custom formatting: Apply organization-specific log formatting
Multiple hooks support:
- This function can be called multiple times to add multiple hooks
- Hooks are executed in the order they are added
- Hook failures do not prevent log event processing
- Each hook receives the log event independently
Hooks execute synchronously and should be designed for minimal performance impact.
func WithLevel ¶
WithLevel configures the minimum log level for CloudZero Agent logger output filtering. This option enables appropriate verbosity control across different deployment environments, optimizing performance and ensuring suitable log output for development and production.
Supported log levels (from most to least verbose):
- "trace": Detailed execution flow for deep debugging
- "debug": Development debugging information
- "info": General operational information (default)
- "warn": Warning conditions that should be noted
- "error": Error conditions requiring attention
- "fatal": Critical errors causing application termination
- "panic": Panic conditions with stack traces
Level selection guidelines:
- Development: "debug" or "trace" for comprehensive debugging
- Testing: "warn" or "error" to reduce noise
- Production: "info" for operational visibility
- Troubleshooting: Temporarily lower levels for issue diagnosis
Returns an error if the level string is not recognized or valid.
func WithSink ¶
WithSink adds an output destination for CloudZero Agent log events. This option enables simultaneous log output to multiple destinations including console output, files, and external logging systems for comprehensive observability.
Common sink configurations:
- os.Stdout: Console output for development and container logging
- File writers: Persistent log files for audit and analysis
- Network writers: Integration with external logging systems
- Filtered writers: Custom filtering and formatting for specific requirements
Multiple sinks support:
- This function can be called multiple times to add multiple output destinations
- All sinks receive identical log events simultaneously
- Each sink can apply independent filtering and formatting
- Failed sinks do not affect other sink operations
Operational benefits:
- Console output for real-time monitoring during development
- File output for persistent storage and analysis
- External system integration for centralized logging and alerting
- Backup logging destinations for reliability
The sink receives all log events that pass the configured log level threshold.
func WithVersion ¶
WithVersion specifies custom version information for CloudZero Agent log events. This option overrides the default version from the build library, enabling custom version identification for special deployments, development builds, or testing scenarios.
Version information usage:
- Log correlation: Track issues across different agent versions
- Debugging support: Identify version-specific behaviors and bugs
- Operational monitoring: Monitor version distribution across deployments
- Compliance tracking: Maintain version audit trails for regulatory requirements
Default behavior:
- If not specified, version is automatically retrieved from build.GetVersion()
- Build version includes Git commit, build time, and release information
- Production deployments typically use automatic version detection
Custom version scenarios:
- Development builds: Custom identifiers for local development
- Testing environments: Test-specific version markers
- Special deployments: Custom deployment identifiers
- Integration testing: Version markers for test correlation
The version appears in all log events as a consistent field for operational visibility.
Source Files
Directories