freelruotel

freelru-otel

OpenTelemetry instrumentation for elastic/go-freelru LRU cache implementations.

Features

• Universal Instrumentation: Works with freelru.LRU, freelru.SyncedLRU and freelru.ShardedLRU
• OpenTelemetry Integration: Automatic metrics export for cache performance monitoring
• Low Overhead: Uses OpenTelemetry Observable Counter callbacks for efficient metrics collection
• Non-intrusive: Metrics collection doesn't impact cache performance

Installation

go get github.com/sweet-tv/freelru-otel

Usage

Basic Usage with freelru.LRU

package main

import (
    "github.com/cespare/xxhash/v2"
    "github.com/elastic/go-freelru"
    "github.com/sweet-tv/freelru-otel"
)

func hashString(s string) uint32 {
    return uint32(xxhash.Sum64String(s))
}

func main() {
    // Create a single-threaded LRU cache
    cache, err := freelru.New[string, string](100, hashString)
    if err != nil {
        panic(err)
    }

    // Instrument the cache (this starts collecting metrics)
    err = freelruotel.InstrumentCache(cache, "my_cache")
    if err != nil {
        panic(err)
    }

    // Use the cache normally
    cache.Add("key1", "value1")
    if value, ok := cache.Get("key1"); ok {
        // Metrics are automatically collected
    }
}

Usage with SyncedLRU

// Create a SyncedLRU cache for thread safety
cache, err := freelru.NewSynced[string, string](100, hashString)
if err != nil {
    panic(err)
}

// Instrument the cache
err = freelruotel.InstrumentCache(cache, "synced_cache")
if err != nil {
    panic(err)
}

// Use cache normally - metrics are collected automatically
cache.Add("key1", "value1")
cache.Get("key1")

Usage with ShardedLRU

// Create a ShardedLRU cache for high concurrency
cache, err := freelru.NewSharded[string, string](1024, hashString)
if err != nil {
    panic(err)
}

// Instrument the cache
err = freelruotel.InstrumentCache(cache, "high_perf_cache")
if err != nil {
    panic(err)
}

// Use cache normally - metrics are collected automatically
cache.Add("key1", "value1")
cache.Get("key1")

Using Custom MeterProvider

// Create custom MeterProvider
provider := metric.NewMeterProvider()

// Create a cache
cache, err := freelru.NewSynced[string, string](100, hashString)
if err != nil {
    panic(err)
}

// Instrument the cache with custom MeterProvider
err = freelruotel.InstrumentCache(cache, "my_cache", 
    freelruotel.WithMeterProvider(provider))
if err != nil {
    panic(err)
}

Exported Metrics

The instrumentation automatically exports the following OpenTelemetry metrics:

All metrics include the cache_name attribute to distinguish between different cache instances.

Requirements

• Go 1.22+
• OpenTelemetry configured in your application

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.