{"_id":"@api-blitz/otel-drizzle","name":"@api-blitz/otel-drizzle","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@api-blitz/otel-drizzle","version":"1.0.0","private":false,"publishConfig":{"access":"public"},"description":"OpenTelemetry instrumentation for Drizzle ORM","author":{"name":"api-blitz"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/api-blitz/otel.git"},"sideEffects":false,"type":"module","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/types/index.d.ts","engines":{"node":"^18.19.0 || >=20.6.0"},"devDependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-trace-base":"^2.1.0","@types/node":"18.15.11","@types/pg":"^8.11.10","drizzle-orm":"^0.36.4","postgres":"^3.4.7","rimraf":"3.0.2","typescript":"^5","vitest":"0.33.0"},"peerDependencies":{"@opentelemetry/api":">=1.9.0 <2.0.0","drizzle-orm":">=0.28.0"},"scripts":{"build":"pnpm clean && tsc","clean":"rimraf dist","type-check":"tsc --noEmit","unit-test":"vitest --run","unit-test-watch":"vitest"},"bugs":{"url":"https://github.com/api-blitz/otel/issues"},"homepage":"https://github.com/api-blitz/otel#readme","_id":"@api-blitz/otel-drizzle@1.0.0","_integrity":"sha512-KOUgHkNXxfNa2gzRfViorA2OniDRKXXFiQAxIGJPpHxJRp4/z6WadmgZsT82MepMxT7apqv9cJV+2Ssst5gEPA==","_resolved":"/tmp/42b04f82d84d404330c22a53e39ae4e7/api-blitz-otel-drizzle-1.0.0.tgz","_from":"file:api-blitz-otel-drizzle-1.0.0.tgz","_nodeVersion":"18.19.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-KOUgHkNXxfNa2gzRfViorA2OniDRKXXFiQAxIGJPpHxJRp4/z6WadmgZsT82MepMxT7apqv9cJV+2Ssst5gEPA==","shasum":"3c01893ebd4d01f328c2224a1d45ffefd2089d7b","tarball":"https://registry.npmjs.org/@api-blitz/otel-drizzle/-/otel-drizzle-1.0.0.tgz","fileCount":7,"unpackedSize":70076,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDer6kaewvMjbATjtJ2UgcUIr7WmmCTH+X2+/UN7bbe0gIgPIPyiufKN32FEw8Eicxo0wp03yYXrsf247XFm0wj41s="}]},"_npmUser":{"name":"ibadus","email":"ibadus@icloud.com"},"directories":{},"maintainers":[{"name":"ibadus","email":"ibadus@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/otel-drizzle_1.0.0_1776960543504_0.17949146412593375"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T16:09:03.431Z","1.0.0":"2026-04-23T16:09:03.692Z","modified":"2026-04-23T16:09:03.854Z"},"maintainers":[{"name":"ibadus","email":"ibadus@icloud.com"}],"description":"OpenTelemetry instrumentation for Drizzle ORM","homepage":"https://github.com/api-blitz/otel#readme","repository":{"type":"git","url":"git+https://github.com/api-blitz/otel.git"},"author":{"name":"api-blitz"},"bugs":{"url":"https://github.com/api-blitz/otel/issues"},"license":"MIT","readme":"# @api-blitz/otel-drizzle\n\nOpenTelemetry instrumentation for [Drizzle ORM](https://orm.drizzle.team/). Add distributed tracing to your database queries with a single line of code.\n\n![Drizzle ORM Trace Visualization](https://github.com/api-blitz/otel/blob/main/images/otel-drizzle-trace.png)\n\n_Visualize your database queries with detailed span information including operation type, SQL statements, and performance metrics._\n\n## Installation\n\n```bash\nnpm install @api-blitz/otel-drizzle\n# or\npnpm add @api-blitz/otel-drizzle\n# or\nyarn add @api-blitz/otel-drizzle\n```\n\n**Peer Dependencies:** `@opentelemetry/api` >= 1.9.0, `drizzle-orm` >= 0.28.0\n\n## Supported Frameworks\n\nWorks with any TypeScript framework and Node.js runtime that Drizzle supports including:\n\n- Next.js\n- Fastify\n- NestJS\n- Nuxt\n- And many more...\n\n## Supported Platforms\n\nWorks with any observability platform that supports OpenTelemetry including:\n\n- [api-blitz](https://github.com/api-blitz)\n- [Sentry](https://sentry.io)\n- [Axiom](https://axiom.co)\n- [Datadog](https://www.datadoghq.com)\n- [New Relic](https://newrelic.com)\n- [SigNoz](https://signoz.io)\n- And others ...\n\n## Usage\n\n### Instrument Your Drizzle Database (Recommended)\n\nUse `instrumentDrizzleClient()` to add tracing to your Drizzle database instance. This is the simplest and most straightforward approach:\n\n```typescript\nimport { drizzle } from \"drizzle-orm/postgres-js\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Create your Drizzle database instance as usual\nconst db = drizzle(process.env.DATABASE_URL!);\n\n// Add instrumentation with a single line\ninstrumentDrizzleClient(db);\n\n// That's it! All queries are now traced automatically\nconst users = await db.select().from(usersTable);\n```\n\n### Database-Specific Examples\n\n#### PostgreSQL\n\n```typescript\n// PostgreSQL with postgres.js\nimport { drizzle } from \"drizzle-orm/postgres-js\";\nimport postgres from \"postgres\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Using connection string directly\nconst db = drizzle(process.env.DATABASE_URL!);\ninstrumentDrizzleClient(db, { dbSystem: \"postgresql\" });\n\n// Or with a client instance\nconst queryClient = postgres(process.env.DATABASE_URL!);\nconst db = drizzle({ client: queryClient });\ninstrumentDrizzleClient(db, {\n  dbSystem: \"postgresql\",\n  dbName: \"myapp\",\n  peerName: \"db.example.com\",\n  peerPort: 5432,\n});\n```\n\n```typescript\n// PostgreSQL with node-postgres (pg)\nimport { drizzle } from \"drizzle-orm/node-postgres\";\nimport { Pool } from \"pg\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Using connection string directly\nconst db = drizzle(process.env.DATABASE_URL!);\ninstrumentDrizzleClient(db, { dbSystem: \"postgresql\" });\n\n// Or with a pool instance\nconst pool = new Pool({ connectionString: process.env.DATABASE_URL });\nconst db = drizzle({ client: pool });\ninstrumentDrizzleClient(db, { dbSystem: \"postgresql\" });\n```\n\n#### MySQL\n\n```typescript\n// MySQL with mysql2\nimport { drizzle } from \"drizzle-orm/mysql2\";\nimport mysql from \"mysql2/promise\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Using connection string directly\nconst db = drizzle(process.env.DATABASE_URL!);\ninstrumentDrizzleClient(db, { dbSystem: \"mysql\" });\n\n// Or with a connection instance\nconst connection = await mysql.createConnection({\n  host: \"localhost\",\n  user: \"root\",\n  database: \"mydb\",\n  // ... other connection options\n});\nconst db = drizzle({ client: connection });\ninstrumentDrizzleClient(db, {\n  dbSystem: \"mysql\",\n  dbName: \"mydb\",\n  peerName: \"localhost\",\n  peerPort: 3306,\n});\n```\n\n#### SQLite\n\n```typescript\n// SQLite with better-sqlite3\nimport { drizzle } from \"drizzle-orm/better-sqlite3\";\nimport Database from \"better-sqlite3\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Using file path directly\nconst db = drizzle(\"sqlite.db\");\ninstrumentDrizzleClient(db, { dbSystem: \"sqlite\" });\n\n// Or with a Database instance\nconst sqlite = new Database(\"sqlite.db\");\nconst db = drizzle({ client: sqlite });\ninstrumentDrizzleClient(db, { dbSystem: \"sqlite\" });\n```\n\n```typescript\n// SQLite with LibSQL/Turso\nimport { drizzle } from \"drizzle-orm/libsql\";\nimport { createClient } from \"@libsql/client\";\nimport { instrumentDrizzleClient } from \"@api-blitz/otel-drizzle\";\n\n// Using connection config directly\nconst db = drizzle({\n  connection: {\n    url: process.env.DATABASE_URL!,\n    authToken: process.env.DATABASE_AUTH_TOKEN,\n  }\n});\ninstrumentDrizzleClient(db, { dbSystem: \"sqlite\" });\n\n// Or with a client instance\nconst client = createClient({\n  url: process.env.DATABASE_URL!,\n  authToken: process.env.DATABASE_AUTH_TOKEN,\n});\nconst db = drizzle({ client });\ninstrumentDrizzleClient(db, { dbSystem: \"sqlite\" });\n```\n\n### Configuration Options\n\n```typescript\ninstrumentDrizzleClient(db, {\n  dbSystem: \"postgresql\",    // Database type: 'postgresql' | 'mysql' | 'sqlite' (default: 'postgresql')\n  dbName: \"myapp\",           // Database name for spans\n  captureQueryText: true,    // Include SQL in traces (default: true)\n  maxQueryTextLength: 1000,  // Max SQL length (default: 1000)\n  peerName: \"db.example.com\", // Database server hostname\n  peerPort: 5432,           // Database server port\n});\n```\n\n\n## What You Get\n\nEach database query automatically creates a span with rich telemetry data:\n\n- **Span name**: `drizzle.select`, `drizzle.insert`, `drizzle.update`, etc.\n- **Operation type**: `db.operation` attribute (SELECT, INSERT, UPDATE, DELETE, SET)\n- **SQL query text**: Full query statement captured in `db.statement` (configurable)\n- **Database system**: `db.system` attribute (postgresql, mysql, sqlite, etc.)\n- **Transaction tracking**: Transaction queries are marked with `db.transaction` attribute\n- **Error tracking**: Exceptions are recorded with stack traces and proper span status\n- **Performance metrics**: Duration and timing information for every query\n\n### Transaction Support\n\nAll queries within transactions are automatically traced, including:\n- RLS (Row Level Security) queries like `SET LOCAL role` and `set_config()`\n- All nested transaction queries\n- Transaction rollbacks and commits\n\n### Span Attributes\n\nThe instrumentation adds the following attributes to each span following [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/):\n\n| Attribute        | Description           | Example                               |\n| ---------------- | --------------------- | ------------------------------------- |\n| `db.operation`   | SQL operation type    | `SELECT`                              |\n| `db.statement`   | Full SQL query        | `select \"id\", \"name\" from \"users\"...` |\n| `db.system`      | Database system       | `postgresql`                          |\n| `db.name`        | Database name         | `myapp`                               |\n| `operation.name` | Client operation name | `apiBlitz_otel-drizzle.client`          |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-169d2b3d3e29fcc2dfde0718268ea19b"}