autotel-drizzle 0.0.53 → 0.1.0

package/README.md

@@ -110,33 +110,73 @@ await db.select().from(users).where(eq(users.id, 123));
   peerName?: string          // Database host
   peerPort?: number          // Database port
   explain?: 'plan' | 'analyze' | false // Capture the postgres query plan (default: false)
+  semconv?: 'legacy' | 'stable' | 'dup' // Which attribute names to emit
+  spanNaming?: 'drizzle' | 'semconv'    // Span name style (default: 'drizzle')
 }
 ```
 
+**Attribute names: `semconv`**
+
+OpenTelemetry renamed the database attributes. `semconv` picks which names a span
+carries, and defaults to whatever `OTEL_SEMCONV_STABILITY_OPT_IN` asks for, or
+`'legacy'` when that is unset.
+
+| Mode       | Emits                                                                  |
+| ---------- | ---------------------------------------------------------------------- |
+| `'legacy'` | `db.system`, `db.operation`, `db.name`, `db.statement`                 |
+| `'stable'` | `db.system.name`, `db.operation.name`, `db.namespace`, `db.query.text` |
+| `'dup'`    | both, so tools on either side of the rename read the same trace        |
+
+`'dup'` is what the migration period is for: set it and nothing downstream has to
+move at the same time as you.
+
+**Span names: `spanNaming`**
+
+`'drizzle'` (the default) names spans `drizzle.select`. `'semconv'` follows the
+OpenTelemetry database convention, `{db.operation.name} {target}`, so
+`SELECT comments`. The default stays put so existing dashboards and saved queries
+keep working.
+
 **Span Attributes:**
 
-- `db.system` - Database type (postgresql, mysql, sqlite)
-- `db.operation` - Operation name (SELECT, INSERT, UPDATE, DELETE)
-- `db.name` - Database name
-- `db.statement` - SQL query text (if `captureQueryText: true`)
+- `db.system` / `db.system.name` - Database type (postgresql, mysql, sqlite)
+- `db.operation` / `db.operation.name` - Operation name (SELECT, INSERT, UPDATE, DELETE)
+- `db.name` / `db.namespace` - Database name
+- `db.statement` / `db.query.text` - SQL query text (if `captureQueryText: true`)
 - `db.statement.hash` - Stable hash of the statement, present even when the text is suppressed
+- `db.collection.name` - The table the statement is aimed at
 - `net.peer.name` - Database host
 - `net.peer.port` - Database port
 
+### Finding an N+1
+
+`db.statement.hash` is the cheapest N+1 detector you have. A route that loops a
+query emits one span per iteration, all carrying the same hash, and none of them
+individually slow. Group a trace's spans by it:
+
+| `db.statement.hash` | `db.collection.name` | Spans |
+| ------------------- | -------------------- | ----: |
+| `6b863b41773053ba`  | `comments`           |   200 |
+| `53ee56739d371a4b`  | `posts`              |     1 |
+
+One statement, run 200 times. Asking which span was slowest gives you a 1.7%
+answer and sends you off to index a table that was never the problem. The
+`find_repeated_queries` tool in `autotel-mcp` does this grouping for you.
+
 ## Drivers
 
 Tested against postgres 16, mysql 8, and sqlite, driving each through drizzle's
 own query builder, its relational API, and raw `db.execute`. Every driver below
 emits one span per query, names the operation, and tags `db.collection.name`.
 
-| Driver | Queries | Transaction span | Query plans |
-| --- | --- | --- | --- |
-| `node-postgres` | yes | yes | yes |
-| `postgres.js` | yes | yes | yes |
-| `pglite` | yes | yes | yes |
-| `mysql2` | yes | yes | postgres only |
-| `better-sqlite3` | yes | yes, synchronous | postgres only |
-| `libsql` | yes | yes | postgres only |
+| Driver           | Queries | Transaction span | Query plans   |
+| ---------------- | ------- | ---------------- | ------------- |
+| `node-postgres`  | yes     | yes              | yes           |
+| `postgres.js`    | yes     | yes              | yes           |
+| `pglite`         | yes     | yes              | yes           |
+| `mysql2`         | yes     | yes              | postgres only |
+| `better-sqlite3` | yes     | yes, synchronous | postgres only |
+| `libsql`         | yes     | yes              | postgres only |
 
 Nothing about the instrumentation is dialect-specific except `explain`, which
 sends postgres syntax and so turns itself off unless `dbSystem` is
@@ -165,19 +205,19 @@ instrumentDrizzleClient(db, {
 
 The same query, before and after `CREATE INDEX`:
 
-| Attribute | Before | After |
-| --- | --- | --- |
-| `db.statement.hash` | `372269a8881e921a` | `372269a8881e921a` |
-| `db.plan.hash` | `0b50591ce9f68f51` | `eb8765b8d1c4af5a` |
-| `db.plan.node` | `Seq Scan` | `Bitmap Heap Scan` |
-| `db.plan.indexes` | | `idx_comments_post_id` |
-| `db.plan.seq_scan` | `true` | `false` |
-| `db.plan.rows_examined` | `200199` | `1001` |
-| `db.plan.rows_returned` | `1001` | `1001` |
-| `db.plan.blocks` | `1861` | `1005` |
-| `db.plan.cost` | | planner's total cost estimate |
-| `db.plan.rows_estimated` | | rows the planner expected |
-| `db.plan.execution_ms` | | measured time (`'analyze'` only) |
+| Attribute                | Before             | After                            |
+| ------------------------ | ------------------ | -------------------------------- |
+| `db.statement.hash`      | `372269a8881e921a` | `372269a8881e921a`               |
+| `db.plan.hash`           | `0b50591ce9f68f51` | `eb8765b8d1c4af5a`               |
+| `db.plan.node`           | `Seq Scan`         | `Bitmap Heap Scan`               |
+| `db.plan.indexes`        |                    | `idx_comments_post_id`           |
+| `db.plan.seq_scan`       | `true`             | `false`                          |
+| `db.plan.rows_examined`  | `200199`           | `1001`                           |
+| `db.plan.rows_returned`  | `1001`             | `1001`                           |
+| `db.plan.blocks`         | `1861`             | `1005`                           |
+| `db.plan.cost`           |                    | planner's total cost estimate    |
+| `db.plan.rows_estimated` |                    | rows the planner expected        |
+| `db.plan.execution_ms`   |                    | measured time (`'analyze'` only) |
 
 An unchanged statement hash beside a changed plan hash is a planner decision.
 Grouping `db.plan.indexes` by `db.statement.hash` answers which queries an index
@@ -199,7 +239,7 @@ CI, or behind a sample of production traffic.
 - `'analyze'` runs on read-only statements only, so a traced insert never runs
   twice. A leading `WITH` qualifies only when no writing keyword appears
   anywhere in the statement, because `WITH gone AS (DELETE ... RETURNING *)
