@atrim/instrument-node 1.0.0

package/target/dist/integrations/effect/index.js

@@ -0,0 +1,669 @@
+import { Data, Effect, Cache, Layer, FiberSet as FiberSet$1, Duration, Schedule, Tracer } from 'effect';
+import * as Otlp from '@effect/opentelemetry/Otlp';
+import { FetchHttpClient } from '@effect/platform';
+import { TraceFlags, trace, context } from '@opentelemetry/api';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { parse } from 'yaml';
+import { z } from 'zod';
+
+// src/integrations/effect/effect-tracer.ts
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var PatternConfigSchema = z.object({
+  pattern: z.string(),
+  enabled: z.boolean().optional(),
+  description: z.string().optional()
+});
+var AutoIsolationConfigSchema = z.object({
+  // Global enable/disable for auto-isolation
+  enabled: z.boolean().default(false),
+  // Which operators to auto-isolate
+  operators: z.object({
+    fiberset_run: z.boolean().default(true),
+    effect_fork: z.boolean().default(true),
+    effect_fork_daemon: z.boolean().default(true),
+    effect_fork_in: z.boolean().default(false)
+  }).default({}),
+  // Virtual parent tracking configuration
+  tracking: z.object({
+    use_span_links: z.boolean().default(true),
+    use_attributes: z.boolean().default(true),
+    capture_logical_parent: z.boolean().default(true)
+  }).default({}),
+  // Span categorization
+  attributes: z.object({
+    category: z.string().default("background_task"),
+    add_metadata: z.boolean().default(true)
+  }).default({})
+});
+var InstrumentationConfigSchema = z.object({
+  version: z.string(),
+  instrumentation: z.object({
+    enabled: z.boolean(),
+    description: z.string().optional(),
+    logging: z.enum(["on", "off", "minimal"]).optional().default("on"),
+    instrument_patterns: z.array(PatternConfigSchema),
+    ignore_patterns: z.array(PatternConfigSchema)
+  }),
+  effect: z.object({
+    auto_extract_metadata: z.boolean(),
+    auto_isolation: AutoIsolationConfigSchema.optional()
+  }).optional()
+});
+(class extends Data.TaggedError("ConfigError") {
+});
+var ConfigUrlError = class extends Data.TaggedError("ConfigUrlError") {
+};
+var ConfigValidationError = class extends Data.TaggedError("ConfigValidationError") {
+};
+var ConfigFileError = class extends Data.TaggedError("ConfigFileError") {
+};
+(class extends Data.TaggedError("ServiceDetectionError") {
+});
+(class extends Data.TaggedError("InitializationError") {
+});
+(class extends Data.TaggedError("ExportError") {
+});
+(class extends Data.TaggedError("ShutdownError") {
+});
+var SECURITY_DEFAULTS = {
+  maxConfigSize: 1e6,
+  // 1MB
+  requestTimeout: 5e3,
+  allowedProtocols: ["https:"],
+  // Only HTTPS for remote configs
+  cacheTimeout: 3e5
+  // 5 minutes
+};
+function getDefaultConfig() {
+  return {
+    version: "1.0",
+    instrumentation: {
+      enabled: true,
+      logging: "on",
+      description: "Default instrumentation configuration",
+      instrument_patterns: [
+        { pattern: "^app\\.", enabled: true, description: "Application operations" },
+        { pattern: "^http\\.server\\.", enabled: true, description: "HTTP server operations" },
+        { pattern: "^http\\.client\\.", enabled: true, description: "HTTP client operations" }
+      ],
+      ignore_patterns: [
+        { pattern: "^test\\.", description: "Test utilities" },
+        { pattern: "^internal\\.", description: "Internal operations" },
+        { pattern: "^health\\.", description: "Health checks" }
+      ]
+    },
+    effect: {
+      auto_extract_metadata: true
+    }
+  };
+}
+var validateConfigEffect = (rawConfig) => Effect.try({
+  try: () => InstrumentationConfigSchema.parse(rawConfig),
+  catch: (error) => new ConfigValidationError({
+    reason: "Invalid configuration schema",
+    cause: error
+  })
+});
+var loadConfigFromFileEffect = (filePath) => Effect.gen(function* () {
+  const fileContents = yield* Effect.try({
+    try: () => readFileSync(filePath, "utf8"),
+    catch: (error) => new ConfigFileError({
+      reason: `Failed to read config file at ${filePath}`,
+      cause: error
+    })
+  });
+  if (fileContents.length > SECURITY_DEFAULTS.maxConfigSize) {
+    return yield* Effect.fail(
+      new ConfigFileError({
+        reason: `Config file exceeds maximum size of ${SECURITY_DEFAULTS.maxConfigSize} bytes`
+      })
+    );
+  }
+  let rawConfig;
+  try {
+    rawConfig = parse(fileContents);
+  } catch (error) {
+    return yield* Effect.fail(
+      new ConfigValidationError({
+        reason: "Invalid YAML syntax",
+        cause: error
+      })
+    );
+  }
+  return yield* validateConfigEffect(rawConfig);
+});
+var fetchAndParseConfig = (url) => Effect.gen(function* () {
+  let urlObj;
+  try {
+    urlObj = new URL(url);
+  } catch (error) {
+    return yield* Effect.fail(
+      new ConfigUrlError({
+        reason: `Invalid URL: ${url}`,
+        cause: error
+      })
+    );
+  }
+  if (!SECURITY_DEFAULTS.allowedProtocols.includes(urlObj.protocol)) {
+    return yield* Effect.fail(
+      new ConfigUrlError({
+        reason: `Insecure protocol ${urlObj.protocol}. Only ${SECURITY_DEFAULTS.allowedProtocols.join(", ")} are allowed`
+      })
+    );
+  }
+  const response = yield* Effect.tryPromise({
+    try: () => fetch(url, {
+      redirect: "follow",
+      headers: {
+        Accept: "application/yaml, text/yaml, text/x-yaml"
+      }
+    }),
+    catch: (error) => new ConfigUrlError({
+      reason: `Failed to load config from URL ${url}`,
+      cause: error
+    })
+  }).pipe(
+    Effect.timeout(Duration.millis(SECURITY_DEFAULTS.requestTimeout)),
+    Effect.retry({
+      times: 3,
+      schedule: Schedule.exponential(Duration.millis(100))
+    }),
+    Effect.catchAll((error) => {
+      if (error._tag === "TimeoutException") {
+        return Effect.fail(
+          new ConfigUrlError({
+            reason: `Config fetch timeout after ${SECURITY_DEFAULTS.requestTimeout}ms`
+          })
+        );
+      }
+      return Effect.fail(error);
+    })
+  );
+  if (!response.ok) {
+    return yield* Effect.fail(
+      new ConfigUrlError({
+        reason: `HTTP ${response.status}: ${response.statusText}`
+      })
+    );
+  }
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && parseInt(contentLength) > SECURITY_DEFAULTS.maxConfigSize) {
+    return yield* Effect.fail(
+      new ConfigUrlError({
+        reason: `Config exceeds maximum size of ${SECURITY_DEFAULTS.maxConfigSize} bytes`
+      })
+    );
+  }
+  const text = yield* Effect.tryPromise({
+    try: () => response.text(),
+    catch: (error) => new ConfigUrlError({
+      reason: "Failed to read response body",
+      cause: error
+    })
+  });
+  if (text.length > SECURITY_DEFAULTS.maxConfigSize) {
+    return yield* Effect.fail(
+      new ConfigUrlError({
+        reason: `Config exceeds maximum size of ${SECURITY_DEFAULTS.maxConfigSize} bytes`
+      })
+    );
+  }
+  let rawConfig;
+  try {
+    rawConfig = parse(text);
+  } catch (error) {
+    return yield* Effect.fail(
+      new ConfigValidationError({
+        reason: "Invalid YAML syntax",
+        cause: error
+      })
+    );
+  }
+  return yield* validateConfigEffect(rawConfig);
+});
+var makeConfigCache = () => Cache.make({
+  capacity: 100,
+  timeToLive: Duration.minutes(5),
+  lookup: (url) => fetchAndParseConfig(url)
+});
+var cacheInstance = null;
+var getCache = Effect.gen(function* () {
+  if (!cacheInstance) {
+    cacheInstance = yield* makeConfigCache();
+  }
+  return cacheInstance;
+});
+var loadConfigFromUrlEffect = (url, cacheTimeout = SECURITY_DEFAULTS.cacheTimeout) => Effect.gen(function* () {
+  if (cacheTimeout === 0) {
+    return yield* fetchAndParseConfig(url);
+  }
+  const cache = yield* getCache;
+  return yield* cache.get(url);
+});
+var loadConfigEffect = (options = {}) => Effect.gen(function* () {
+  if (options.config) {
+    return yield* validateConfigEffect(options.config);
+  }
+  const envConfigPath = process.env.ATRIM_INSTRUMENTATION_CONFIG;
+  if (envConfigPath) {
+    if (envConfigPath.startsWith("http://") || envConfigPath.startsWith("https://")) {
+      return yield* loadConfigFromUrlEffect(envConfigPath, options.cacheTimeout);
+    }
+    return yield* loadConfigFromFileEffect(envConfigPath);
+  }
+  if (options.configUrl) {
+    return yield* loadConfigFromUrlEffect(options.configUrl, options.cacheTimeout);
+  }
+  if (options.configPath) {
+    return yield* loadConfigFromFileEffect(options.configPath);
+  }
+  const defaultPath = join(process.cwd(), "instrumentation.yaml");
+  const exists = yield* Effect.sync(() => existsSync(defaultPath));
+  if (exists) {
+    return yield* loadConfigFromFileEffect(defaultPath);
+  }
+  return getDefaultConfig();
+});
+async function loadConfig(options = {}) {
+  return Effect.runPromise(
+    loadConfigEffect(options).pipe(
+      // Convert typed errors to regular Error with reason message for backward compatibility
+      Effect.mapError((error) => {
+        const message = error.reason;
+        const newError = new Error(message);
+        newError.cause = error.cause;
+        return newError;
+      })
+    )
+  );
+}
+var PatternMatcher = class {
+  constructor(config) {
+    __publicField(this, "ignorePatterns", []);
+    __publicField(this, "instrumentPatterns", []);
+    __publicField(this, "enabled", true);
+    this.enabled = config.instrumentation.enabled;
+    this.ignorePatterns = config.instrumentation.ignore_patterns.map((p) => this.compilePattern(p));
+    this.instrumentPatterns = config.instrumentation.instrument_patterns.filter((p) => p.enabled !== false).map((p) => this.compilePattern(p));
+  }
+  /**
+   * Compile a pattern configuration into a RegExp
+   */
+  compilePattern(pattern) {
+    try {
+      const compiled = {
+        regex: new RegExp(pattern.pattern),
+        enabled: pattern.enabled !== false
+      };
+      if (pattern.description !== void 0) {
+        compiled.description = pattern.description;
+      }
+      return compiled;
+    } catch (error) {
+      throw new Error(
+        `Failed to compile pattern "${pattern.pattern}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Check if a span should be instrumented
+   *
+   * Returns true if the span should be created, false otherwise.
+   *
+   * Logic:
+   * 1. If instrumentation disabled globally, return false
+   * 2. Check ignore patterns - if any match, return false
+   * 3. Check instrument patterns - if any match, return true
+   * 4. Default: return true (fail-open - create span if no patterns match)
+   */
+  shouldInstrument(spanName) {
+    if (!this.enabled) {
+      return false;
+    }
+    for (const pattern of this.ignorePatterns) {
+      if (pattern.regex.test(spanName)) {
+        return false;
+      }
+    }
+    for (const pattern of this.instrumentPatterns) {
+      if (pattern.enabled && pattern.regex.test(spanName)) {
+        return true;
+      }
+    }
+    return true;
+  }
+  /**
+   * Get statistics about pattern matching (for debugging/monitoring)
+   */
+  getStats() {
+    return {
+      enabled: this.enabled,
+      ignorePatternCount: this.ignorePatterns.length,
+      instrumentPatternCount: this.instrumentPatterns.filter((p) => p.enabled).length
+    };
+  }
+};
+function initializePatternMatcher(config) {
+  new PatternMatcher(config);
+}
+var Logger = class {
+  constructor() {
+    __publicField(this, "level", "on");
+    __publicField(this, "hasLoggedMinimal", false);
+  }
+  /**
+   * Set the logging level
+   */
+  setLevel(level) {
+    this.level = level;
+    this.hasLoggedMinimal = false;
+  }
+  /**
+   * Get the current logging level
+   */
+  getLevel() {
+    return this.level;
+  }
+  /**
+   * Log a minimal initialization message (only shown once in minimal mode)
+   */
+  minimal(message) {
+    if (this.level === "off") {
+      return;
+    }
+    if (this.level === "minimal" && !this.hasLoggedMinimal) {
+      console.log(message);
+      this.hasLoggedMinimal = true;
+      return;
+    }
+    if (this.level === "on") {
+      console.log(message);
+    }
+  }
+  /**
+   * Log an informational message
+   */
+  log(...args) {
+    if (this.level === "on") {
+      console.log(...args);
+    }
+  }
+  /**
+   * Log a warning message (shown in minimal mode)
+   */
+  warn(...args) {
+    if (this.level !== "off") {
+      console.warn(...args);
+    }
+  }
+  /**
+   * Log an error message (shown in minimal mode)
+   */
+  error(...args) {
+    if (this.level !== "off") {
+      console.error(...args);
+    }
+  }
+  /**
+   * Check if full logging is enabled
+   */
+  isEnabled() {
+    return this.level === "on";
+  }
+  /**
+   * Check if minimal logging is enabled
+   */
+  isMinimal() {
+    return this.level === "minimal";
+  }
+  /**
+   * Check if logging is completely disabled
+   */
+  isDisabled() {
+    return this.level === "off";
+  }
+};
+var logger = new Logger();
+
+// src/integrations/effect/effect-tracer.ts
+function createEffectInstrumentation(options = {}) {
+  return Layer.unwrapEffect(
+    Effect.gen(function* () {
+      const config = yield* Effect.tryPromise({
+        try: () => loadConfig(options),
+        catch: (error) => ({
+          _tag: "ConfigError",
+          message: error instanceof Error ? error.message : String(error)
+        })
+      });
+      yield* Effect.sync(() => {
+        const loggingLevel = config.instrumentation.logging || "on";
+        logger.setLevel(loggingLevel);
+      });
+      yield* Effect.sync(() => initializePatternMatcher(config));
+      const otlpEndpoint = options.otlpEndpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318";
+      const serviceName = options.serviceName || process.env.OTEL_SERVICE_NAME || "effect-service";
+      const serviceVersion = options.serviceVersion || process.env.npm_package_version || "1.0.0";
+      const autoExtractMetadata = options.autoExtractMetadata ?? config.effect?.auto_extract_metadata ?? true;
+      const continueExistingTraces = options.continueExistingTraces ?? true;
+      logger.log("\u{1F50D} Effect OpenTelemetry instrumentation");
+      logger.log(`   \u{1F4E1} Endpoint: ${otlpEndpoint}`);
+      logger.log(`   \u{1F3F7}\uFE0F  Service: ${serviceName}`);
+      logger.log(`   \u2705 Auto metadata extraction: ${autoExtractMetadata}`);
+      logger.log(`   \u2705 Continue existing traces: ${continueExistingTraces}`);
+      const otlpLayer = Otlp.layer({
+        baseUrl: otlpEndpoint,
+        resource: {
+          serviceName,
+          serviceVersion,
+          attributes: {
+            "platform.component": "effect",
+            "effect.auto_metadata": autoExtractMetadata,
+            "effect.context_propagation": continueExistingTraces
+          }
+        },
+        // Bridge Effect context to OpenTelemetry global context
+        // This is essential for context propagation to work properly
+        tracerContext: (f, span) => {
+          if (span._tag !== "Span") {
+            return f();
+          }
+          const spanContext = {
+            traceId: span.traceId,
+            spanId: span.spanId,
+            traceFlags: span.sampled ? TraceFlags.SAMPLED : TraceFlags.NONE
+          };
+          const otelSpan = trace.wrapSpanContext(spanContext);
+          return context.with(trace.setSpan(context.active(), otelSpan), f);
+        }
+      }).pipe(Layer.provide(FetchHttpClient.layer));
+      if (autoExtractMetadata) {
+        return otlpLayer;
+      }
+      return otlpLayer;
+    })
+  ).pipe(Layer.orDie);
+}
+var EffectInstrumentationLive = Effect.sync(() => {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318";
+  const serviceName = process.env.OTEL_SERVICE_NAME || "effect-service";
+  const serviceVersion = process.env.npm_package_version || "1.0.0";
+  logger.log("\u{1F50D} Effect OpenTelemetry tracer (Otlp.layer)");
+  logger.log(`   \u{1F4E1} Endpoint: ${endpoint}`);
+  logger.log(`   \u{1F3F7}\uFE0F  Service: ${serviceName}`);
+  return Otlp.layer({
+    baseUrl: endpoint,
+    resource: {
+      serviceName,
+      serviceVersion,
+      attributes: {
+        "platform.component": "effect"
+      }
+    },
+    // CRITICAL: Bridge Effect context to OpenTelemetry global context
+    // This allows NodeSDK auto-instrumentation to see Effect spans as parent spans
+    tracerContext: (f, span) => {
+      if (span._tag !== "Span") {
+        return f();
+      }
+      const spanContext = {
+        traceId: span.traceId,
+        spanId: span.spanId,
+        traceFlags: span.sampled ? TraceFlags.SAMPLED : TraceFlags.NONE
+      };
+      const otelSpan = trace.wrapSpanContext(spanContext);
+      return context.with(trace.setSpan(context.active(), otelSpan), f);
+    }
+  }).pipe(Layer.provide(FetchHttpClient.layer));
+}).pipe(Layer.unwrapEffect);
+
+// src/integrations/effect/effect-helpers.ts
+function annotateUser(_userId, _email) {
+}
+function annotateDataSize(_bytes, _count) {
+}
+function annotateBatch(_size, _batchSize) {
+}
+function annotateLLM(_model, _operation, _inputTokens, _outputTokens) {
+}
+function annotateQuery(_query, _database) {
+}
+function annotateHttpRequest(_method, _url, _statusCode) {
+}
+function annotateError(_error, _context) {
+}
+function annotatePriority(_priority) {
+}
+function annotateCache(_operation, _hit) {
+}
+var createLogicalParentLink = (parentSpan, useSpanLinks) => {
+  if (!useSpanLinks) {
+    return [];
+  }
+  return [
+    {
+      _tag: "SpanLink",
+      span: parentSpan,
+      attributes: {
+        "link.type": "logical_parent",
+        "atrim.relationship": "spawned_by",
+        description: "Logical parent (isolated to prevent context leakage)"
+      }
+    }
+  ];
+};
+var createLogicalParentAttributes = (parentSpan, useAttributes, category, useSpanLinks, customAttributes) => {
+  if (!useAttributes) {
+    return customAttributes;
+  }
+  return {
+    // Logical parent tracking (works in ALL tools)
+    "atrim.logical_parent.span_id": parentSpan.spanId,
+    "atrim.logical_parent.trace_id": parentSpan.traceId,
+    "atrim.logical_parent.name": parentSpan._tag === "Span" ? parentSpan.name : "external",
+    // Categorization and metadata
+    "atrim.fiberset.isolated": true,
+    "atrim.span.category": category,
+    "atrim.has_logical_parent": true,
+    "atrim.isolation.method": useSpanLinks ? "hybrid" : "attributes_only",
+    // User-provided attributes
+    ...customAttributes
+  };
+};
+var runIsolated = (set, effect, name, options) => {
+  const {
+    createRoot = true,
+    captureLogicalParent = true,
+    useSpanLinks = true,
+    useAttributes = true,
+    propagateInterruption,
+    attributes = {},
+    category = "background_task"
+  } = options ?? {};
+  if (!createRoot && !captureLogicalParent) {
+    return FiberSet$1.run(set, effect, { propagateInterruption });
+  }
+  return Effect.gen(function* () {
+    const maybeParent = yield* Effect.serviceOption(Tracer.ParentSpan);
+    if (maybeParent._tag === "None" || !captureLogicalParent) {
+      const isolated2 = effect.pipe(
+        Effect.withSpan(name, {
+          root: createRoot,
+          attributes: {
+            "atrim.fiberset.isolated": createRoot,
+            "atrim.span.category": category,
+            "atrim.has_logical_parent": false,
+            ...attributes
+          }
+        })
+      );
+      return yield* FiberSet$1.run(set, isolated2, { propagateInterruption });
+    }
+    const parent = maybeParent.value;
+    const links = createLogicalParentLink(parent, useSpanLinks);
+    const spanAttributes = createLogicalParentAttributes(
+      parent,
+      useAttributes,
+      category,
+      useSpanLinks,
+      attributes
+    );
+    const isolated = effect.pipe(
+      Effect.withSpan(name, {
+        root: createRoot,
+        links: links.length > 0 ? links : void 0,
+        attributes: spanAttributes
+      })
+    );
+    return yield* FiberSet$1.run(set, isolated, { propagateInterruption });
+  });
+};
+var runWithSpan = (set, name, effect, options) => {
+  return runIsolated(set, effect, name, {
+    createRoot: true,
+    captureLogicalParent: true,
+    useSpanLinks: true,
+    useAttributes: true,
+    ...options
+  });
+};
+var annotateSpawnedTasks = (tasks) => {
+  return Effect.annotateCurrentSpan({
+    "atrim.fiberset.spawned_count": tasks.length,
+    "atrim.fiberset.task_names": tasks.map((t) => t.name).join(","),
+    "atrim.has_background_tasks": true,
+    "atrim.spawned_tasks": JSON.stringify(
+      tasks.map((t) => ({
+        name: t.name,
+        ...t.spanId && { span_id: t.spanId },
+        ...t.category && { category: t.category }
+      }))
+    )
+  });
+};
+var FiberSet = {
+  // Re-export all original FiberSet functions
+  make: FiberSet$1.make,
+  add: FiberSet$1.add,
+  unsafeAdd: FiberSet$1.unsafeAdd,
+  run: FiberSet$1.run,
+  clear: FiberSet$1.clear,
+  join: FiberSet$1.join,
+  awaitEmpty: FiberSet$1.awaitEmpty,
+  size: FiberSet$1.size,
+  runtime: FiberSet$1.runtime,
+  runtimePromise: FiberSet$1.runtimePromise,
+  makeRuntime: FiberSet$1.makeRuntime,
+  makeRuntimePromise: FiberSet$1.makeRuntimePromise,
+  isFiberSet: FiberSet$1.isFiberSet,
+  // Add our isolation helpers
+  runIsolated,
+  runWithSpan
+};
+
+export { EffectInstrumentationLive, FiberSet, annotateBatch, annotateCache, annotateDataSize, annotateError, annotateHttpRequest, annotateLLM, annotatePriority, annotateQuery, annotateSpawnedTasks, annotateUser, createEffectInstrumentation, runIsolated, runWithSpan };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map