{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}