autotel 3.5.0 → 3.7.0

package/dist/yaml-config.js

@@ -1,8 +1,227 @@
-export { hasYamlConfig, loadYamlConfig, loadYamlConfigFromFile } from './chunk-CMHVQR6P.js';
-import './chunk-Q4EULJQY.js';
-import './chunk-DPSA4QLA.js';
-import './chunk-55ER2KD5.js';
-import './chunk-J5QENANM.js';
-import './chunk-HA2WBOGQ.js';
-//# sourceMappingURL=yaml-config.js.map
+import { AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler } from "./sampling.js";
+import { t as requireModule } from "./node-require-Db1oDpLj.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/yaml-config.ts
+/**
+* YAML configuration loader for autotel
+*
+* Supports:
+* - Auto-discovery of autotel.yaml in cwd
+* - AUTOTEL_CONFIG_FILE env var override
+* - Environment variable substitution: ${env:VAR} and ${env:VAR:-default}
+*
+* @example Auto-discovery
+* ```yaml
+* # autotel.yaml in project root
+* service:
+*   name: my-service
+* exporter:
+*   endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}
+* ```
+*
+* @example Explicit path
+* ```bash
+* AUTOTEL_CONFIG_FILE=./config/otel.yaml tsx --import autotel/auto src/index.ts
+* ```
+*/
+/**
+* Lazy-load yaml parser (optional peer dependency)
+* Only loads when a YAML config file is actually found
+*/
+function loadYamlParser() {
+	try {
+		return requireModule("yaml").parse;
+	} catch {
+		throw new Error("YAML parser not found. Install with: pnpm add yaml");
+	}
+}
+/**
+* Environment variable substitution regex
+* Matches ${env:VAR_NAME} and ${env:VAR_NAME:-default}
+*/
+const ENV_VAR_PATTERN = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+* Substitute ${env:VAR} and ${env:VAR:-default} in a string
+*
+* @param value - String potentially containing env var references
+* @returns String with env vars substituted
+*
+* @example
+* substituteEnvVars('${env:NODE_ENV:-development}')
+* // Returns 'production' if NODE_ENV=production, else 'development'
+*/
+function substituteEnvVars(value) {
+	return value.replaceAll(ENV_VAR_PATTERN, (_match, varName, defaultValue) => {
+		const envValue = process.env[varName];
+		if (envValue !== void 0) return envValue;
+		if (defaultValue !== void 0) return defaultValue;
+		console.warn(`[autotel] Environment variable ${varName} not set and no default provided`);
+		return "";
+	});
+}
+/**
+* Recursively substitute env vars in an object
+*
+* @param obj - Object to process
+* @returns Object with all string values having env vars substituted
+*/
+function substituteEnvVarsDeep(obj) {
+	if (typeof obj === "string") return substituteEnvVars(obj);
+	if (Array.isArray(obj)) return obj.map((item) => substituteEnvVarsDeep(item));
+	if (obj && typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) result[key] = substituteEnvVarsDeep(value);
+		return result;
+	}
+	return obj;
+}
+/**
+* Find YAML config file path
+*
+* Priority:
+* 1. AUTOTEL_CONFIG_FILE env var (explicit path)
+* 2. autotel.yaml in cwd (convention)
+* 3. autotel.yml in cwd (alternative extension)
+*
+* @returns File path if found, null otherwise
+*/
+function findConfigFile() {
+	const envPath = process.env.AUTOTEL_CONFIG_FILE;
+	if (envPath) {
+		const resolved = path.resolve(envPath);
+		if (existsSync(resolved)) return resolved;
+		console.warn(`[autotel] Config file not found: ${envPath}`);
+		return null;
+	}
+	const conventionPath = path.resolve(process.cwd(), "autotel.yaml");
+	if (existsSync(conventionPath)) return conventionPath;
+	const altPath = path.resolve(process.cwd(), "autotel.yml");
+	if (existsSync(altPath)) return altPath;
+	return null;
+}
+/**
+* Convert YAML config structure to AutotelConfig
+*
+* @param yaml - Parsed and env-substituted YAML config
+* @returns Partial AutotelConfig ready for merging
+*/
+function yamlToAutotelConfig(yaml) {
+	const config = {};
+	if (yaml.service?.name) config.service = yaml.service.name;
+	if (yaml.service?.version) config.version = yaml.service.version;
+	if (yaml.service?.environment) config.environment = yaml.service.environment;
+	if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;
+	if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;
+	if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;
+	if (yaml.resource) config.resourceAttributes = yaml.resource;
+	if (yaml.autoInstrumentations) config.autoInstrumentations = yaml.autoInstrumentations;
+	if (yaml.debug !== void 0) config.debug = yaml.debug;
+	if (yaml.sampling?.preset) {
+		warnOnIgnoredPresetOverrides(yaml.sampling);
+		config.sampling = yaml.sampling.preset;
+	} else {
+		const sampler = createSamplerFromYaml(yaml.sampling);
+		if (sampler) config.sampler = sampler;
+	}
+	return config;
+}
+function createSamplerFromYaml(sampling) {
+	if (!sampling) return void 0;
+	if (sampling.preset) return void 0;
+	const type = sampling.type ?? "adaptive";
+	try {
+		switch (type) {
+			case "adaptive": return new AdaptiveSampler({
+				baselineSampleRate: sampling.baseline_rate,
+				alwaysSampleErrors: sampling.always_sample_errors,
+				alwaysSampleSlow: sampling.always_sample_slow,
+				slowThresholdMs: sampling.slow_threshold_ms
+			});
+			case "always_on": return new AlwaysSampler();
+			case "always_off": return new NeverSampler();
+			case "ratio":
+				if (sampling.ratio === void 0) {
+					console.warn("[autotel] sampling.ratio missing in YAML sampling config. Falling back to adaptive sampler.");
+					return new AdaptiveSampler();
+				}
+				return new RandomSampler(sampling.ratio);
+			default:
+				console.warn(`[autotel] Unknown sampling type "${type}" in YAML config. Falling back to defaults.`);
+				return;
+		}
+	} catch (error) {
+		console.warn(`[autotel] Failed to configure sampling from YAML: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+}
+function warnOnIgnoredPresetOverrides(sampling) {
+	const ignoredFields = [
+		"type",
+		"ratio",
+		"baseline_rate",
+		"always_sample_errors",
+		"always_sample_slow",
+		"slow_threshold_ms"
+	].filter((field) => sampling[field] !== void 0);
+	if (ignoredFields.length === 0) return;
+	console.warn(`[autotel] sampling.preset="${sampling.preset}" ignores these YAML fields: ${ignoredFields.join(", ")}. Use the programmatic API with sampler or samplingPresets.*(...) for tuned presets.`);
+}
+/**
+* Load and parse YAML config file (auto-discovery)
+*
+* Automatically finds and loads autotel.yaml or uses AUTOTEL_CONFIG_FILE.
+* Returns null if no config file found (not an error - YAML config is optional).
+*
+* @returns Partial AutotelConfig or null if no config file found
+*
+* @example
+* const yamlConfig = loadYamlConfig();
+* if (yamlConfig) {
+*   init({ ...yamlConfig, debug: true });
+* }
+*/
+function loadYamlConfig() {
+	const filePath = findConfigFile();
+	if (!filePath) return null;
+	try {
+		const content = readFileSync(filePath, "utf8");
+		return yamlToAutotelConfig(substituteEnvVarsDeep(loadYamlParser()(content)));
+	} catch (error) {
+		console.error(`[autotel] Failed to load YAML config from ${filePath}:`, error);
+		return null;
+	}
+}
+/**
+* Load YAML config from a specific file path
+*
+* Unlike loadYamlConfig(), this throws if the file cannot be read.
+*
+* @param filePath - Path to YAML config file
+* @returns Partial AutotelConfig
+* @throws Error if file cannot be read or parsed
+*
+* @example
+* import { loadYamlConfigFromFile } from 'autotel/yaml';
+* import { init } from 'autotel';
+*
+* const config = loadYamlConfigFromFile('./config/otel.yaml');
+* init({ ...config, debug: true });
+*/
+function loadYamlConfigFromFile(filePath) {
+	const content = readFileSync(path.resolve(filePath), "utf8");
+	return yamlToAutotelConfig(substituteEnvVarsDeep(loadYamlParser()(content)));
+}
+/**
+* Check if a YAML config file exists (without loading it)
+*
+* @returns true if a config file would be found by loadYamlConfig()
+*/
+function hasYamlConfig() {
+	return findConfigFile() !== null;
+}
+
+//#endregion
+export { hasYamlConfig, loadYamlConfig, loadYamlConfigFromFile };
 //# sourceMappingURL=yaml-config.js.map

package/dist/yaml-config.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"yaml-config.js"}
+{"version":3,"file":"yaml-config.js","names":[],"sources":["../src/yaml-config.ts"],"sourcesContent":["/**\n * YAML configuration loader for autotel\n *\n * Supports:\n * - Auto-discovery of autotel.yaml in cwd\n * - AUTOTEL_CONFIG_FILE env var override\n * - Environment variable substitution: ${env:VAR} and ${env:VAR:-default}\n *\n * @example Auto-discovery\n * ```yaml\n * # autotel.yaml in project root\n * service:\n *   name: my-service\n * exporter:\n *   endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}\n * ```\n *\n * @example Explicit path\n * ```bash\n * AUTOTEL_CONFIG_FILE=./config/otel.yaml tsx --import autotel/auto src/index.ts\n * ```\n */\n\nimport { readFileSync, existsSync } from 'node:fs';\nimport path from 'node:path';\nimport type { AutotelConfig } from './init';\nimport {\n  AdaptiveSampler,\n  AlwaysSampler,\n  NeverSampler,\n  RandomSampler,\n  type SamplingPreset,\n} from './sampling';\n\n/**\n * Lazy-load yaml parser (optional peer dependency)\n * Only loads when a YAML config file is actually found\n */\nimport { requireModule } from './node-require';\n\nfunction loadYamlParser(): (content: string) => unknown {\n  try {\n    const mod = requireModule<{ parse: (content: string) => unknown }>('yaml');\n    return mod.parse;\n  } catch {\n    throw new Error('YAML parser not found. Install with: pnpm add yaml');\n  }\n}\n\n/**\n * YAML config structure\n * Maps to AutotelConfig with user-friendly naming\n */\nexport interface YamlConfig {\n  service?: {\n    name?: string;\n    version?: string;\n    environment?: string;\n  };\n  exporter?: {\n    endpoint?: string;\n    protocol?: 'http' | 'grpc';\n    headers?: Record<string, string>;\n  };\n  resource?: Record<string, string | number | boolean>;\n  sampling?: {\n    preset?: SamplingPreset;\n    type?: 'adaptive' | 'always_on' | 'always_off' | 'ratio';\n    ratio?: number;\n    baseline_rate?: number;\n    always_sample_errors?: boolean;\n    always_sample_slow?: boolean;\n    slow_threshold_ms?: number;\n  };\n  autoInstrumentations?: string[] | Record<string, { enabled?: boolean }>;\n  debug?: boolean;\n}\n\n/**\n * Environment variable substitution regex\n * Matches ${env:VAR_NAME} and ${env:VAR_NAME:-default}\n */\nconst ENV_VAR_PATTERN = /\\$\\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\\}/g;\n\n/**\n * Substitute ${env:VAR} and ${env:VAR:-default} in a string\n *\n * @param value - String potentially containing env var references\n * @returns String with env vars substituted\n *\n * @example\n * substituteEnvVars('${env:NODE_ENV:-development}')\n * // Returns 'production' if NODE_ENV=production, else 'development'\n */\nfunction substituteEnvVars(value: string): string {\n  return value.replaceAll(\n    ENV_VAR_PATTERN,\n    (_match, varName: string, defaultValue?: string) => {\n      const envValue = process.env[varName];\n      if (envValue !== undefined) return envValue;\n      if (defaultValue !== undefined) return defaultValue;\n      console.warn(\n        `[autotel] Environment variable ${varName} not set and no default provided`,\n      );\n      return '';\n    },\n  );\n}\n\n/**\n * Recursively substitute env vars in an object\n *\n * @param obj - Object to process\n * @returns Object with all string values having env vars substituted\n */\nfunction substituteEnvVarsDeep(obj: unknown): unknown {\n  if (typeof obj === 'string') {\n    return substituteEnvVars(obj);\n  }\n  if (Array.isArray(obj)) {\n    return obj.map((item) => substituteEnvVarsDeep(item));\n  }\n  if (obj && typeof obj === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(obj)) {\n      result[key] = substituteEnvVarsDeep(value);\n    }\n    return result;\n  }\n  return obj;\n}\n\n/**\n * Find YAML config file path\n *\n * Priority:\n * 1. AUTOTEL_CONFIG_FILE env var (explicit path)\n * 2. autotel.yaml in cwd (convention)\n * 3. autotel.yml in cwd (alternative extension)\n *\n * @returns File path if found, null otherwise\n */\nfunction findConfigFile(): string | null {\n  // Check env var first (explicit takes priority)\n  const envPath = process.env.AUTOTEL_CONFIG_FILE;\n  if (envPath) {\n    const resolved = path.resolve(envPath);\n    if (existsSync(resolved)) return resolved;\n    console.warn(`[autotel] Config file not found: ${envPath}`);\n    return null;\n  }\n\n  // Auto-discover autotel.yaml in cwd\n  const conventionPath = path.resolve(process.cwd(), 'autotel.yaml');\n  if (existsSync(conventionPath)) return conventionPath;\n\n  // Also check .yml extension\n  const altPath = path.resolve(process.cwd(), 'autotel.yml');\n  if (existsSync(altPath)) return altPath;\n\n  return null;\n}\n\n/**\n * Convert YAML config structure to AutotelConfig\n *\n * @param yaml - Parsed and env-substituted YAML config\n * @returns Partial AutotelConfig ready for merging\n */\nfunction yamlToAutotelConfig(yaml: YamlConfig): Partial<AutotelConfig> {\n  const config: Partial<AutotelConfig> = {};\n\n  // Service configuration\n  if (yaml.service?.name) config.service = yaml.service.name;\n  if (yaml.service?.version) config.version = yaml.service.version;\n  if (yaml.service?.environment) config.environment = yaml.service.environment;\n\n  // Exporter configuration\n  if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;\n  if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;\n  if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;\n\n  // Resource attributes (flattened)\n  if (yaml.resource) config.resourceAttributes = yaml.resource;\n\n  // Integrations\n  if (yaml.autoInstrumentations)\n    config.autoInstrumentations = yaml.autoInstrumentations;\n\n  // Debug mode\n  if (yaml.debug !== undefined) config.debug = yaml.debug;\n\n  // Sampling configuration\n  if (yaml.sampling?.preset) {\n    warnOnIgnoredPresetOverrides(yaml.sampling);\n    config.sampling = yaml.sampling.preset;\n  } else {\n    const sampler = createSamplerFromYaml(yaml.sampling);\n    if (sampler) config.sampler = sampler;\n  }\n\n  return config;\n}\n\nfunction createSamplerFromYaml(\n  sampling?: YamlConfig['sampling'],\n): AutotelConfig['sampler'] {\n  if (!sampling) return undefined;\n  if (sampling.preset) return undefined;\n\n  const type = sampling.type ?? 'adaptive';\n\n  try {\n    switch (type) {\n      case 'adaptive': {\n        return new AdaptiveSampler({\n          baselineSampleRate: sampling.baseline_rate,\n          alwaysSampleErrors: sampling.always_sample_errors,\n          alwaysSampleSlow: sampling.always_sample_slow,\n          slowThresholdMs: sampling.slow_threshold_ms,\n        });\n      }\n      case 'always_on': {\n        return new AlwaysSampler();\n      }\n      case 'always_off': {\n        return new NeverSampler();\n      }\n      case 'ratio': {\n        if (sampling.ratio === undefined) {\n          console.warn(\n            '[autotel] sampling.ratio missing in YAML sampling config. Falling back to adaptive sampler.',\n          );\n          return new AdaptiveSampler();\n        }\n        return new RandomSampler(sampling.ratio);\n      }\n      default: {\n        console.warn(\n          `[autotel] Unknown sampling type \"${type}\" in YAML config. Falling back to defaults.`,\n        );\n        return undefined;\n      }\n    }\n  } catch (error) {\n    console.warn(\n      `[autotel] Failed to configure sampling from YAML: ${error instanceof Error ? error.message : String(error)}`,\n    );\n    return undefined;\n  }\n}\n\nfunction warnOnIgnoredPresetOverrides(\n  sampling: NonNullable<YamlConfig['sampling']>,\n): void {\n  const ignoredFields = [\n    'type',\n    'ratio',\n    'baseline_rate',\n    'always_sample_errors',\n    'always_sample_slow',\n    'slow_threshold_ms',\n  ].filter((field) => sampling[field as keyof typeof sampling] !== undefined);\n\n  if (ignoredFields.length === 0) {\n    return;\n  }\n\n  console.warn(\n    `[autotel] sampling.preset=\"${sampling.preset}\" ignores these YAML fields: ${ignoredFields.join(', ')}. ` +\n      'Use the programmatic API with sampler or samplingPresets.*(...) for tuned presets.',\n  );\n}\n\n/**\n * Load and parse YAML config file (auto-discovery)\n *\n * Automatically finds and loads autotel.yaml or uses AUTOTEL_CONFIG_FILE.\n * Returns null if no config file found (not an error - YAML config is optional).\n *\n * @returns Partial AutotelConfig or null if no config file found\n *\n * @example\n * const yamlConfig = loadYamlConfig();\n * if (yamlConfig) {\n *   init({ ...yamlConfig, debug: true });\n * }\n */\nexport function loadYamlConfig(): Partial<AutotelConfig> | null {\n  const filePath = findConfigFile();\n  if (!filePath) return null;\n\n  try {\n    const content = readFileSync(filePath, 'utf8');\n    const parseYaml = loadYamlParser();\n    const rawYaml = parseYaml(content) as YamlConfig;\n    const substituted = substituteEnvVarsDeep(rawYaml) as YamlConfig;\n    return yamlToAutotelConfig(substituted);\n  } catch (error) {\n    console.error(\n      `[autotel] Failed to load YAML config from ${filePath}:`,\n      error,\n    );\n    return null;\n  }\n}\n\n/**\n * Load YAML config from a specific file path\n *\n * Unlike loadYamlConfig(), this throws if the file cannot be read.\n *\n * @param filePath - Path to YAML config file\n * @returns Partial AutotelConfig\n * @throws Error if file cannot be read or parsed\n *\n * @example\n * import { loadYamlConfigFromFile } from 'autotel/yaml';\n * import { init } from 'autotel';\n *\n * const config = loadYamlConfigFromFile('./config/otel.yaml');\n * init({ ...config, debug: true });\n */\nexport function loadYamlConfigFromFile(\n  filePath: string,\n): Partial<AutotelConfig> {\n  const resolved = path.resolve(filePath);\n  const content = readFileSync(resolved, 'utf8');\n  const parseYaml = loadYamlParser();\n  const rawYaml = parseYaml(content) as YamlConfig;\n  const substituted = substituteEnvVarsDeep(rawYaml) as YamlConfig;\n  return yamlToAutotelConfig(substituted);\n}\n\n/**\n * Check if a YAML config file exists (without loading it)\n *\n * @returns true if a config file would be found by loadYamlConfig()\n */\nexport function hasYamlConfig(): boolean {\n  return findConfigFile() !== null;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -208,6 +208,16 @@
       "import": "./dist/security-schema.js",
       "require": "./dist/security-schema.cjs"
     },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js",
+      "require": "./dist/validate.cjs"
+    },
+    "./validation-attributes": {
+      "types": "./dist/validation-attributes.d.ts",
+      "import": "./dist/validation-attributes.js",
+      "require": "./dist/validation-attributes.cjs"
+    },
     "./test-span-collector": {
       "types": "./dist/test-span-collector.d.ts",
       "import": "./dist/test-span-collector.js",
@@ -345,7 +355,7 @@
     "pino": "^10.3.1",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsup": "^8.5.1",
+    "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.1",
@@ -365,9 +375,9 @@
   },
   "homepage": "https://github.com/jagreehal/autotel#readme",
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test",
-    "dev": "tsup --watch",
+    "dev": "tsdown --watch",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "format": "prettier --write .",

package/src/define-event.ts

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
 import { track } from './track';
+import { hashJson } from './stable-hash';
 import type { EventSchemaMetadata } from './event-subscriber';
 
 type SafeParseResult<T> =
@@ -34,7 +34,7 @@ export function defineEvent<
     ? {
         source: 'zod' as const,
         jsonSchema,
-        hash: hashSchema(jsonSchema),
+        hash: hashJson(jsonSchema),
       }
     : undefined;
 
@@ -56,22 +56,3 @@ export function defineEvent<
     },
   };
 }
