@comprehend/telemetry-node 0.1.3 → 0.2.0

package/.claude/settings.local.json

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

package/.idea/telemetry-node.iml

@@ -3,7 +3,6 @@
   <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/DEVELOPMENT.md

@@ -0,0 +1,69 @@
+# Development Guide
+
+## Development Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Run tests:
+```bash
+npm test
+```
+
+3. Build the package:
+```bash
+npm run build
+```
+
+## Making a New Release
+
+Follow these steps to release a new version:
+
+### 1. Update Version Number
+Edit `package.json` and update the version:
+```json
+{
+  "version": "0.1.4"
+}
+```
+
+### 2. Run Tests
+Ensure all tests pass:
+```bash
+npm test
+```
+
+### 3. Build Distribution Package
+Build the TypeScript files:
+```bash
+npm run build
+```
+
+### 4. Publish to npm
+Publish the package (requires npm authentication):
+```bash
+npm publish
+```
+
+### 5. Verify Release
+Check that the package is available:
+```bash
+# View on npm
+open https://www.npmjs.com/package/@comprehend/telemetry-node
+
+# Test installation
+npm install @comprehend/telemetry-node@NEW_VERSION
+```
+
+### Version Strategy
+- **Patch** (0.1.0 → 0.1.1): Bug fixes, small improvements
+- **Minor** (0.1.0 → 0.2.0): New features, backward compatible
+- **Major** (0.1.0 → 1.0.0): Breaking changes
+
+### Prerequisites for Release
+- npm account with publish access to @comprehend scope
+- Authenticated with npm (`npm login`)
+- All tests passing
+- Clean working directory (no uncommitted changes recommended)

package/README.md

@@ -0,0 +1,173 @@
+# @comprehend/telemetry-node
+
+OpenTelemetry integration for [comprehend.dev](https://comprehend.dev) - automatically capture and analyze your Node.js application's architecture, performance, and runtime metrics.
+
+## Installation
+
+```bash
+npm install @comprehend/telemetry-node
+```
+
+## Quick Start
+
+### Starting from scratch
+
+If you don't have OpenTelemetry set up yet, here's a complete setup:
+
+```bash
+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 { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { Resource } from '@opentelemetry/resources';
+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)
+});
+
+const sdk = new NodeSDK({
+    resource: new Resource({
+        'service.name': 'my-node-service',
+        'service.namespace': 'production',
+        'deployment.environment': 'prod'
+    }),
+    spanProcessors: [comprehend.getSpanProcessor()],
+    metricReader: new PeriodicExportingMetricReader({
+        exporter: comprehend.getMetricsExporter(),
+        exportIntervalMillis: 15000
+    }),
+    instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+    sdk.shutdown().then(() => console.log('Telemetry terminated'));
+});
+```
+
+### Adding to existing OpenTelemetry setup
+
+If you already have OpenTelemetry configured, create a `ComprehendSDK` instance and add its processor and exporter:
+
+```typescript
+import { ComprehendSDK } from '@comprehend/telemetry-node';
+
+const comprehend = new ComprehendSDK({
+    organization: 'your-org',
+    token: process.env.COMPREHEND_SDK_TOKEN!,
+});
+
+// Add to your NodeSDK config:
+const sdk = new NodeSDK({
+    // ... your existing config
+    spanProcessors: [
+        // ... your existing processors
+        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.
+
+## Configuration
+
+Set your comprehend.dev SDK token as an environment variable:
+
+```bash
+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.
+
+## What it captures
+
+This integration automatically captures:
+
+- **HTTP Routes** - API endpoints and their usage patterns
+- **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 dependencies: `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, `@opentelemetry/sdk-metrics`)
+
+## Framework Support
+
+Works with any Node.js framework that supports OpenTelemetry auto-instrumentation:
+
+- Express
+- Fastify
+- Koa
+- NestJS
+- PostgreSQL
+- MySQL
+- MongoDB
+- Prisma
+- Sequelize
+- TypeORM
+- And more...
+
+## Learn More
+
+- Visit [comprehend.dev](https://comprehend.dev) for documentation and to get your ingestion token
+- [OpenTelemetry JavaScript Documentation](https://opentelemetry.io/docs/languages/js/)
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and release instructions.

package/dist/ComprehendDevSpanProcessor.d.ts

@@ -1,25 +1,28 @@
 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 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;