@devskin/agent 1.0.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@devskin/agent",
+  "version": "1.0.0",
+  "description": "DevSkin Monitor Agent - JavaScript/Node.js Instrumentation SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "axios": "^1.6.5",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.10.6",
+    "@types/uuid": "^9.0.7",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "keywords": [
+    "monitoring",
+    "apm",
+    "agent",
+    "instrumentation",
+    "observability",
+    "tracing",
+    "logging",
+    "metrics"
+  ],
+  "author": "DevSkin Team",
+  "license": "MIT"
+}

package/src/agent.ts

@@ -0,0 +1,276 @@
+import { AgentConfig, Span, Transaction, LogEntry, ErrorData } from './types';
+import { ApiClient } from './api-client';
+import { shouldSample } from './utils/id-generator';
+import { Context } from './utils/context';
+
+/**
+ * DevSkin APM Agent
+ */
+export class Agent {
+  private config: AgentConfig;
+  private apiClient: ApiClient;
+  private spanBuffer: Span[] = [];
+  private transactionBuffer: Transaction[] = [];
+  private logBuffer: LogEntry[] = [];
+  private errorBuffer: ErrorData[] = [];
+  private flushTimer?: NodeJS.Timeout;
+  private initialized = false;
+
+  constructor(config: AgentConfig) {
+    this.config = {
+      enabled: true,
+      sampleRate: 1.0,
+      instrumentHttp: true,
+      instrumentExpress: true,
+      batchSize: 100,
+      flushInterval: 10000, // 10 seconds
+      debug: false,
+      ...config,
+    };
+
+    if (!this.config.enabled) {
+      console.log('[DevSkin Agent] Agent is disabled');
+      return;
+    }
+
+    if (!this.config.serverUrl || !this.config.apiKey || !this.config.serviceName) {
+      throw new Error('[DevSkin Agent] serverUrl, apiKey, and serviceName are required');
+    }
+
+    this.apiClient = new ApiClient(
+      this.config.serverUrl,
+      this.config.apiKey,
+      this.config.serviceName,
+      this.config.debug
+    );
+  }
+
+  /**
+   * Start the agent
+   */
+  async start(): Promise<void> {
+    if (!this.config.enabled) return;
+    if (this.initialized) return;
+
+    this.initialized = true;
+
+    if (this.config.debug) {
+      console.log('[DevSkin Agent] Starting agent for service:', this.config.serviceName);
+    }
+
+    // Start flush timer
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, this.config.flushInterval);
+
+    // Send service metadata for discovery
+    await this.sendServiceMetadata();
+
+    // Initialize instrumentation
+    if (this.config.instrumentHttp) {
+      await this.initHttpInstrumentation();
+    }
+
+    if (this.config.debug) {
+      console.log('[DevSkin Agent] Agent started successfully');
+    }
+  }
+
+  /**
+   * Stop the agent
+   */
+  async stop(): Promise<void> {
+    if (!this.config.enabled) return;
+
+    if (this.config.debug) {
+      console.log('[DevSkin Agent] Stopping agent...');
+    }
+
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+
+    await this.flush();
+
+    this.initialized = false;
+
+    if (this.config.debug) {
+      console.log('[DevSkin Agent] Agent stopped');
+    }
+  }
+
+  /**
+   * Initialize HTTP instrumentation
+   */
+  private async initHttpInstrumentation(): Promise<void> {
+    try {
+      const { instrumentHttp } = await import('./instrumentation/http');
+      instrumentHttp(this);
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to initialize HTTP instrumentation:', error.message);
+    }
+  }
+
+  /**
+   * Send service metadata
+   */
+  private async sendServiceMetadata(): Promise<void> {
+    try {
+      await this.apiClient.sendServiceMetadata({
+        service_version: this.config.serviceVersion,
+        environment: this.config.environment,
+        language: 'node.js',
+        language_version: process.version,
+        metadata: {
+          platform: process.platform,
+          arch: process.arch,
+          node_version: process.version,
+        },
+      });
+    } catch (error: any) {
+      if (this.config.debug) {
+        console.error('[DevSkin Agent] Failed to send service metadata:', error.message);
+      }
+    }
+  }
+
+  /**
+   * Report a span
+   */
+  reportSpan(span: Span): void {
+    if (!this.config.enabled) return;
+
+    this.spanBuffer.push(span);
+
+    if (this.spanBuffer.length >= this.config.batchSize!) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Report a transaction
+   */
+  reportTransaction(transaction: Transaction): void {
+    if (!this.config.enabled) return;
+
+    this.transactionBuffer.push(transaction);
+
+    if (this.transactionBuffer.length >= this.config.batchSize!) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Report a log entry
+   */
+  reportLog(log: LogEntry): void {
+    if (!this.config.enabled) return;
+
+    this.logBuffer.push(log);
+
+    if (this.logBuffer.length >= this.config.batchSize!) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Report an error
+   */
+  reportError(error: ErrorData): void {
+    if (!this.config.enabled) return;
+
+    this.errorBuffer.push(error);
+
+    if (this.errorBuffer.length >= this.config.batchSize!) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Flush all buffered data
+   */
+  async flush(): Promise<void> {
+    if (!this.config.enabled) return;
+
+    const spans = [...this.spanBuffer];
+    const transactions = [...this.transactionBuffer];
+    const logs = [...this.logBuffer];
+    const errors = [...this.errorBuffer];
+
+    this.spanBuffer = [];
+    this.transactionBuffer = [];
+    this.logBuffer = [];
+    this.errorBuffer = [];
+
+    try {
+      await Promise.all([
+        this.apiClient.sendSpans(spans),
+        this.apiClient.sendTransactions(transactions),
+        this.apiClient.sendLogs(logs),
+        this.apiClient.sendErrors(errors),
+      ]);
+    } catch (error: any) {
+      if (this.config.debug) {
+        console.error('[DevSkin Agent] Failed to flush data:', error.message);
+      }
+    }
+  }
+
+  /**
+   * Get agent configuration
+   */
+  getConfig(): AgentConfig {
+    return this.config;
+  }
+
+  /**
+   * Check if sampling is enabled for this request
+   */
+  shouldSample(): boolean {
+    return shouldSample(this.config.sampleRate || 1.0);
+  }
+}
+
+/**
+ * Global agent instance
+ */
+let globalAgent: Agent | null = null;
+
+/**
+ * Initialize the global agent
+ */
+export function init(config: AgentConfig): Agent {
+  if (globalAgent) {
+    console.warn('[DevSkin Agent] Agent already initialized');
+    return globalAgent;
+  }
+
+  globalAgent = new Agent(config);
+  return globalAgent;
+}
+
+/**
+ * Get the global agent instance
+ */
+export function getAgent(): Agent | null {
+  return globalAgent;
+}
+
+/**
+ * Start the global agent
+ */
+export async function startAgent(): Promise<void> {
+  if (!globalAgent) {
+    throw new Error('[DevSkin Agent] Agent not initialized. Call init() first.');
+  }
+  await globalAgent.start();
+}
+
+/**
+ * Stop the global agent
+ */
+export async function stopAgent(): Promise<void> {
+  if (globalAgent) {
+    await globalAgent.stop();
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,125 @@
+import axios, { AxiosInstance } from 'axios';
+import { Span, Transaction, LogEntry, ErrorData } from './types';
+
+/**
+ * API client for sending data to DevSkin backend
+ */
+export class ApiClient {
+  private client: AxiosInstance;
+  private apiKey: string;
+  private serviceName: string;
+  private debug: boolean;
+
+  constructor(serverUrl: string, apiKey: string, serviceName: string, debug = false) {
+    this.apiKey = apiKey;
+    this.serviceName = serviceName;
+    this.debug = debug;
+
+    this.client = axios.create({
+      baseURL: serverUrl,
+      timeout: 30000,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-DevSkin-API-Key': apiKey,
+      },
+    });
+  }
+
+  /**
+   * Send spans to the backend
+   */
+  async sendSpans(spans: Span[]): Promise<void> {
+    if (spans.length === 0) return;
+
+    try {
+      if (this.debug) {
+        console.log(`[DevSkin Agent] Sending ${spans.length} spans`);
+      }
+
+      await this.client.post('/api/v1/apm/spans', {
+        service_name: this.serviceName,
+        spans,
+      });
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to send spans:', error.message);
+    }
+  }
+
+  /**
+   * Send transactions to the backend
+   */
+  async sendTransactions(transactions: Transaction[]): Promise<void> {
+    if (transactions.length === 0) return;
+
+    try {
+      if (this.debug) {
+        console.log(`[DevSkin Agent] Sending ${transactions.length} transactions`);
+      }
+
+      await this.client.post('/api/v1/apm/transactions', {
+        service_name: this.serviceName,
+        transactions,
+      });
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to send transactions:', error.message);
+    }
+  }
+
+  /**
+   * Send logs to the backend
+   */
+  async sendLogs(logs: LogEntry[]): Promise<void> {
+    if (logs.length === 0) return;
+
+    try {
+      if (this.debug) {
+        console.log(`[DevSkin Agent] Sending ${logs.length} logs`);
+      }
+
+      await this.client.post('/api/v1/logs/batch', {
+        service_name: this.serviceName,
+        logs,
+      });
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to send logs:', error.message);
+    }
+  }
+
+  /**
+   * Send error data to the backend
+   */
+  async sendErrors(errors: ErrorData[]): Promise<void> {
+    if (errors.length === 0) return;
+
+    try {
+      if (this.debug) {
+        console.log(`[DevSkin Agent] Sending ${errors.length} errors`);
+      }
+
+      await this.client.post('/api/v1/apm/errors', {
+        service_name: this.serviceName,
+        errors,
+      });
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to send errors:', error.message);
+    }
+  }
+
+  /**
+   * Send service metadata (for service discovery)
+   */
+  async sendServiceMetadata(metadata: Record<string, any>): Promise<void> {
+    try {
+      if (this.debug) {
+        console.log('[DevSkin Agent] Sending service metadata');
+      }
+
+      await this.client.post('/api/v1/apm/services', {
+        service_name: this.serviceName,
+        ...metadata,
+      });
+    } catch (error: any) {
+      console.error('[DevSkin Agent] Failed to send service metadata:', error.message);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * DevSkin APM Agent for Node.js
+ *
+ * @example
+ * ```typescript
+ * import { init, startAgent } from '@devskin/agent';
+ *
+ * const agent = init({
+ *   serverUrl: 'https://api-monitoring.devskin.com',
+ *   apiKey: 'your-api-key',
+ *   serviceName: 'my-service',
+ *   serviceVersion: '1.0.0',
+ *   environment: 'production',
+ *   sampleRate: 1.0,
+ * });
+ *
+ * await startAgent();
+ * ```
+ */
+
+export * from './types';
+export * from './agent';
+export * from './span';
+export * from './api-client';
+export * from './utils/context';
+export * from './utils/id-generator';
+export { expressMiddleware, expressErrorHandler } from './instrumentation/express';
+
+// Re-export commonly used functions
+export { init, getAgent, startAgent, stopAgent } from './agent';
+export { SpanBuilder, TransactionBuilder } from './span';
+export { Context } from './utils/context';

package/src/instrumentation/express.ts

@@ -0,0 +1,143 @@
+import { Request, Response, NextFunction } from 'express';
+import { Agent } from '../agent';
+import { TransactionBuilder } from '../span';
+import { Context } from '../utils/context';
+
+/**
+ * Express middleware for automatic transaction creation
+ */
+export function expressMiddleware(agent: Agent) {
+  const config = agent.getConfig();
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Check if we should sample this request
+    if (!agent.shouldSample()) {
+      return next();
+    }
+
+    // Extract trace context from headers
+    const incomingTraceId = req.headers['x-trace-id'] as string;
+    const incomingSpanId = req.headers['x-span-id'] as string;
+
+    // Create transaction
+    const transactionName = req.route?.path
+      ? `${req.method} ${req.route.path}`
+      : `${req.method} ${req.path}`;
+
+    const transaction = new TransactionBuilder(
+      transactionName,
+      'http.request',
+      config.serviceName,
+      config.serviceVersion,
+      config.environment,
+      true,
+      agent
+    );
+
+    // If there's an incoming trace ID, use it
+    if (incomingTraceId) {
+      transaction.getTransaction().trace_id = incomingTraceId;
+      if (incomingSpanId) {
+        transaction.getTransaction().parent_span_id = incomingSpanId;
+      }
+    }
+
+    transaction.setAttributes({
+      'http.method': req.method,
+      'http.url': req.originalUrl || req.url,
+      'http.target': req.path,
+      'http.route': req.route?.path,
+      'http.host': req.hostname,
+      'http.scheme': req.protocol,
+      'http.user_agent': req.get('user-agent'),
+      'net.peer.ip': req.ip,
+    });
+
+    // Add query params and body (be careful with sensitive data)
+    if (Object.keys(req.query).length > 0) {
+      transaction.setAttribute('http.query', JSON.stringify(req.query));
+    }
+
+    // Store transaction in request object
+    (req as any).devskinTransaction = transaction;
+
+    // Run the rest of the request handling in context
+    Context.run({ transaction: transaction.getTransaction() }, () => {
+      // Wrap res.send, res.json, res.end to capture response
+      const originalSend = res.send;
+      const originalJson = res.json;
+      const originalEnd = res.end;
+
+      const endTransaction = () => {
+        transaction.setAttributes({
+          'http.status_code': res.statusCode,
+        });
+
+        if (res.statusCode >= 400) {
+          transaction.setStatus('error' as any, `HTTP ${res.statusCode}`);
+        }
+
+        transaction.setResult(res.statusCode < 400 ? 'success' : 'error');
+        transaction.end();
+      };
+
+      res.send = function (body?: any): Response {
+        endTransaction();
+        return originalSend.call(this, body);
+      };
+
+      res.json = function (body?: any): Response {
+        endTransaction();
+        return originalJson.call(this, body);
+      };
+
+      (res as any).end = function (...args: any[]): Response {
+        endTransaction();
+        return originalEnd.apply(this, args);
+      };
+
+      // Handle errors
+      res.on('error', (error: Error) => {
+        transaction.recordError(error);
+        endTransaction();
+      });
+
+      next();
+    });
+  };
+}
+
+/**
+ * Express error handler middleware
+ */
+export function expressErrorHandler(agent: Agent) {
+  return (err: Error, req: Request, res: Response, next: NextFunction) => {
+    const transaction = (req as any).devskinTransaction as TransactionBuilder | undefined;
+
+    if (transaction) {
+      transaction.recordError(err);
+      transaction.setResult('error');
+      transaction.end();
+    }
+
+    // Report error to agent
+    const config = agent.getConfig();
+    agent.reportError({
+      timestamp: new Date(),
+      message: err.message,
+      type: err.name,
+      stack_trace: err.stack,
+      trace_id: Context.getTraceId(),
+      span_id: Context.getSpanId(),
+      attributes: {
+        'http.method': req.method,
+        'http.url': req.originalUrl || req.url,
+        'http.route': req.route?.path,
+      },
+      service_name: config.serviceName,
+      environment: config.environment,
+    });
+
+    next(err);
+  };
+}