OpenTelemetry Cassandra Instrumentation

0.62b0 · active · verified Sat Apr 11

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.

Warnings

beta This 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.
gotcha The 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.
gotcha By 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.

Install

pip install opentelemetry-instrumentation-cassandra opentelemetry-sdk cassandra-driver Install with Cassandra driver

Imports

CassandraInstrumentor

from opentelemetry.instrumentation.cassandra import CassandraInstrumentor

Quickstart

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.")

view raw JSON →