Cassandra Integration#
Jaeger's Cassandra storage backend lives under two primary paths:
internal/storage/cassandra/โ shared config, session abstraction, gocql wrapper, and schema utilities.internal/storage/v1/cassandra/โ the v1 storage API implementations: spanstore reader/writer, dependency store, sampling store, and theFactory.
The Factory wires everything together: it builds a cassandra.Session from the configuration via NewSession, which calls NewCluster โ cluster.CreateSession(). The cassandra.Session / Query / Iterator interfaces are thin abstractions over gocql, backed by CQLSession/CQLQuery/CQLIterator wrappers in the gocql sub-package.
Configuration#
The root type is config.Configuration, composed of three sub-structs:
| Sub-struct | Key fields |
|---|---|
Connection | Servers, LocalDC, Port, ProtoVersion, ConnectionsPerHost, ReconnectInterval, TLS, auth |
Schema | Keyspace, CreateSchema, TraceTTL, DependenciesTTL, ReplicationFactor, CompactionWindow |
Query | Timeout, MaxRetryAttempts, Consistency (string) |
Default values are set by DefaultConfiguration(): keyspace jaeger_dc1, datacenter dc1, TTLs 48 h, replication factor 1, Port 9042, ProtoVersion 4, ConnectionsPerHost 2, MaxRetryAttempts 3. ApplyDefaults copies non-zero values from a source config, used when merging primary and archive configurations.
NewCluster translates the config struct into a *gocql.ClusterConfig. Notable behaviors:
- If
Consistencyis empty, the cluster defaults togocql.LocalOne. - If
DisableAutoDiscoveryis set, bothDisableInitialHostLookupandIgnorePeerAddrare enabled . - Snappy compression is applied by default unless
Schema.DisableCompressionis set . - Token-aware host selection is always used, falling back to DC-aware round-robin if
LocalDCis set, otherwise plain round-robin .
Known Gap: ParseConsistency Panics on Invalid Input#
The Query.Consistency field is a free-form string . In NewCluster, when the string is non-empty it is passed directly to gocql.ParseConsistency:
cluster.Consistency = gocql.ParseConsistency(c.Query.Consistency)
gocql.ParseConsistency panics on an unrecognized string โ it does not return an error. The safer alternative, gocql.ParseConsistencyWrapper, returns (Consistency, error) and is the correct function to use here. Valid consistency level strings are: ANY, ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, SERIAL, LOCAL_SERIAL, LOCAL_ONE.
The Validate() method does not validate the Consistency string โ it only validates TTL durations and CompactionWindow via govalidator.ValidateStruct. This means an invalid consistency string passes Validate() and causes a panic later at session creation time inside NewCluster.
The test TestNewClusterWithOverrides passes "LOCAL_QUORUM" and asserts it maps to gocql.LocalQuorum , but there is no test covering an invalid consistency string.
Spanstore: Reader and Writer#
The span reader queries five Cassandra tables via CQL constants defined at the top of the file :
| Table | Query |
|---|---|
traces | Fetch spans by trace ID |
tag_index | Find trace IDs by tag (service + key + value + time range) |
service_name_index | Find trace IDs by service name |
service_operation_index | Find trace IDs by service + operation |
duration_index | Find trace IDs by duration bucket |
All index queries use ORDER BY start_time DESC LIMIT ?, returning the most-recent matching traces first .
Directory Map#
| Path | Purpose |
|---|---|
internal/storage/cassandra/config/config.go | Config structs, NewCluster, Validate, ApplyDefaults |
internal/storage/cassandra/session.go | Session, Query, Iterator interfaces; Consistency constants |
internal/storage/cassandra/gocql/gocql.go | gocql wrappers: CQLSession, CQLQuery, CQLIterator |
internal/storage/v1/cassandra/factory.go | Factory, NewSession, session lifecycle |
internal/storage/v1/cassandra/spanstore/reader.go | Span reader: CQL queries, index lookups, trace assembly |
internal/storage/v1/cassandra/spanstore/writer.go | Span writer |
internal/storage/cassandra/config/config_test.go | Config tests: validation, NewCluster, ApplyDefaults |