-
-function hashSchema(schema: unknown): string {
-  return createHash('sha256').update(stableStringify(schema)).digest('hex');
-}
-
-function stableStringify(value: unknown): string {
-  if (value === null || value === undefined || typeof value !== 'object') {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
-  }
-  const obj = value as Record<string, unknown>;
-  const body = Object.keys(obj)
-    .sort()
-    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
-    .join(',');
-  return '{' + body + '}';
-}

package/src/index.ts

@@ -136,6 +136,9 @@ export { flush, shutdown } from './shutdown';
 // Request logger
 export {
   getRequestLogger,
+  getRequestLoggerSafe,
+  createNoopRequestLogger,
+  hasRequestContext,
   runWithRequestContext,
   type RequestLogger,
   type RequestLogSnapshot,

package/src/request-logger.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { trace as otelTrace } from '@opentelemetry/api';
-import { getRequestLogger, runWithRequestContext } from './request-logger';
+import {
+  createNoopRequestLogger,
+  getRequestLogger,
+  getRequestLoggerSafe,
+  hasRequestContext,
+  runWithRequestContext,
+} from './request-logger';
 import type { TraceContext } from './trace-context';
 
 function createMockContext(): TraceContext {
@@ -491,3 +497,49 @@ describe('getRequestLogger', () => {
     });
   });
 });
