@devskin/agent 1.0.0

package/src/instrumentation/http.ts

@@ -0,0 +1,180 @@
+import * as http from 'http';
+import * as https from 'https';
+import { Agent } from '../agent';
+import { SpanBuilder, TransactionBuilder } from '../span';
+import { SpanKind } from '../types';
+import { Context } from '../utils/context';
+
+/**
+ * Instrument HTTP module
+ */
+export function instrumentHttp(agent: Agent): void {
+  const config = agent.getConfig();
+
+  // Instrument outgoing HTTP requests
+  instrumentHttpRequest(http, agent);
+  instrumentHttpRequest(https, agent);
+
+  // Instrument incoming HTTP requests (server)
+  instrumentHttpServer(http, agent);
+  instrumentHttpServer(https, agent);
+}
+
+/**
+ * Instrument outgoing HTTP requests
+ */
+function instrumentHttpRequest(module: typeof http | typeof https, agent: Agent): void {
+  const originalRequest = module.request;
+
+  (module as any).request = function (
+    this: any,
+    ...args: any[]
+  ) {
+    let options = args[0];
+    let callback = args[1];
+
+    // Handle overloaded signatures
+    if (typeof options === 'string') {
+      options = new URL(options);
+    }
+
+    // Create a span for the outgoing request
+    const config = agent.getConfig();
+    const url = typeof args[0] === 'string' ? args[0] : options.href || `${options.protocol}//${options.host || options.hostname}${options.path}`;
+
+    const span = new SpanBuilder(
+      `HTTP ${options.method || 'GET'}`,
+      SpanKind.CLIENT,
+      config.serviceName,
+      config.serviceVersion,
+      config.environment,
+      agent
+    );
+
+    span.setAttributes({
+      'http.method': options.method || 'GET',
+      'http.url': url,
+      'http.target': options.path || '/',
+      'net.peer.name': options.hostname || options.host,
+      'net.peer.port': options.port,
+    });
+
+    // Add trace context to outgoing request headers
+    const traceId = Context.getTraceId();
+    const spanId = span.getSpan().span_id;
+
+    if (!options.headers) {
+      options.headers = {};
+    }
+    options.headers['x-trace-id'] = traceId;
+    options.headers['x-span-id'] = spanId;
+
+    // Wrap callback
+    const wrappedCallback = (res: http.IncomingMessage) => {
+      span.setAttributes({
+        'http.status_code': res.statusCode,
+        'http.response.size': res.headers['content-length'],
+      });
+
+      if (res.statusCode && res.statusCode >= 400) {
+        span.setStatus('error' as any, `HTTP ${res.statusCode}`);
+      }
+
+      res.on('end', () => {
+        span.end();
+      });
+
+      if (callback) {
+        callback(res);
+      }
+    };
+
+    const req = originalRequest.call(this, options, wrappedCallback);
+
+    req.on('error', (error: Error) => {
+      span.recordError(error);
+      span.end();
+    });
+
+    return req;
+  };
+}
+
+/**
+ * Instrument incoming HTTP requests (server)
+ */
+function instrumentHttpServer(module: typeof http | typeof https, agent: Agent): void {
+  const originalCreateServer = module.createServer;
+
+  (module as any).createServer = function (
+    this: any,
+    ...args: any[]
+  ): http.Server | https.Server {
+    const server = originalCreateServer.call(this, ...args) as http.Server | https.Server;
+    const config = agent.getConfig();
+
+    // Wrap the request listener
+    server.on('request', (req: http.IncomingMessage, res: http.ServerResponse) => {
+      // Check if we should sample this request
+      if (!agent.shouldSample()) {
+        return;
+      }
+
+      // Extract trace context from headers
+      const incomingTraceId = req.headers['x-trace-id'] as string;
+      const incomingSpanId = req.headers['x-span-id'] as string;
+
+      const transaction = new TransactionBuilder(
+        `${req.method} ${req.url}`,
+        '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.url,
+        'http.target': req.url,
+        'http.host': req.headers.host,
+        'http.scheme': (req as any).protocol || 'http',
+        'http.user_agent': req.headers['user-agent'],
+        'net.peer.ip': req.socket.remoteAddress,
+        'net.peer.port': req.socket.remotePort,
+      });
+
+      // Run the rest of the request handling in context
+      Context.run({ transaction: transaction.getTransaction() }, () => {
+        const originalEnd = res.end;
+
+        (res as any).end = function (this: http.ServerResponse, ...endArgs: any[]) {
+          transaction.setAttributes({
+            'http.status_code': res.statusCode,
+            'http.response.size': res.getHeader('content-length'),
+          });
+
+          if (res.statusCode >= 400) {
+            transaction.setStatus('error' as any, `HTTP ${res.statusCode}`);
+          }
+
+          transaction.setResult(res.statusCode < 400 ? 'success' : 'error');
+          transaction.end();
+
+          return originalEnd.call(this, ...endArgs);
+        };
+      });
+    });
+
+    return server;
+  };
+}