-  SELECT` opens exactly like a read.
+SELECT` opens exactly like a read.
 - The plan is collected before the span opens, so the extra round trip stays out
   of the duration the span reports.
 - A failed `EXPLAIN` is swallowed. The query still runs and still gets its span.

package/dist/{drizzle-C3xQFzy2.js → drizzle-BPYatG7J.js}

@@ -188,6 +188,7 @@ function resolveConfig(config) {
 		peerPort: config?.peerPort,
 		tracerProvider: config?.tracerProvider,
 		semconv: config?.semconv ?? semconvFromEnvironment(),
+		spanNaming: config?.spanNaming ?? "drizzle",
 		traceTransactions: config?.traceTransactions ?? true,
 		explain: (config?.dbSystem ?? DEFAULT_DB_SYSTEM) === "postgresql" ? config?.explain ?? false : false
 	};
@@ -303,9 +304,17 @@ async function collectPlan(state, client, queryText, params) {
 		return;
 	}
 }
+function buildSpanName(mode, operation, table) {
+	if (mode === "semconv") {
+		if (operation === void 0) return "query";
+		return table === void 0 ? operation : `${operation} ${table}`;
+	}
+	return operation ? `drizzle.${operation.toLowerCase()}` : "drizzle.query";
+}
 function buildSpan(state, queryText, extraAttributes) {
 	const operation = queryText ? extractOperation(queryText) : void 0;
-	const spanName = operation ? `drizzle.${operation.toLowerCase()}` : "drizzle.query";
+	const table = queryText ? extractTableName(queryText) : void 0;
+	const spanName = buildSpanName(state.config.spanNaming, operation, table);
 	const span = state.tracer.startSpan(spanName, { kind: SpanKind.CLIENT });
 	const { semconv } = state.config;
 	const legacy = semconv !== "stable";
@@ -319,7 +328,6 @@ function buildSpan(state, queryText, extraAttributes) {
 	if (state.config.dbName !== void 0) setRenamed(SEMATTRS_DB_NAME, SEMATTRS_DB_NAMESPACE, state.config.dbName);
 	if (queryText !== void 0) {
 		span.setAttribute(SEMATTRS_DB_STATEMENT_HASH, hashQueryText(queryText));
-		const table = extractTableName(queryText);
 		if (table !== void 0) span.setAttribute(SEMATTRS_DB_COLLECTION_NAME, table);
 	}
 	if (state.config.captureQueryText && queryText !== void 0) setRenamed(SEMATTRS_DB_STATEMENT, SEMATTRS_DB_QUERY_TEXT, sanitizeQueryText(queryText, state.config.maxQueryTextLength));

package/dist/{drizzle-BzeOQKBq.cjs → drizzle-xrFydm_L.cjs}

@@ -188,6 +188,7 @@ function resolveConfig(config) {
 		peerPort: config?.peerPort,
 		tracerProvider: config?.tracerProvider,
 		semconv: config?.semconv ?? semconvFromEnvironment(),
+		spanNaming: config?.spanNaming ?? "drizzle",
 		traceTransactions: config?.traceTransactions ?? true,
 		explain: (config?.dbSystem ?? DEFAULT_DB_SYSTEM) === "postgresql" ? config?.explain ?? false : false
 	};
@@ -303,9 +304,17 @@ async function collectPlan(state, client, queryText, params) {
 		return;
 	}
 }
+function buildSpanName(mode, operation, table) {
+	if (mode === "semconv") {
+		if (operation === void 0) return "query";
+		return table === void 0 ? operation : `${operation} ${table}`;
+	}
+	return operation ? `drizzle.${operation.toLowerCase()}` : "drizzle.query";
+}
 function buildSpan(state, queryText, extraAttributes) {
 	const operation = queryText ? extractOperation(queryText) : void 0;
-	const spanName = operation ? `drizzle.${operation.toLowerCase()}` : "drizzle.query";
+	const table = queryText ? extractTableName(queryText) : void 0;
+	const spanName = buildSpanName(state.config.spanNaming, operation, table);
 	const span = state.tracer.startSpan(spanName, { kind: _opentelemetry_api.SpanKind.CLIENT });
 	const { semconv } = state.config;
 	const legacy = semconv !== "stable";
@@ -319,7 +328,6 @@ function buildSpan(state, queryText, extraAttributes) {
 	if (state.config.dbName !== void 0) setRenamed(SEMATTRS_DB_NAME, SEMATTRS_DB_NAMESPACE, state.config.dbName);
 	if (queryText !== void 0) {
 		span.setAttribute(SEMATTRS_DB_STATEMENT_HASH, hashQueryText(queryText));
-		const table = extractTableName(queryText);
 		if (table !== void 0) span.setAttribute(SEMATTRS_DB_COLLECTION_NAME, table);
 	}
 	if (state.config.captureQueryText && queryText !== void 0) setRenamed(SEMATTRS_DB_STATEMENT, SEMATTRS_DB_QUERY_TEXT, sanitizeQueryText(queryText, state.config.maxQueryTextLength));

package/dist/drizzle.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_drizzle = require("./drizzle-BzeOQKBq.cjs");
+const require_drizzle = require("./drizzle-xrFydm_L.cjs");
 exports.instrumentDrizzle = require_drizzle.instrumentDrizzle;
 exports.instrumentDrizzleClient = require_drizzle.instrumentDrizzleClient;

package/dist/drizzle.d.cts

@@ -30,6 +30,14 @@ type ExplainMode = 'plan' | 'analyze';
  * `database/dup` selects `'dup'`.
  */
 type SemconvMode = 'legacy' | 'stable' | 'dup';
+/**
+ * How a query span is named.
+ *
+ * - `'drizzle'` names it after the library, `drizzle.select`.
+ * - `'semconv'` follows OpenTelemetry's database span convention,
+ *   `{db.operation.name} {target}`, so `SELECT comments`.
+ */
+type SpanNamingMode = 'drizzle' | 'semconv';
 interface InstrumentDrizzleConfig {
   tracerName?: string;
   dbSystem?: string;
@@ -50,6 +58,12 @@ interface InstrumentDrizzleConfig {
    * unset.
    */
   semconv?: SemconvMode;
+  /**
+   * How query spans are named. Defaults to `'drizzle'`, which keeps the
+   * `drizzle.select` names existing dashboards and saved queries are built on.
+   * `'semconv'` switches to the OpenTelemetry convention, `SELECT comments`.
+   */
+  spanNaming?: SpanNamingMode;
   /**
    * Where spans are created. Defaults to the globally registered provider,
    * which is what an application wants. Pass one to send this client's spans
@@ -67,4 +81,4 @@ interface InstrumentDrizzleConfig {
 declare function instrumentDrizzle<TClient>(client: TClient, config?: InstrumentDrizzleConfig): TClient;
 declare function instrumentDrizzleClient<TDb>(db: TDb, config?: InstrumentDrizzleConfig): TDb;
 //#endregion
-export { ExplainMode, InstrumentDrizzleConfig, SemconvMode, instrumentDrizzle, instrumentDrizzleClient };
+export { ExplainMode, InstrumentDrizzleConfig, SemconvMode, SpanNamingMode, instrumentDrizzle, instrumentDrizzleClient };

package/dist/drizzle.d.ts

@@ -30,6 +30,14 @@ type ExplainMode = 'plan' | 'analyze';
  * `database/dup` selects `'dup'`.
  */
 type SemconvMode = 'legacy' | 'stable' | 'dup';
+/**
+ * How a query span is named.
+ *
+ * - `'drizzle'` names it after the library, `drizzle.select`.
+ * - `'semconv'` follows OpenTelemetry's database span convention,
+ *   `{db.operation.name} {target}`, so `SELECT comments`.
+ */
+type SpanNamingMode = 'drizzle' | 'semconv';
 interface InstrumentDrizzleConfig {
   tracerName?: string;
   dbSystem?: string;
@@ -50,6 +58,12 @@ interface InstrumentDrizzleConfig {
    * unset.
    */
   semconv?: SemconvMode;
+  /**
+   * How query spans are named. Defaults to `'drizzle'`, which keeps the
+   * `drizzle.select` names existing dashboards and saved queries are built on.
+   * `'semconv'` switches to the OpenTelemetry convention, `SELECT comments`.
+   */
+  spanNaming?: SpanNamingMode;
   /**
    * Where spans are created. Defaults to the globally registered provider,
    * which is what an application wants. Pass one to send this client's spans
@@ -67,4 +81,4 @@ interface InstrumentDrizzleConfig {
 declare function instrumentDrizzle<TClient>(client: TClient, config?: InstrumentDrizzleConfig): TClient;
 declare function instrumentDrizzleClient<TDb>(db: TDb, config?: InstrumentDrizzleConfig): TDb;
 //#endregion
-export { ExplainMode, InstrumentDrizzleConfig, SemconvMode, instrumentDrizzle, instrumentDrizzleClient };
+export { ExplainMode, InstrumentDrizzleConfig, SemconvMode, SpanNamingMode, instrumentDrizzle, instrumentDrizzleClient };

package/dist/drizzle.js

@@ -1,2 +1,2 @@
-import { n as instrumentDrizzleClient, t as instrumentDrizzle } from "./drizzle-C3xQFzy2.js";
+import { n as instrumentDrizzleClient, t as instrumentDrizzle } from "./drizzle-BPYatG7J.js";
 export { instrumentDrizzle, instrumentDrizzleClient };

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_drizzle = require("./drizzle-BzeOQKBq.cjs");
+const require_drizzle = require("./drizzle-xrFydm_L.cjs");
 exports.SEMATTRS_DB_COLLECTION_NAME = require_drizzle.SEMATTRS_DB_COLLECTION_NAME;
 exports.SEMATTRS_DB_NAME = require_drizzle.SEMATTRS_DB_NAME;
 exports.SEMATTRS_DB_NAMESPACE = require_drizzle.SEMATTRS_DB_NAMESPACE;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { C as SEMATTRS_NET_PEER_NAME, S as SEMATTRS_GCP_BIGQUERY_STATEMENT_TYPE, _ as SEMATTRS_GCP_BIGQUERY_QUERY_HASH, a as SEMATTRS_DB_NAMESPACE, b as SEMATTRS_GCP_BIGQUERY_SCHEMA_FIELDS, c as SEMATTRS_DB_QUERY_SUMMARY, d as SEMATTRS_DB_SYSTEM, f as SEMATTRS_DB_SYSTEM_NAME, g as SEMATTRS_GCP_BIGQUERY_PROJECT_ID, h as SEMATTRS_GCP_BIGQUERY_JOB_LOCATION, i as SEMATTRS_DB_NAME, l as SEMATTRS_DB_QUERY_TEXT, m as SEMATTRS_GCP_BIGQUERY_JOB_ID, n as instrumentDrizzleClient, o as SEMATTRS_DB_OPERATION, p as SEMATTRS_GCP_BIGQUERY_DESTINATION_TABLE, r as SEMATTRS_DB_COLLECTION_NAME, s as SEMATTRS_DB_OPERATION_NAME, t as instrumentDrizzle, u as SEMATTRS_DB_STATEMENT, v as SEMATTRS_GCP_BIGQUERY_ROWS_AFFECTED, w as SEMATTRS_NET_PEER_PORT, x as SEMATTRS_GCP_BIGQUERY_SOURCE_TABLES, y as SEMATTRS_GCP_BIGQUERY_ROWS_RETURNED } from "./drizzle-C3xQFzy2.js";
+import { C as SEMATTRS_NET_PEER_NAME, S as SEMATTRS_GCP_BIGQUERY_STATEMENT_TYPE, _ as SEMATTRS_GCP_BIGQUERY_QUERY_HASH, a as SEMATTRS_DB_NAMESPACE, b as SEMATTRS_GCP_BIGQUERY_SCHEMA_FIELDS, c as SEMATTRS_DB_QUERY_SUMMARY, d as SEMATTRS_DB_SYSTEM, f as SEMATTRS_DB_SYSTEM_NAME, g as SEMATTRS_GCP_BIGQUERY_PROJECT_ID, h as SEMATTRS_GCP_BIGQUERY_JOB_LOCATION, i as SEMATTRS_DB_NAME, l as SEMATTRS_DB_QUERY_TEXT, m as SEMATTRS_GCP_BIGQUERY_JOB_ID, n as instrumentDrizzleClient, o as SEMATTRS_DB_OPERATION, p as SEMATTRS_GCP_BIGQUERY_DESTINATION_TABLE, r as SEMATTRS_DB_COLLECTION_NAME, s as SEMATTRS_DB_OPERATION_NAME, t as instrumentDrizzle, u as SEMATTRS_DB_STATEMENT, v as SEMATTRS_GCP_BIGQUERY_ROWS_AFFECTED, w as SEMATTRS_NET_PEER_PORT, x as SEMATTRS_GCP_BIGQUERY_SOURCE_TABLES, y as SEMATTRS_GCP_BIGQUERY_ROWS_RETURNED } from "./drizzle-BPYatG7J.js";
 export { SEMATTRS_DB_COLLECTION_NAME, SEMATTRS_DB_NAME, SEMATTRS_DB_NAMESPACE, SEMATTRS_DB_OPERATION, SEMATTRS_DB_OPERATION_NAME, SEMATTRS_DB_QUERY_SUMMARY, SEMATTRS_DB_QUERY_TEXT, SEMATTRS_DB_STATEMENT, SEMATTRS_DB_SYSTEM, SEMATTRS_DB_SYSTEM_NAME, SEMATTRS_GCP_BIGQUERY_DESTINATION_TABLE, SEMATTRS_GCP_BIGQUERY_JOB_ID, SEMATTRS_GCP_BIGQUERY_JOB_LOCATION, SEMATTRS_GCP_BIGQUERY_PROJECT_ID, SEMATTRS_GCP_BIGQUERY_QUERY_HASH, SEMATTRS_GCP_BIGQUERY_ROWS_AFFECTED, SEMATTRS_GCP_BIGQUERY_ROWS_RETURNED, SEMATTRS_GCP_BIGQUERY_SCHEMA_FIELDS, SEMATTRS_GCP_BIGQUERY_SOURCE_TABLES, SEMATTRS_GCP_BIGQUERY_STATEMENT_TYPE, SEMATTRS_NET_PEER_NAME, SEMATTRS_NET_PEER_PORT, instrumentDrizzle, instrumentDrizzleClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-drizzle",
-  "version": "0.0.53",
+  "version": "0.1.0",
   "description": "OpenTelemetry instrumentation for Drizzle ORM",
   "type": "module",
   "main": "./dist/drizzle.js",
@@ -35,7 +35,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/instrumentation": "^0.221.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
-    "autotel": "7.0.1"
+    "autotel": "7.2.0"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.45.2"