+
+describe('best-effort helpers', () => {
+  it('hasRequestContext is false with no ctx, ALS, or active span', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(hasRequestContext()).toBe(false);
+  });
+
+  it('hasRequestContext is true when an explicit ctx is passed', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(hasRequestContext(createMockContext())).toBe(true);
+  });
+
+  it('hasRequestContext is true inside runWithRequestContext', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    runWithRequestContext(createMockContext(), () => {
+      expect(hasRequestContext()).toBe(true);
+    });
+  });
+
+  it('getRequestLoggerSafe returns null when no context is available', () => {
+    vi.spyOn(otelTrace, 'getActiveSpan').mockReturnValue(undefined);
+    expect(getRequestLoggerSafe()).toBeNull();
+  });
+
+  it('getRequestLoggerSafe returns a working logger when ctx is provided', () => {
+    const ctx = createMockContext();
+    const log = getRequestLoggerSafe(ctx);
+    expect(log).not.toBeNull();
+    log?.set({ user: { id: 'safe-user' } });
+    expect(ctx.setAttributes).toHaveBeenCalledWith({ 'user.id': 'safe-user' });
+  });
+
+  it('createNoopRequestLogger never throws and emits an empty snapshot', () => {
+    const log = createNoopRequestLogger();
+    expect(() => {
+      log.set({ a: 1 });
+      log.info('hi', { b: 2 });
+      log.warn('careful');
+      log.error(new Error('boom'));
+    }).not.toThrow();
+    expect(log.getContext()).toEqual({});
+    const snapshot = log.emitNow();
+    expect(snapshot.traceId).toBe('');
+    expect(snapshot.context).toEqual({});
+  });
+});

