@comprehend/telemetry-node 0.1.4 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @comprehend/telemetry-node
 
-OpenTelemetry integration for [comprehend.dev](https://comprehend.dev) - automatically capture and analyze your Node.js application's architecture and performance.
+OpenTelemetry integration for [comprehend.dev](https://comprehend.dev) - automatically capture and analyze your Node.js application's architecture, performance, and runtime metrics.
 
 ## Installation
 
@@ -15,29 +15,33 @@ npm install @comprehend/telemetry-node
 If you don't have OpenTelemetry set up yet, here's a complete setup:
 
 ```bash
-npm install @comprehend/telemetry-node @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
+npm install @comprehend/telemetry-node @opentelemetry/sdk-node @opentelemetry/sdk-metrics @opentelemetry/auto-instrumentations-node
 ```
 
 ```typescript
+import { ComprehendSDK } from '@comprehend/telemetry-node';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
 import { Resource } from '@opentelemetry/resources';
-import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const comprehend = new ComprehendSDK({
+    organization: 'your-org',
+    token: process.env.COMPREHEND_SDK_TOKEN!,
+    debug: true  // Optional: enable debug logging (or pass a custom logger function)
+});
 
-// Set up OpenTelemetry with your service information
 const sdk = new NodeSDK({
     resource: new Resource({
         'service.name': 'my-node-service',
         'service.namespace': 'production',
         'deployment.environment': 'prod'
     }),
-    spanProcessors: [
-        new ComprehendDevSpanProcessor({
-            organization: 'your-org',  // Use your organization name
-            token: process.env.COMPREHEND_INGESTION_TOKEN!,
-            debug: true  // Optional: enable debug logging (or pass a custom logger function)
-        })
-    ],
+    spanProcessors: [comprehend.getSpanProcessor()],
+    metricReader: new PeriodicExportingMetricReader({
+        exporter: comprehend.getMetricsExporter(),
+        exportIntervalMillis: 15000
+    }),
     instrumentations: [getNodeAutoInstrumentations()],
 });
 
@@ -45,43 +49,121 @@ sdk.start();
 
 // Graceful shutdown
 process.on('SIGTERM', () => {
-    sdk.shutdown().then(() => console.log('Tracing terminated'));
+    sdk.shutdown().then(() => console.log('Telemetry terminated'));
 });
 ```
 
 ### Adding to existing OpenTelemetry setup
 
-If you already have OpenTelemetry configured, simply add the ComprehendDevSpanProcessor to your existing span processors:
+If you already have OpenTelemetry configured, create a `ComprehendSDK` instance and add its processor and exporter:
 
 ```typescript
-import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';
+import { ComprehendSDK } from '@comprehend/telemetry-node';
 
-// Add to your existing span processors array
-const comprehendProcessor = new ComprehendDevSpanProcessor({
+const comprehend = new ComprehendSDK({
     organization: 'your-org',
-    token: process.env.COMPREHEND_INGESTION_TOKEN!,
-    debug: false  // Optional
+    token: process.env.COMPREHEND_SDK_TOKEN!,
 });
 
-// If using NodeSDK:
+// Add to your NodeSDK config:
 const sdk = new NodeSDK({
     // ... your existing config
     spanProcessors: [
         // ... your existing processors
-        comprehendProcessor
+        comprehend.getSpanProcessor()
     ],
+    metricReader: new PeriodicExportingMetricReader({
+        exporter: comprehend.getMetricsExporter(),
+        exportIntervalMillis: 15000
+    }),
 });
+```
+
+### Process and runtime metrics
+
+For process-level and V8 runtime metrics (memory usage, event loop delay, GC duration, etc.), include `@opentelemetry/instrumentation-runtime-node` in your instrumentations:
+
+```bash
+npm install @opentelemetry/instrumentation-runtime-node
+```
+
+```typescript
+import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node';
+
+const sdk = new NodeSDK({
+    // ...
+    instrumentations: [
+        getNodeAutoInstrumentations(),
+        new RuntimeNodeInstrumentation(),
+    ],
+});
+```
+
+### Host metrics (CPU and memory)
+
+For process-level CPU utilization and memory usage, add `@opentelemetry/host-metrics`:
+
+```bash
+npm install @opentelemetry/host-metrics
+```
+
+```typescript
+import { HostMetrics } from '@opentelemetry/host-metrics';
+
+// Start after sdk.start()
+const hostMetrics = new HostMetrics({
+    metricGroups: ['process.cpu', 'process.memory'],
+});
+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. To populate `container.id`, `k8s.pod.name`, `k8s.namespace.name`, and similar, add the container resource detector explicitly via `resourceDetectors`:
+
+```bash
+npm install @opentelemetry/resource-detector-container
+```
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { envDetector, hostDetector, processDetector } from '@opentelemetry/resources';
+import { containerDetector } from '@opentelemetry/resource-detector-container';
+
+const sdk = new NodeSDK({
+    // ...
+    resourceDetectors: [envDetector, processDetector, hostDetector, containerDetector],
+});
+```
 
-// Or if using TracerProvider directly:
-tracerProvider.addSpanProcessor(comprehendProcessor);
+Note that passing `resourceDetectors` replaces the defaults, so make sure to include the built-in detectors alongside `containerDetector`. The container detector reads `container.id` from `/proc/self/cgroup`. For other k8s attributes (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 ingestion token as an environment variable:
+Set your comprehend.dev SDK token as an environment variable:
 
 ```bash
-export COMPREHEND_INGESTION_TOKEN=your-ingestion-token-here
+export COMPREHEND_SDK_TOKEN=your-token-here
 ```
 
 **Note:** In production environments, the token should be stored in a secure secret management system (such as AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, Kubernetes Secrets, or your cloud provider's secret management service) and injected into the environment through your container orchestrator's workload definition or service configuration.
@@ -91,15 +173,18 @@ export COMPREHEND_INGESTION_TOKEN=your-ingestion-token-here
 This integration automatically captures:
 
 - **HTTP Routes** - API endpoints and their usage patterns
-- **Database Operations** - SQL queries with table operations analysis
+- **Database Operations** - SQL queries (analysis done server-side)
 - **Service Dependencies** - HTTP client calls to external services
 - **Performance Metrics** - Request durations, response codes, error rates
 - **Service Architecture** - Automatically maps your service relationships
+- **Trace Spans** - Span identity and parent relationships for connecting observations to traces
+- **Runtime Metrics** - Node.js memory, event loop, and V8 metrics
+- **Custom Metrics** - Server-configured custom metric and span collection
 
 ## Requirements
 
 - Node.js 14+
-- OpenTelemetry SDK (peer dependency)
+- OpenTelemetry SDK (peer dependencies: `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, `@opentelemetry/sdk-metrics`)
 
 ## Framework Support
 

package/dist/ComprehendDevSpanProcessor.d.ts

@@ -1,25 +1,29 @@
 import { Context } from "@opentelemetry/api";
 import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { SpanMatcherRule, CustomMetricSpecification } from "./wire-protocol";
+import { WebSocketConnection } from "./WebSocketConnection";
 export declare class ComprehendDevSpanProcessor implements SpanProcessor {
     private readonly connection;
     private observedServices;
     private observedDatabases;
     private observedHttpServices;
     private observedInteractions;
-    private observationsSeq;
-    constructor(options: {
-        organization: string;
-        token: string;
-        debug?: boolean | ((message: string) => void);
-    });
+    private processContextSet;
+    private spanObservationSpecs;
+    constructor(connection: WebSocketConnection);
+    updateCustomMetrics(specs: CustomMetricSpecification[]): void;
     onStart(span: Span, parentContext: Context): void;
     onEnd(span: ReadableSpan): void;
+    private processSpan;
     private discoverService;
     private processHTTPRoute;
     private processDatabaseOperation;
     private processHttpRequest;
+    private reportTraceSpan;
+    private checkCustomSpanMatching;
     private getInteractions;
     private ingestMessage;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
 }
+export declare function matchSpanRule(span: ReadableSpan, rule: SpanMatcherRule): boolean;