OpenTelemetry SQLite3 Instrumentation

Auto-instrumentation for the Ruby sqlite3 gem

Installation ◆ Usage ◆ Configuration ◆ Semantic Conventions

---

Wraps SQLite3::Database query methods with OpenTelemetry spans, capturing SQL statements with configurable obfuscation. Fills the gap in the OpenTelemetry Ruby ecosystem where adapter instrumentations exist for PG, Mysql2, and Trilogy, but not for SQLite3.

Installation

Add to your Gemfile:

gem "opentelemetry-instrumentation-sqlite3", github: "6temes/opentelemetry-instrumentation-sqlite3"

Usage

With use_all (recommended)

If you already use opentelemetry-instrumentation-all, the SQLite3 instrumentation is picked up automatically:

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

Standalone

require "opentelemetry/sdk"
require "opentelemetry-instrumentation-sqlite3"

OpenTelemetry::SDK.configure do |c|
  c.use "OpenTelemetry::Instrumentation::SQLite3"
end

With options

OpenTelemetry::SDK.configure do |c|
  c.use "OpenTelemetry::Instrumentation::SQLite3", {
    db_statement: :obfuscate,
    obfuscation_limit: 2000,
    record_exception: true
  }
end

All SQLite3::Database queries are now traced:

db = SQLite3::Database.new("app.sqlite3")
db.execute("SELECT * FROM users WHERE id = ?", [42])
# => Creates a span: name="SELECT app.sqlite3", db.system.name="sqlite", db.query.text="SELECT * FROM users WHERE id = ?"

Configuration

Option	Default	Values	Description
db_statement	:obfuscate	:omit, :include, :obfuscate	Controls SQL capture in spans
obfuscation_limit	2000	Integer	Max length of obfuscated SQL
record_exception	true	Boolean	Record exceptions on spans

db_statement modes:

• :obfuscate (default) — captures SQL with literal values replaced by ?
• :include — captures raw SQL including all literal values
• :omit — no SQL captured in spans

Note: Avoid :include in production if your queries contain sensitive data (passwords, PII, tokens). The default :obfuscate mode is recommended.

Semantic Conventions

Each span includes:

Attribute	Value	Example
db.system.name	"sqlite"	"sqlite"
db.namespace	Database filename (basename)	"app.sqlite3"
db.operation.name	SQL operation (first keyword)	"SELECT"
db.query.text	SQL (per db_statement config)	"SELECT * FROM users WHERE id = ?"
error.type	Exception class name (on errors)	"SQLite3::SQLException"
db.response.status_code	SQLite error code (on errors)	"1"

Uses stable database semantic conventions. SQLite-specific simplifications (compared to PG/Trilogy):

• No server.address or server.port — SQLite is an embedded database
• No db.user — SQLite has no authentication
• db.namespace is nil for in-memory databases (:memory:)

Instrumented Methods

The following SQLite3::Database methods are wrapped with spans:

• execute
• execute2
• execute_batch
• execute_batch2
• query

Compatibility

• Ruby >= 3.1
• sqlite3 gem >= 2.0, < 3.0

License

Apache-2.0. See LICENSE.