package/src/span.ts

@@ -0,0 +1,178 @@
+import { Span, SpanKind, SpanStatus, SpanEvent, Transaction } from './types';
+import { generateSpanId, generateTraceId } from './utils/id-generator';
+import { Context } from './utils/context';
+
+/**
+ * Span builder for creating and managing spans
+ */
+export class SpanBuilder {
+  private span: Span;
+  private agent: any; // Reference to agent for reporting
+
+  constructor(
+    name: string,
+    kind: SpanKind,
+    serviceName: string,
+    serviceVersion?: string,
+    environment?: string,
+    agent?: any
+  ) {
+    const parentSpan = Context.getCurrentSpan();
+    const traceId = Context.getTraceId() || generateTraceId();
+
+    this.span = {
+      span_id: generateSpanId(),
+      trace_id: traceId,
+      parent_span_id: parentSpan?.span_id,
+      name,
+      kind,
+      start_time: new Date(),
+      status: SpanStatus.OK,
+      attributes: {},
+      events: [],
+      service_name: serviceName,
+      service_version: serviceVersion,
+      environment,
+    };
+
+    this.agent = agent;
+
+    // Set this span as current in context
+    Context.setSpan(this.span);
+  }
+
+  /**
+   * Set an attribute on the span
+   */
+  setAttribute(key: string, value: any): this {
+    this.span.attributes[key] = value;
+    return this;
+  }
+
+  /**
+   * Set multiple attributes
+   */
+  setAttributes(attributes: Record<string, any>): this {
+    Object.assign(this.span.attributes, attributes);
+    return this;
+  }
+
+  /**
+   * Add an event to the span
+   */
+  addEvent(name: string, attributes?: Record<string, any>): this {
+    this.span.events.push({
+      timestamp: new Date(),
+      name,
+      attributes,
+    });
+    return this;
+  }
+
+  /**
+   * Set the span status
+   */
+  setStatus(status: SpanStatus, message?: string): this {
+    this.span.status = status;
+    if (message) {
+      this.span.status_message = message;
+    }
+    return this;
+  }
+
+  /**
+   * Mark the span as having an error
+   */
+  recordError(error: Error): this {
+    this.setStatus(SpanStatus.ERROR, error.message);
+    this.setAttributes({
+      'error.type': error.name,
+      'error.message': error.message,
+      'error.stack': error.stack,
+    });
+    this.addEvent('exception', {
+      'exception.type': error.name,
+      'exception.message': error.message,
+    });
+    return this;
+  }
+
+  /**
+   * End the span
+   */
+  end(): void {
+    this.span.end_time = new Date();
+    this.span.duration_ms = this.span.end_time.getTime() - this.span.start_time.getTime();
+
+    // Report span to agent
+    if (this.agent && typeof this.agent.reportSpan === 'function') {
+      this.agent.reportSpan(this.span);
+    }
+  }
+
+  /**
+   * Get the span data
+   */
+  getSpan(): Span {
+    return this.span;
+  }
+}
+
+/**
+ * Transaction builder for creating root spans (transactions)
+ */
+export class TransactionBuilder extends SpanBuilder {
+  private transaction: Transaction;
+
+  constructor(
+    name: string,
+    type: string,
+    serviceName: string,
+    serviceVersion?: string,
+    environment?: string,
+    sampled = true,
+    agent?: any
+  ) {
+    super(name, SpanKind.SERVER, serviceName, serviceVersion, environment, agent);
+
+    const span = this.getSpan();
+    this.transaction = {
+      ...span,
+      transaction_type: type,
+      transaction_name: name,
+      sampled,
+    };
+
+    // Set transaction in context
+    Context.setTransaction(this.transaction);
+  }
+
+  /**
+   * Set the transaction result
+   */
+  setResult(result: string): this {
+    this.transaction.result = result;
+    return this;
+  }
+
+  /**
+   * End the transaction
+   */
+  end(): void {
+    this.transaction.end_time = new Date();
+    this.transaction.duration_ms =
+      this.transaction.end_time.getTime() - this.transaction.start_time.getTime();
+
+    // Report transaction to agent
+    if ((this as any).agent && typeof (this as any).agent.reportTransaction === 'function') {
+      (this as any).agent.reportTransaction(this.transaction);
+    }
+  }
+
+  /**
+   * Get the transaction data
+   */
+  getTransaction(): Transaction {
+    return this.transaction;
+  }
+}

