Registry / observability / opentelemetry-instrumentation-cassandra

opentelemetry-instrumentation-cassandra

JSON →
library0.65b0pypypi✓ verified 29d ago

This library provides automatic OpenTelemetry tracing instrumentation for Python applications using the `cassandra-driver` and `scylla-driver` libraries to interact with Apache Cassandra. It captures database operations as spans, providing visibility into query execution, latency, and errors within a distributed tracing context. The package is part of the `opentelemetry-python-contrib` project, currently in a beta release phase, and aims to offer high-quality, ubiquitous, and portable telemetry for Cassandra interactions.

pip install opentelemetry-instrumentation-cassandra opentelemetry-sdk cassandra-driver
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-cassandra
observabilitypythonv0.65b0
Install
3.2s avg
Import
467ms
Disk
33MB
Pass rate
6/ 10
Env Coverage6 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 3.3s
py 3.11
✕ build_error
✓ 3.1s
py 3.12
✕ build_error
✓ 2.9s
py 3.13
✕ build_error
✓ 2.8s
py 3.9
✓ —
✓ 3.8s
33MB installed
● package 33MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CassandraInstrumentor
✓ from opentelemetry.instrumentation.cassandra import CassandraInstrumentor

This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter, enable Cassandra instrumentation, and then perform basic Cassandra operations. The `CassandraInstrumentor().instrument()` call automatically wraps `cassandra-driver` methods to create spans for database interactions. Ensure a Cassandra instance is running and accessible at the specified contact points.

from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor from opentelemetry.instrumentation.cassandra import CassandraInstrumentor from cassandra.cluster import Cluster, ConsistencyLevel import os # 1. Configure OpenTelemetry SDK # For production, use an OTLPSpanExporter or other suitable exporter provider = TracerProvider() processor = SimpleSpanProcessor(ConsoleSpanExporter()) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # 2. Instrument the Cassandra driver CassandraInstrumentor().instrument() # 3. Use the Cassandra driver as usual # Replace with your Cassandra connection details cassandra_contact_points = os.environ.get('CASSANDRA_CONTACT_POINTS', '127.0.0.1').split(',') cluster = Cluster(cassandra_contact_points) session = cluster.connect() try: print("Executing Cassandra operations...") session.execute("CREATE KEYSPACE IF NOT EXISTS mykeyspace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 }") session.execute("USE mykeyspace") session.execute("CREATE TABLE IF NOT EXISTS users (id uuid PRIMARY KEY, name text, age int)") # Insert data session.execute("INSERT INTO users (id, name, age) VALUES (uuid(), 'Jane Doe', 25)", consistency_level=ConsistencyLevel.QUORUM) print("Inserted 'Jane Doe'.") # Select data rows = session.execute("SELECT * FROM users WHERE name = 'Jane Doe'") for row in rows: print(f"Retrieved: {row.name}, {row.age}") # Update data session.execute("UPDATE users SET age = 26 WHERE name = 'Jane Doe'") print("Updated 'Jane Doe's age.") # Select all data again to see update rows = session.execute("SELECT * FROM users ALLOW FILTERING") print("All users:") for row in rows: print(f" {row.name}, {row.age}") finally: session.shutdown() cluster.shutdown() print("Cassandra session and cluster shut down.")
Debug
Known issues
betaThis library is currently in a beta state (version 0.62b0). While functional, it may introduce breaking changes in future releases without adhering strictly to semantic versioning until it reaches a stable (1.0.0) release. Users should be prepared for potential API changes.
fix
Monitor `opentelemetry-python-contrib` release notes for breaking changes and migrate as necessary. Consider pinning to specific minor versions if stability is critical.
affects: All versions below 1.0.0
gotchaThe OpenTelemetry project is actively migrating to stable semantic conventions for attribute naming (e.g., `db.system` instead of `db.type`). Depending on your OpenTelemetry SDK version and configuration, the Cassandra instrumentation might emit older (v1.7.0) or newer semantic conventions. This can affect how traces appear in your observability backend.
fix
To explicitly opt into new semantic conventions, set the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database/dup`. This will emit both old and new attributes, allowing a graceful migration. Consult the OpenTelemetry semantic conventions documentation for the latest attribute names.
affects: All versions below 1.0.0
gotchaBy default, the instrumentation does not include the full database query text (`db.statement`) in spans to avoid exposing sensitive information. If `enhancedDatabaseReporting` is enabled, the full query string (potentially containing sensitive data) will be added to spans.
fix
Exercise caution when enabling `enhancedDatabaseReporting`. Only enable it if you are confident that sensitive data will not be inadvertently exposed through your tracing backend or if appropriate sanitization is in place. Refer to the instrumentation's options for configuring this behavior.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-sdkrequiredCore OpenTelemetry SDK for trace management.
opentelemetry-apirequiredCore OpenTelemetry API for instrumentation.
opentelemetry-instrumentationrequiredBase package for OpenTelemetry Python instrumentations.
opentelemetry-semantic-conventionsrequiredProvides standard attribute names for telemetry data.
wraptrequiredA decorator for decorators, often used in Python instrumentation libraries.
cassandra-driveroptionalThe Python driver for Apache Cassandra that this instrumentation targets.
scylla-driveroptionalThe Python driver for ScyllaDB that this instrumentation also targets.
Agent activity
16 hits · last 30 days
node
12
OpenAI (training)
1
Resources
opentelemetry-instrumentation-cassandra — pip install opentelemetry-instrumentation-cassandra · libregistry