@comprehend/telemetry-node 0.1.2 → 0.1.4

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/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,127 @@
+# @comprehend/telemetry-node
+
+OpenTelemetry integration for [comprehend.dev](https://comprehend.dev) - automatically capture and analyze your Node.js application's architecture and performance.
+
+## 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/auto-instrumentations-node
+```
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Resource } from '@opentelemetry/resources';
+import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';
+
+// 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)
+        })
+    ],
+    instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+    sdk.shutdown().then(() => console.log('Tracing terminated'));
+});
+```
+
+### Adding to existing OpenTelemetry setup
+
+If you already have OpenTelemetry configured, simply add the ComprehendDevSpanProcessor to your existing span processors:
+
+```typescript
+import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';
+
+// Add to your existing span processors array
+const comprehendProcessor = new ComprehendDevSpanProcessor({
+    organization: 'your-org',
+    token: process.env.COMPREHEND_INGESTION_TOKEN!,
+    debug: false  // Optional
+});
+
+// If using NodeSDK:
+const sdk = new NodeSDK({
+    // ... your existing config
+    spanProcessors: [
+        // ... your existing processors
+        comprehendProcessor
+    ],
+});
+
+// Or if using TracerProvider directly:
+tracerProvider.addSpanProcessor(comprehendProcessor);
+```
+
+## Configuration
+
+Set your comprehend.dev ingestion token as an environment variable:
+
+```bash
+export COMPREHEND_INGESTION_TOKEN=your-ingestion-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 with table operations analysis
+- **Service Dependencies** - HTTP client calls to external services
+- **Performance Metrics** - Request durations, response codes, error rates
+- **Service Architecture** - Automatically maps your service relationships
+
+## Requirements
+
+- Node.js 14+
+- OpenTelemetry SDK (peer dependency)
+
+## 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.js

@@ -72,6 +72,7 @@ class ComprehendDevSpanProcessor {
             ...(environment ? { environment } : {})
         };
         this.ingestMessage(message);
+        return newService;
     }
     processHTTPRoute(service, route, method, span) {
         // Check if this route+method already exists under the service

package/dist/ComprehendDevSpanProcessor.test.d.ts

@@ -0,0 +1 @@
+export {};