package/src/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Configuration for DevSkin APM Agent
+ */
+export interface AgentConfig {
+  /** DevSkin backend URL */
+  serverUrl: string;
+
+  /** API key for authentication */
+  apiKey: string;
+
+  /** Service name */
+  serviceName: string;
+
+  /** Service version */
+  serviceVersion?: string;
+
+  /** Environment (production, staging, development) */
+  environment?: string;
+
+  /** Enable/disable the agent */
+  enabled?: boolean;
+
+  /** Sample rate (0.0 to 1.0) */
+  sampleRate?: number;
+
+  /** Enable HTTP instrumentation */
+  instrumentHttp?: boolean;
+
+  /** Enable Express instrumentation */
+  instrumentExpress?: boolean;
+
+  /** Batch size for sending data */
+  batchSize?: number;
+
+  /** Flush interval in milliseconds */
+  flushInterval?: number;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Span kind
+ */
+export enum SpanKind {
+  SERVER = 'server',
+  CLIENT = 'client',
+  INTERNAL = 'internal',
+  PRODUCER = 'producer',
+  CONSUMER = 'consumer',
+}
+
+/**
+ * Span status
+ */
+export enum SpanStatus {
+  OK = 'ok',
+  ERROR = 'error',
+}
+
+/**
+ * Span data structure
+ */
+export interface Span {
+  span_id: string;
+  trace_id: string;
+  parent_span_id?: string;
+  name: string;
+  kind: SpanKind;
+  start_time: Date;
+  end_time?: Date;
+  duration_ms?: number;
+  status: SpanStatus;
+  status_message?: string;
+  attributes: Record<string, any>;
+  events: SpanEvent[];
+  service_name: string;
+  service_version?: string;
+  environment?: string;
+}
+
+/**
+ * Span event
+ */
+export interface SpanEvent {
+  timestamp: Date;
+  name: string;
+  attributes?: Record<string, any>;
+}
+
+/**
+ * Transaction (root span)
+ */
+export interface Transaction extends Span {
+  transaction_type: string;
+  transaction_name: string;
+  result?: string;
+  sampled: boolean;
+}
+
+/**
+ * Log entry
+ */
+export interface LogEntry {
+  timestamp: Date;
+  level: string;
+  message: string;
+  trace_id?: string;
+  span_id?: string;
+  attributes?: Record<string, any>;
+  service_name: string;
+  environment?: string;
+}
+
+/**
+ * Error data
+ */
+export interface ErrorData {
+  timestamp: Date;
+  message: string;
+  type: string;
+  stack_trace?: string;
+  trace_id?: string;
+  span_id?: string;
+  attributes?: Record<string, any>;
+  service_name: string;
+  environment?: string;
+}

package/src/utils/context.ts

@@ -0,0 +1,87 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { Span, Transaction } from '../types';
+
+/**
+ * Context data stored in AsyncLocalStorage
+ */
+interface ContextData {
+  transaction?: Transaction;
+  currentSpan?: Span;
+  traceId?: string;
+  spanId?: string;
+}
+
+/**
+ * AsyncLocalStorage instance for context propagation
+ */
+const asyncLocalStorage = new AsyncLocalStorage<ContextData>();
+
+/**
+ * Context manager for maintaining trace context across async operations
+ */
+export class Context {
+  /**
+   * Run a function with a new context
+   */
+  static run<T>(context: ContextData, fn: () => T): T {
+    return asyncLocalStorage.run(context, fn);
+  }
+
+  /**
+   * Get the current context
+   */
+  static get(): ContextData | undefined {
+    return asyncLocalStorage.getStore();
+  }
+
+  /**
+   * Get the current transaction
+   */
+  static getCurrentTransaction(): Transaction | undefined {
+    return asyncLocalStorage.getStore()?.transaction;
+  }
+
+  /**
+   * Get the current span
+   */
+  static getCurrentSpan(): Span | undefined {
+    return asyncLocalStorage.getStore()?.currentSpan;
+  }
+
+  /**
+   * Get the current trace ID
+   */
+  static getTraceId(): string | undefined {
+    return asyncLocalStorage.getStore()?.traceId;
+  }
+
+  /**
+   * Get the current span ID
+   */
+  static getSpanId(): string | undefined {
+    return asyncLocalStorage.getStore()?.spanId;
+  }
+
+  /**
+   * Set the current transaction
+   */
+  static setTransaction(transaction: Transaction): void {
+    const store = asyncLocalStorage.getStore();
+    if (store) {
+      store.transaction = transaction;
+      store.traceId = transaction.trace_id;
+      store.spanId = transaction.span_id;
+    }
+  }
+
+  /**
+   * Set the current span
+   */
+  static setSpan(span: Span): void {
+    const store = asyncLocalStorage.getStore();
+    if (store) {
+      store.currentSpan = span;
+      store.spanId = span.span_id;
+    }
+  }
+}

package/src/utils/id-generator.ts

@@ -0,0 +1,22 @@
+import { randomBytes } from 'crypto';
+
+/**
+ * Generate a random trace ID (16 bytes / 32 hex chars)
+ */
+export function generateTraceId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+/**
+ * Generate a random span ID (8 bytes / 16 hex chars)
+ */
+export function generateSpanId(): string {
+  return randomBytes(8).toString('hex');
+}
+
+/**
+ * Check if a value should be sampled based on sample rate
+ */
+export function shouldSample(sampleRate: number): boolean {
+  return Math.random() < sampleRate;
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "removeComments": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "types": ["node"],
+    "strict": false,
+    "noImplicitAny": false,
+    "strictNullChecks": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}