package/src/request-logger.ts

@@ -282,3 +282,61 @@ export function getRequestLogger(
     },
   };
 }
+
+/**
+ * Returns `true` when a request-logger context can be resolved without throwing —
+ * i.e. an explicit `ctx` was provided, a `runWithRequestContext()` scope is active,
+ * or there is an active OpenTelemetry span.
+ *
+ * Use this to branch on observability availability instead of wrapping
+ * {@link getRequestLogger} in try/catch.
+ */
+export function hasRequestContext(ctx?: TraceContext): boolean {
+  if (ctx) return true;
+  if (requestContextStore.getStore()) return true;
+  return otelTrace.getActiveSpan() != null;
+}
+
+/**
+ * Like {@link getRequestLogger}, but returns `null` instead of throwing when no
+ * request context is available. Intended for best-effort instrumentation where a
+ * missing telemetry context must never crash business logic.
+ */
+export function getRequestLoggerSafe(
+  ctx?: TraceContext,
+  options?: RequestLoggerOptions,
+): RequestLogger | null {
+  if (!hasRequestContext(ctx)) return null;
+  return getRequestLogger(ctx, options);
+}
+
+/**
+ * A no-op {@link RequestLogger} whose methods do nothing. Used as a fallback by
+ * best-effort instrumentation so wrapped handlers can run un-instrumented without
+ * branching on logger presence.
+ */
+export function createNoopRequestLogger(): RequestLogger {
+  const snapshot = (): RequestLogSnapshot => ({
+    timestamp: new Date().toISOString(),
+    traceId: '',
+    spanId: '',
+    correlationId: '',
+    context: {},
+  });
+
+  return {
+    set() {},
+    info() {},
+    warn() {},
+    error() {},
+    getContext() {
+      return {};
+    },
+    emitNow() {
+      return snapshot();
+    },
+    fork(_label, fn) {
+      void Promise.resolve().then(() => fn());
+    },
+  };
+}

package/src/stable-hash.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Deterministic JSON stringify with sorted object keys, so two structurally
+ * equal values always produce the same string regardless of key insertion
+ * order. Shared by `defineEvent` and the validation layer for stable schema
+ * hashes.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+  }
+  const obj = value as Record<string, unknown>;
+  const body = Object.keys(obj)
+    .toSorted()
+    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+    .join(',');
+  return '{' + body + '}';
+}
+
+/** Stable sha256 of any JSON-serializable value. */
+export function hashJson(value: unknown): string {
+  return createHash('sha256').update(stableStringify(value)).digest('hex');
+}