OpenTelemetry Tracing

Dalli includes built-in OpenTelemetry instrumentation. When the OpenTelemetry SDK is loaded in your application, Dalli automatically creates spans for cache operations. When OpenTelemetry is not available, all tracing is a no-op with zero overhead.

Setup

No Dalli-specific setup is required. If opentelemetry-sdk is loaded in your application, Dalli will detect it and begin tracing automatically. Dalli registers itself as a tracer named dalli with the current Dalli::VERSION.

# Gemfile
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'dalli'

# config/initializers/opentelemetry.rb (Rails example)
require 'opentelemetry/sdk'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-app'
end

That's it. Dalli will automatically create spans for all cache operations.

Span Attributes

All spans include db.system.name: "memcached" by default.

Single-key operations

Operations like get, set, delete, add, replace, incr, decr, gat, touch, append, prepend, get_with_metadata, and fetch_with_lock include:

Attribute	Description	Example
db.operation.name	The operation name	"get"
server.address	The server hostname	"localhost"
server.port	The server port (integer, omitted for Unix sockets)	11211

Multi-key operations

get_multi includes:

Attribute	Description
db.operation.name	"get_multi"
db.memcached.key_count	Number of keys requested
db.memcached.hit_count	Number of keys found in cache
db.memcached.miss_count	Number of keys not found

set_multi and delete_multi include:

Attribute	Description
db.operation.name	The operation name
db.memcached.key_count	Number of keys in the operation

Optional Attributes

Two client options control additional span attributes:

otel_db_statement

Controls the db.query.text span attribute, which shows the operation and key(s):

Value	Behavior	Example
nil (default)	Attribute omitted	—
:obfuscate	Keys replaced with ?	"get ?"
:include	Full statement with keys	"get user:123"

Dalli::Client.new('localhost:11211', otel_db_statement: :obfuscate)

otel_peer_service

Sets a peer.service span attribute for logical service naming in distributed traces:

Dalli::Client.new('localhost:11211', otel_peer_service: 'session-cache')

Error Handling

When an exception occurs during a traced operation, OpenTelemetry's in_span method automatically records the exception on the span and sets the span status to error. The exception is then re-raised to the caller.

Checking if Tracing is Active

Dalli::Instrumentation.enabled? # => true if OpenTelemetry is loaded