Registry / observability / opentelemetry-instrumentation-sqlite3

opentelemetry-instrumentation-sqlite3

library0.65b0pypypi✓ verified 23d ago

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.

observability database

pip install opentelemetry-instrumentation-sqlite3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-INST

opentelemetry-instrumentation-sqlite3

observabilitypythonv0.65b0

Install

2.6s avg

Import

448ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.476s · 22.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.420s · 23MB

21MB installed

● package 21MB

Code

Verified usage

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

SQLite3Instrumentor

✓ from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor

This is the main class to enable SQLite3 instrumentation.

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.

import sqlite3 from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor # 1. Configure OpenTelemetry SDK resource = Resource.create({"service.name": "sqlite3-example"}) provider = TracerProvider(resource=resource) exporter = ConsoleSpanExporter() processor = SimpleSpanProcessor(exporter) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # 2. Instrument SQLite3 BEFORE making any connections SQLite3Instrumentor().instrument() # 3. Perform SQLite3 operations print("\nPerforming SQLite3 operations...") conn = sqlite3.connect(':memory:') cursor = conn.cursor() cursor.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)") cursor.execute("INSERT INTO users (name) VALUES ('Alice')") cursor.execute("INSERT INTO users (name) VALUES ('Bob')") conn.commit() cursor.execute("SELECT * FROM users") for row in cursor.fetchall(): print(f" Fetched: {row}") cursor.close() conn.close() print("SQLite3 operations complete. Check console for traces.\n")

Debug

Known issues

gotchaThe 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.

fix

Refer to release notes for potential breaking changes when upgrading beta versions.

affects: All versions marked with 'b' (beta).

gotchaInstrumentation must be enabled *before* establishing any `sqlite3` connections or interacting with the `sqlite3` module. Connections made prior to `SQLite3Instrumentor().instrument()` will not be traced.

fix

Call `SQLite3Instrumentor().instrument()` at the very beginning of your application's lifecycle, typically alongside other OpenTelemetry SDK configurations.

affects: All versions

gotchaTraces 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.

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.

affects: All versions

gotchaTo 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.

fix

Always obtain a cursor object using `connection.cursor()` and perform operations via the cursor: `cursor.execute(...)`.

affects: All versions prior to 1.x.x

Errors

Common errors & fixes

ModuleNotFoundError: No module named '_sqlite3'

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.

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.

Default SQLite3 cursor is not instrumented

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.

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()`.

AttributeError: 'Context' object has no attribute 'trace_id'

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.

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.

span was not created

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.

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.

Upgrade

Version history

0.65b0latest on PyPI · released Jul 16, 2026

Audit

Dependencies

opentelemetry-apirequiredRequired for core OpenTelemetry API functionality (e.g., TracerProvider).

opentelemetry-semantic-conventionsrequiredProvides standard attribute names and values for database spans.

opentelemetry-instrumentationrequiredBase classes and utilities for instrumentations.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/open-telemetry/opentelemetry-python-contrib ↗

packagehttps://pypi.org/project/opentelemetry-instrumentation-sqlite3/ ↗

homepagehttps://opentelemetry.io ↗