@comprehend/telemetry-node 0.2.0 → 0.2.2

package/.claude/settings.local.json

@@ -2,8 +2,8 @@
   "permissions": {
     "allow": [
       "Bash(npm test:*)",
-      "Bash(grep:*)"
+      "Bash(pnpm run test:*)"
     ],
     "deny": []
   }
-}
+}

package/.idea/telemetry-node.iml

@@ -3,6 +3,7 @@
   <component name="NewModuleRootManager">
     <content url="file://$MODULE_DIR$">
       <excludeFolder url="file://$MODULE_DIR$/.tmp" />
+      <excludeFolder url="file://$MODULE_DIR$/dist" />
       <excludeFolder url="file://$MODULE_DIR$/temp" />
       <excludeFolder url="file://$MODULE_DIR$/tmp" />
     </content>

package/README.md

@@ -119,6 +119,49 @@ hostMetrics.start();
 
 This collects `process.cpu.time`, `process.cpu.utilization`, and `process.memory.usage`. The `metricGroups` option limits collection to process-level metrics only, avoiding the overhead of system-wide CPU, memory, and network data gathering.
 
+### Kubernetes / container resources
+
+When running in containers or Kubernetes, the `NodeSDK` default resource detectors (`env`, `process`, `host`) do not include container or pod attributes. Configure `resourceDetectors` explicitly to add them — note that doing so replaces the defaults, so include the built-in detectors too:
+
+```bash
+npm install @opentelemetry/resource-detector-container
+```
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { envDetector, hostDetector, processDetector, serviceInstanceIdDetector } from '@opentelemetry/resources';
+import { containerDetector } from '@opentelemetry/resource-detector-container';
+
+const sdk = new NodeSDK({
+    // ...
+    resourceDetectors: [envDetector, processDetector, hostDetector, containerDetector, serviceInstanceIdDetector],
+});
+```
+
+**`serviceInstanceIdDetector`** generates a random UUID (`service.instance.id`) at process startup. This gives each deployment instance a unique identity that changes on every restart, which is useful for distinguishing runs in environments where `container.id` is not available (see below).
+
+**`containerDetector`** reads `container.id` from `/proc/self/cgroup`. This works reliably with Docker-based runtimes but not on modern containerd-based Kubernetes clusters (which is the default since k8s 1.24), where the cgroup format does not expose the container ID in the expected location. Add it anyway — it will populate `container.id` when available and is a no-op otherwise.
+
+For k8s identity attributes that cannot be read from the host (pod name, namespace, node), use the Kubernetes Downward API to inject them as `OTEL_RESOURCE_ATTRIBUTES`:
+
+```yaml
+env:
+  - name: OTEL_RESOURCE_ATTRIBUTES
+    value: k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME)
+  - name: POD_NAME
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.name
+  - name: POD_NAMESPACE
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.namespace
+  - name: NODE_NAME
+    valueFrom:
+      fieldRef:
+        fieldPath: spec.nodeName
+```
+
 ## Configuration
 
 Set your comprehend.dev SDK token as an environment variable:

package/dist/ComprehendDevSpanProcessor.d.ts

@@ -14,6 +14,7 @@ export declare class ComprehendDevSpanProcessor implements SpanProcessor {
     updateCustomMetrics(specs: CustomMetricSpecification[]): void;
     onStart(span: Span, parentContext: Context): void;
     onEnd(span: ReadableSpan): void;
+    private processSpan;
     private discoverService;
     private processHTTPRoute;
     private processDatabaseOperation;

package/dist/ComprehendDevSpanProcessor.js

@@ -7,7 +7,7 @@ const utils_1 = require("@noble/hashes/utils");
 const api_1 = require("@opentelemetry/api");
 const sqlDbSystems = new Set([
     'mysql', 'postgresql', 'mssql', 'oracle', 'db2', 'sqlite', 'hsqldb', 'h2',
-    'informix', 'cockroachdb', 'redshift', 'tidb', 'trino', 'greenplum'
+    'informix', 'cockroachdb', 'redshift', 'tidb', 'trino', 'greenplum', 'clickhouse'
 ]);
 class ComprehendDevSpanProcessor {
     constructor(connection) {
@@ -25,6 +25,15 @@ class ComprehendDevSpanProcessor {
     onStart(span, parentContext) {
     }
     onEnd(span) {
+        const process = () => this.processSpan(span);
+        if (span.resource.asyncAttributesPending) {
+            span.resource.waitForAsyncAttributes?.().then(process);
+        }
+        else {
+            process();
+        }
+    }
+    processSpan(span) {
         const currentService = this.discoverService(span);
         if (!currentService)
             return;

package/dist/sql-analyzer.js

@@ -23,6 +23,7 @@ function analyzeSQL(sql) {
     let skippingValues = false;
     let lookingForCommaOrEnd = false;
     let valuesDepth = 0;
+    let skippedWhitespace = [];
     for (let token of tokenizeSQL(sql)) {
         switch (token.type) {
             case "whitespace":
@@ -136,23 +137,31 @@ function analyzeSQL(sql) {
             switch (token.type) {
                 case "comment":
                 case "whitespace":
-                    // Skip whitespace/comments while looking for comma or end
+                    // Collect whitespace/comments while looking for comma or end
+                    skippedWhitespace.push(token);
                     break;
                 case "punct":
                     if (token.value === ",") {
-                        // More tuples coming, continue skipping
+                        // More tuples coming, clear skipped whitespace and continue skipping
+                        skippedWhitespace = [];
                         lookingForCommaOrEnd = false;
                         skippingValues = true;
                     }
                     else {
                         // Not a comma, so VALUES clause is done
+                        // Add back the skipped whitespace, then the current token
+                        presentableTokens.push(...skippedWhitespace);
                         presentableTokens.push(token);
+                        skippedWhitespace = [];
                         lookingForCommaOrEnd = false;
                     }
                     break;
                 default:
                     // VALUES clause is done, resume normal processing
+                    // Add back the skipped whitespace, then the current token
+                    presentableTokens.push(...skippedWhitespace);
                     presentableTokens.push(token);
+                    skippedWhitespace = [];
                     lookingForCommaOrEnd = false;
                     break;
             }

package/dist/sql-analyzer.test.js

@@ -482,4 +482,16 @@ describe('SQL Analyzer - bulk INSERT VALUES cardinality reduction', () => {
         expect(result.presentableQuery).toEqual(`INSERT INTO comments (text, author) VALUES
             (...)`);
     });
+    it('preserves whitespace before ON CONFLICT after VALUES clause', () => {
+        const sql = `INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com') ON CONFLICT (email) DO NOTHING`;
+        const result = (0, sql_analyzer_1.analyzeSQL)(sql);
+        expect(result.tableOperations).toEqual({ users: ['INSERT'] });
+        expect(result.presentableQuery).toEqual(`INSERT INTO users (name, email) VALUES (...) ON CONFLICT (email) DO NOTHING`);
+    });
+    it('preserves whitespace before ON CONFLICT with multiple VALUES tuples', () => {
+        const sql = `INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com'), ('Bob', 'bob@example.com') ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name`;
+        const result = (0, sql_analyzer_1.analyzeSQL)(sql);
+        expect(result.tableOperations).toEqual({ users: ['INSERT'] });
+        expect(result.presentableQuery).toEqual(`INSERT INTO users (name, email) VALUES (...) ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name`);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comprehend/telemetry-node",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Integration of comprehend.dev with OpenTelemetry in Node.js and similar environemnts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ComprehendDevSpanProcessor.ts

@@ -64,7 +64,7 @@ interface ObservedDatabaseConnection {
 
 const sqlDbSystems = new Set([
     'mysql', 'postgresql', 'mssql', 'oracle', 'db2', 'sqlite', 'hsqldb', 'h2',
-    'informix', 'cockroachdb', 'redshift', 'tidb', 'trino', 'greenplum'
+    'informix', 'cockroachdb', 'redshift', 'tidb', 'trino', 'greenplum', 'clickhouse'
 ]);
 
 export class ComprehendDevSpanProcessor implements SpanProcessor {
@@ -93,6 +93,15 @@ export class ComprehendDevSpanProcessor implements SpanProcessor {
     }
 
     onEnd(span: ReadableSpan): void {
+        const process = () => this.processSpan(span);
+        if (span.resource.asyncAttributesPending) {
+            span.resource.waitForAsyncAttributes?.().then(process);
+        } else {
+            process();
+        }
+    }
+
+    private processSpan(span: ReadableSpan): void {
         const currentService = this.discoverService(span);
         if (!currentService)
             return;