Dalli

Dalli is a high performance pure Ruby client for accessing memcached servers.

Dalli supports:

Simple and complex memcached configurations
Failover between memcached instances
Fine-grained control of data serialization and compression
Thread-safe operation (either through use of a connection pool, or by using the Dalli client in threadsafe mode)
SSL/TLS connections to memcached
OpenTelemetry distributed tracing (automatic when SDK is present)

The name is a variant of Salvador Dali for his famous painting The Persistence of Memory.

Requirements

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

Configuration Options

Namespace

Use namespaces to partition your cache and avoid key collisions between different applications or environments:

# All keys will be prefixed with "myapp:"
Dalli::Client.new('localhost:11211', namespace: 'myapp')

# Dynamic namespace using a Proc (evaluated on each operation)
Dalli::Client.new('localhost:11211', namespace: -> { "tenant:#{Thread.current[:tenant_id]}" })

Namespace Separator

By default, the namespace and key are joined with a colon (:). You can customize this with the namespace_separator option:

# Keys will be prefixed with "myapp/" instead of "myapp:"
Dalli::Client.new('localhost:11211', namespace: 'myapp', namespace_separator: '/')

The separator must be a single non-alphanumeric character. Valid examples: :, /, |, ., -, _, #

Security Note

By default, Dalli uses Ruby's Marshal for serialization. Deserializing untrusted data with Marshal can lead to remote code execution. If you cache user-controlled data, consider using a safer serializer:

Dalli::Client.new('localhost:11211', serializer: JSON)

See the 5.0-Upgrade.md guide for upgrade information.

OpenTelemetry Tracing

Dalli automatically instruments operations with OpenTelemetry when the SDK is present. No configuration is required - just add the OpenTelemetry gems to your application:

# Gemfile
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp' # or your preferred exporter

When OpenTelemetry is loaded, Dalli creates spans for:

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

All spans include:

db.system: memcached
db.operation: The operation name (e.g., get, set_multi)

Single-key operations also include:

server.address: The memcached server that handled the request (e.g., localhost:11211)

Multi-key operations include cache efficiency metrics:

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)

Error Handling

Exceptions are automatically recorded on spans with error status. When an operation fails:

The exception is recorded on the span via span.record_exception(e)
The span status is set to error with the exception message
The exception is re-raised to the caller

Zero Overhead

When OpenTelemetry is not present, there is zero overhead - the tracing code checks once at startup and bypasses all instrumentation logic entirely when the SDK is not loaded.

Persistence of Memory

Documentation and Information

User Documentation - The documentation is maintained in the repository's wiki.
Announcements - Announcements of interest to the Dalli community will be posted here.
Bug Reports - If you discover a problem with Dalli, please submit a bug report in the tracker.
Forum - If you have questions about Dalli, please post them here.
Client API - Ruby documentation for the Dalli::Client API

Development

After checking out the repo, run bin/setup to install dependencies. You can run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

If you have a fix you wish to provide, please fork the code, fix in your local project and then send a pull request on github. Please ensure that you include a test which verifies your fix and update the changelog with a one sentence description of your fix so you get credit as a contributor.

Appreciation

Dalli would not exist in its current form without the contributions of many people. But special thanks go to several individuals and organizations:

Mike Perham - for originally authoring the Dalli project and serving as maintainer and primary contributor for many years
Eric Wong - for help using his kgio library.
Brian Mitchell - for his remix-stash project which was helpful when implementing and testing the binary protocol support.
CouchBase - for their sponsorship of the original development

Authors

Peter M. Goldstein - current maintainer
Mike Perham and contributors