{"id":3195,"library":"opentelemetry-instrumentation-cassandra","title":"OpenTelemetry Cassandra Instrumentation","description":"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.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","cassandra","database","instrumentation","beta"],"install":[{"cmd":"pip install opentelemetry-instrumentation-cassandra opentelemetry-sdk cassandra-driver","lang":"bash","label":"Install with Cassandra driver"}],"dependencies":[{"reason":"Core OpenTelemetry SDK for trace management.","package":"opentelemetry-sdk"},{"reason":"Core OpenTelemetry API for instrumentation.","package":"opentelemetry-api"},{"reason":"Base package for OpenTelemetry Python instrumentations.","package":"opentelemetry-instrumentation"},{"reason":"Provides standard attribute names for telemetry data.","package":"opentelemetry-semantic-conventions"},{"reason":"A decorator for decorators, often used in Python instrumentation libraries.","package":"wrapt","optional":false},{"reason":"The Python driver for Apache Cassandra that this instrumentation targets.","package":"cassandra-driver","optional":true},{"reason":"The Python driver for ScyllaDB that this instrumentation also targets.","package":"scylla-driver","optional":true}],"imports":[{"symbol":"CassandraInstrumentor","correct":"from opentelemetry.instrumentation.cassandra import CassandraInstrumentor"}],"quickstart":{"code":"from opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.cassandra import CassandraInstrumentor\nfrom cassandra.cluster import Cluster, ConsistencyLevel\nimport os\n\n# 1. Configure OpenTelemetry SDK\n# For production, use an OTLPSpanExporter or other suitable exporter\nprovider = TracerProvider()\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument the Cassandra driver\nCassandraInstrumentor().instrument()\n\n# 3. Use the Cassandra driver as usual\n# Replace with your Cassandra connection details\ncassandra_contact_points = os.environ.get('CASSANDRA_CONTACT_POINTS', '127.0.0.1').split(',')\ncluster = Cluster(cassandra_contact_points)\nsession = cluster.connect()\n\ntry:\n    print(\"Executing Cassandra operations...\")\n    session.execute(\"CREATE KEYSPACE IF NOT EXISTS mykeyspace WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 }\")\n    session.execute(\"USE mykeyspace\")\n    session.execute(\"CREATE TABLE IF NOT EXISTS users (id uuid PRIMARY KEY, name text, age int)\")\n\n    # Insert data\n    session.execute(\"INSERT INTO users (id, name, age) VALUES (uuid(), 'Jane Doe', 25)\", consistency_level=ConsistencyLevel.QUORUM)\n    print(\"Inserted 'Jane Doe'.\")\n\n    # Select data\n    rows = session.execute(\"SELECT * FROM users WHERE name = 'Jane Doe'\")\n    for row in rows:\n        print(f\"Retrieved: {row.name}, {row.age}\")\n\n    # Update data\n    session.execute(\"UPDATE users SET age = 26 WHERE name = 'Jane Doe'\")\n    print(\"Updated 'Jane Doe's age.\")\n\n    # Select all data again to see update\n    rows = session.execute(\"SELECT * FROM users ALLOW FILTERING\")\n    print(\"All users:\")\n    for row in rows:\n        print(f\"  {row.name}, {row.age}\")\n\nfinally:\n    session.shutdown()\n    cluster.shutdown()\n    print(\"Cassandra session and cluster shut down.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Monitor `opentelemetry-python-contrib` release notes for breaking changes and migrate as necessary. Consider pinning to specific minor versions if stability is critical.","message":"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.","severity":"beta","affected_versions":"All versions below 1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions below 1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}