DOCSEARCHbyAlgolia
Submit Docs

Dalli Documentation

repository·main·Indexed 25 days ago

https://github.com/petergoldstein/dalli

A high-performance, pure Ruby client for Memcached. Dalli supports failover, thread-safety, SSL/TLS, and automatic OpenTelemetry instrumentation. It provides advanced features such as namespacing, secure JSON serialization, and thundering herd protection via fetch_with_lock. Version 5.0 requires Ruby 3.3+ and memcached 1.6+, transitioning exclusively to the meta protocol and removing support for the binary protocol and SASL authentication.

Tokens
5.7K
Snippets
15
Records
59
Agent score
81%

What's inside Dalli

  1. Install and use Dalli

    main

    Dalli is a high-performance pure Ruby client for accessing memcached servers. It supports complex configurations, failover, thread-safe operation, SSL/TLS, and OpenTelemetry tracing.

    Requirements

    • Ruby 3.3 or later (JRuby is also supported)
    • memcached 1.6 or later

  3. Observe Dalli errors using OpenTelemetry

    main
    For error visibility and observability, it is recommended to use OpenTelemetry (OTel) instead of the deprecated instrument_errors parameter. Dalli 4.2.0+ includes OpenTelemetry support which automatically records errors on spans.

  4. Migrate from :dalli_store to :mem_cache_store

    main
    In Dalli 3.0, the :dalli_store option has been removed. To maintain compatibility with Rails, you must migrate to the official Rails :mem_cache_store. Refer to the Rails caching guide for implementation details.

  5. Run local performance benchmarks

    main

    To view current performance benchmarks for Dalli on your local environment, use the provided Rake task. Note that the historical data in the documentation is outdated and the kgio gem is no longer required for modern Ruby versions.

    bundle exec rake bench

  6. Enable OpenTelemetry tracing

    main

    Dalli automatically instruments operations with OpenTelemetry when the SDK is present. No manual configuration is required; simply add the OpenTelemetry gems to your Gemfile.

    Supported Operations

    • Single key operations: get, set, delete, add, replace, incr, decr, etc.
    • Multi-key operations: get_multi, set_multi, delete_multi
    • Advanced operations: get_with_metadata, fetch_with_lock

    Span Attributes

    • db.system: memcached
    • db.operation: The operation name (e.g., get, set_multi)
    • server.address: The memcached server address (for single-key operations)
    • db.memcached.key_count: Number of keys in the request
    • db.memcached.hit_count: Number of keys found (for get_multi)
    • db.memcached.miss_count: Number of keys not found (for get_multi)
    # Gemfile
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp' # or your preferred exporter

  7. Upgrade to Dalli 5.0

    main
    Dalli 5.0 is a major version update that introduces several breaking changes. To upgrade, you must ensure your environment meets the new requirements and remove deprecated options related to the binary protocol and SASL authentication.

  12. Migrate to Dalli v5.0 (Breaking Changes)

    main

    Upgrading to Dalli v5.0 involves several breaking changes that require architectural adjustments:

    • Binary Protocol Removal: The binary protocol is no longer supported. Dalli now uses the meta protocol exclusively.
    • SASL Authentication Removal: The meta protocol does not support SASL authentication. If your application requires authentication, you must use one of the following alternatives:
      • Network-level security (e.g., VPN, firewall rules).
      • Memcached's TLS support.
      • Stay on Dalli 4.x (which supports the binary protocol).
    • Minimum Requirements Update:
      • Ruby: Requires Ruby 3.3+.
      • Memcached: Requires memcached 1.6+ (the minimum version for the meta protocol).
    • JRuby Support: JRuby support is maintained, but it will continue to use a readfull fallback because JRuby lacks IO#timeout= support.