Skip to content

Glaber ValueCache Documentation

Overview

This directory contains comprehensive documentation for the Glaber ValueCache system, an intelligent in-memory caching solution for monitoring data.

Available Documentation

User Guide / Руководство пользователя (Russian)

Target Audience: System Administrators, DevOps Engineers, Monitoring Users

Contents: - What is ValueCache and why use it - Configuration parameters and tuning - Understanding cache behavior - Performance optimization strategies
- Troubleshooting common issues - Best practices for production deployments - Comparison with standard Zabbix caching

When to Read: - Setting up a new Glaber installation - Tuning performance for your environment - Troubleshooting cache-related issues - Understanding monitoring query performance

Programmer's Guide

Target Audience: Software Developers, System Architects, Contributors

Contents: - Complete architecture overview - Detailed component descriptions - Algorithm explanations with examples - Data structures and memory management - API reference with code examples - Integration points and extension mechanisms - Testing strategies - Common pitfalls and debugging techniques

When to Read: - Contributing to Glaber development - Integrating ValueCache into other systems - Debugging cache-related code issues - Extending or modifying cache functionality - Understanding internal implementation details

Quick Reference

Key Concepts

Concept Description
Raw Cache Stores recent, high-resolution monitoring data
Downsampled Cache Stores older data in aggregated form to save memory
Demand Tracking System learns usage patterns and optimizes cache allocation
Two-Tier Architecture Combines raw and downsampled caches for optimal performance

Configuration Quick Start

Minimal Configuration (defaults work for most cases): 

ValueCacheSize=256M

High-Frequency Monitoring (1-second intervals): 

ValueCacheSize=1G
ValueCacheMaxDuration=604800        # 7 days
ValueCacheDefaultElements=100

Standard Monitoring (30-60 second intervals): 

ValueCacheSize=256M
ValueCacheMaxDuration=172800        # 2 days
ValueCacheDefaultElements=10

Common Operations

Task Where to Look
Configure cache size User Guide → Configuration Parameters
Tune for performance User Guide → Performance Optimization
Fix high memory usage User Guide → Troubleshooting
Understand fetch algorithm Programmer's Guide → Key Algorithms
Add new aggregation function Programmer's Guide → Future Enhancements
Debug cache behavior Programmer's Guide → Debugging

Architecture at a Glance

┌─────────────────────────────────────────────┐
│         items_valuecache (per item)         │
├─────────────────────────────────────────────┤
│                                             │
│  ┌───────────────────┐  ┌─────────────┐   │
│  │   Raw Cache       │  │   Demand    │   │
│  │   (Recent Data)   │  │  Tracking   │   │
│  │                   │  │             │   │
│  │ • Full Resolution │  │ • Count     │   │
│  │ • Fast Access     │  │ • Period    │   │
│  │ • DB Fetch        │  │ • Timeshift │   │
│  └───────────────────┘  └─────────────┘   │
│                                             │
│  ┌───────────────────┐                     │
│  │ Downsampled Cache │                     │
│  │  (Historical)     │                     │
│  │                   │                     │
│  │ • Aggregated      │                     │
│  │ • Memory Efficient│                     │
│  │ • Trends Support  │                     │
│  └───────────────────┘                     │
└─────────────────────────────────────────────┘

Data Flow

New Monitoring Value
        ↓
   Raw Cache (add)
        ↓
  [Enough old data?]
        ↓ YES
   Downsample old data
        ↓
  Downsampled Cache
        ↓
    Cleanup (demand-based)

Query Flow

User/API Request
        ↓
  [Data in cache?]
        ↓ NO              ↓ YES
   Fetch from DB     [Recent or old?]
        ↓                  ↓
   Populate cache    Recent → Raw Cache
        ↓             Old → Downsampled
   Return data      
        ↓
   Update demand

Features Summary

User-Facing Features

✓ Automatic memory management
✓ Intelligent demand learning
✓ Fast query response
✓ Minimal configuration required
✓ Database load reduction
✓ Cache persistence across restarts
✓ On-demand trend aggregation

Developer Features

✓ Modular architecture
✓ Extensible design
✓ Custom memory allocators
✓ JSON serialization
✓ Thread-safe compatible
✓ Comprehensive debugging

Performance Characteristics

Memory Efficiency

  • Raw Cache: ~16 bytes per numeric value, variable for strings
  • Downsampled Cache: ~16 bytes per aggregated hour (3600 values)
  • Compression Ratio: Up to 3600:1 for old data

Query Performance

  • Cache Hit: Sub-millisecond response
  • Cache Miss: Database fetch + cache population
  • Typical Hit Rate: >90% for active items

Scalability

  • Items: Scales to millions of items
  • Values per Item: Adapts based on demand (10 to 10,000+)
  • Memory: Linear scaling with cache size configuration

Version Information

This documentation describes the ValueCache implementation in Glaber (Zabbix fork).

Compatibility

  • Glaber Version: 7.x and later
  • Based on: Zabbix 7.x architecture
  • Language: C++ with C integration
  • Zabbix Documentation: For general monitoring concepts
  • Glaber ChangeLog: For version-specific changes (ChangeLog.glaber)
  • Source Code: src/libs/glb_state/glb_state_valuecache.*

Getting Help

For Users

  1. Check the User Guide for configuration and troubleshooting
  2. Review log files with DebugLevel=4 for detailed information
  3. Check cache statistics via internal API

For Developers

  1. Read the Programmer's Guide for architecture details
  2. Review source code with inline comments
  3. Run unit tests in src/libs/glb_state/tests/
  4. Use debug macros (DEBUG_ITEM) for instrumentation

Contributing

When contributing to ValueCache:

  1. Read the Programmer's Guide thoroughly
  2. Understand the demand tracking mechanism
  3. Test with various usage patterns
  4. Document new features or changes
  5. Follow existing code style and patterns

License

Copyright Glaber. Licensed under GNU General Public License v2.0.

See source file headers for complete license information.

Last Updated: 2025
Authors: Glaber Development Team
Maintainer: See project contributors