{"id":2166,"library":"opentelemetry-instrumentation-sqlite3","title":"OpenTelemetry SQLite3 Instrumentation","description":"This library provides automatic instrumentation for the Python `sqlite3` module, enabling distributed tracing for database operations within applications. It's part of the `opentelemetry-python-contrib` repository, which follows a frequent release cadence, often aligning with core OpenTelemetry Python releases, with the current version being 0.62b0.","status":"active","version":"0.62b0","language":"python","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","instrumentation","sqlite3","database","tracing","observability"],"install":[{"cmd":"pip install opentelemetry-instrumentation-sqlite3","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"Required for core OpenTelemetry API functionality (e.g., TracerProvider).","package":"opentelemetry-api"},{"reason":"Provides standard attribute names and values for database spans.","package":"opentelemetry-semantic-conventions"},{"reason":"Base classes and utilities for instrumentations.","package":"opentelemetry-instrumentation"}],"imports":[{"note":"This is the main class to enable SQLite3 instrumentation.","symbol":"SQLite3Instrumentor","correct":"from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor"}],"quickstart":{"code":"import sqlite3\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor\n\n# 1. Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"sqlite3-example\"})\nprovider = TracerProvider(resource=resource)\nexporter = ConsoleSpanExporter()\nprocessor = SimpleSpanProcessor(exporter)\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument SQLite3 BEFORE making any connections\nSQLite3Instrumentor().instrument()\n\n# 3. Perform SQLite3 operations\nprint(\"\\nPerforming SQLite3 operations...\")\nconn = sqlite3.connect(':memory:')\ncursor = conn.cursor()\n\ncursor.execute(\"CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)\")\ncursor.execute(\"INSERT INTO users (name) VALUES ('Alice')\")\ncursor.execute(\"INSERT INTO users (name) VALUES ('Bob')\")\nconn.commit()\n\ncursor.execute(\"SELECT * FROM users\")\nfor row in cursor.fetchall():\n    print(f\"  Fetched: {row}\")\n\ncursor.close()\nconn.close()\nprint(\"SQLite3 operations complete. Check console for traces.\\n\")\n","lang":"python","description":"This quickstart demonstrates how to set up the OpenTelemetry SDK with a console exporter and then enable SQLite3 instrumentation. It's crucial to call `SQLite3Instrumentor().instrument()` before any `sqlite3.connect()` calls or module interactions to ensure all operations are traced. The example performs basic table creation, data insertion, and selection."},"warnings":[{"fix":"Refer to release notes for potential breaking changes when upgrading beta versions.","message":"The package version (e.g., `0.62b0`) includes a 'b', indicating it's a beta release. While generally stable, minor API changes might occur in future beta versions before a stable `1.0.0` release.","severity":"gotcha","affected_versions":"All versions marked with 'b' (beta)."},{"fix":"Call `SQLite3Instrumentor().instrument()` at the very beginning of your application's lifecycle, typically alongside other OpenTelemetry SDK configurations.","message":"Instrumentation must be enabled *before* establishing any `sqlite3` connections or interacting with the `sqlite3` module. Connections made prior to `SQLite3Instrumentor().instrument()` will not be traced.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you initialize a `TracerProvider`, add at least one `SpanProcessor` (e.g., `SimpleSpanProcessor` or `BatchSpanProcessor`), and configure an `SpanExporter` (e.g., `ConsoleSpanExporter`, `OTLPSpanExporter`) as part of your application's setup.","message":"Traces will not be exported or visible without a configured OpenTelemetry `TracerProvider`, `SpanProcessor`, and `SpanExporter`. The instrumentation only generates spans; the SDK is responsible for their processing and export.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always obtain a cursor object using `connection.cursor()` and perform operations via the cursor: `cursor.execute(...)`.","message":"To ensure tracing support for database operations, cursor objects must be explicitly initialized. Direct usage of `connection.execute()` without an explicit cursor might not be fully traced in some scenarios.","severity":"gotcha","affected_versions":"All versions prior to 1.x.x"}],"env_vars":null,"search_vec":"'0.62':50 'align':39 'applic':21 'automat':7 'b0':51 'cadenc':37 'contrib':30 'core':41 'current':47 'databas':18,55 'distribut':15 'enabl':14 'follow':33 'frequent':35 'instrument':3,8,53 'librari':5 'modul':13 'observ':57 'often':38 'opentelemetri':1,28,42,52 'opentelemetry-python-contrib':27 'oper':19 'part':24 'provid':6 'python':11,29,43 'releas':36,44 'repositori':31 'sqlite3':2,12,54 'trace':16,56 'version':48 'within':20","created_at":"2026-04-09T18:46:20.617173+00:00","updated_at":"2026-04-16T17:44:04.106613+00:00","problems":[{"fix":"Install the necessary system-level development packages for SQLite (e.g., `sqlite-devel` on CentOS/RHEL, `libsqlite3-dev` on Debian/Ubuntu, `build-base` and `sqlite-dev` on Alpine) and ensure Python is built or reinstalled with these dependencies available. For example: `sudo apt-get install libsqlite3-dev` and then potentially reinstalling Python or the `sqlite3` module if it was custom-built.","cause":"This error occurs when the underlying C library for Python's `sqlite3` module is missing or incorrectly linked in the environment, often in containerized setups or minimal Linux distributions where Python development headers are not installed.","error":"ModuleNotFoundError: No module named '_sqlite3'"},{"fix":"Ensure `SQLite3Instrumentor().instrument()` is called early in your application's lifecycle to patch all `sqlite3` connections, or explicitly instrument individual connections using `instrumented_connection = SQLite3Instrumentor().instrument_connection(conn)`. When using the instrumented connection, ensure you obtain cursors from it, e.g., `cursor = instrumented_connection.cursor()`.","cause":"This indicates that database operations performed using a standard `sqlite3.Cursor` object are not generating traces because the instrumentation has not correctly wrapped the cursor's methods or the connection itself was not properly instrumented prior to cursor creation.","error":"Default SQLite3 cursor is not instrumented"},{"fix":"Update all `opentelemetry` related packages to their latest compatible versions. Ensure consistency across `opentelemetry-api`, `opentelemetry-sdk`, and all `opentelemetry-instrumentation-*` packages being used. It's often best to upgrade them simultaneously.","cause":"This `AttributeError` typically arises from version incompatibilities between different OpenTelemetry Python packages (e.g., `opentelemetry-api`, `opentelemetry-sdk`, and various instrumentation packages). The API for accessing trace context might have changed or been refactored between releases.","error":"AttributeError: 'Context' object has no attribute 'trace_id'"},{"fix":"Verify that `SQLite3Instrumentor().instrument()` is called. If instrumenting individual connections, ensure the `instrument_connection` method is used and that cursors are created from the *instrumented* connection. Additionally, confirm that a `TracerProvider` is configured and an exporter is set up to send telemetry data.","cause":"This is a common observation when instrumentation is active, but no traces or spans are appearing for expected database operations, often due to incorrect initialization or specific patterns of SQLite usage that the instrumentor doesn't automatically cover.","error":"span was not created"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.65b0","cli_name":"","cli_version":null,"type":"library","homepage":"https://opentelemetry.io","github":"https://github.com/open-telemetry/opentelemetry-python-contrib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opentelemetry-instrumentation-sqlite3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}