@uploadista/observability 0.0.3

package/dist/upload/metrics.js

@@ -0,0 +1,80 @@
+import { Metric, MetricBoundaries } from "effect";
+// ============================================================================
+// Upload Server Metrics
+// ============================================================================
+/**
+ * Upload server metrics for tracking upload operations
+ */
+export const createUploadServerMetrics = () => ({
+    // Counter metrics
+    uploadCreatedTotal: Metric.counter("upload_created_total", {
+        description: "Total number of uploads created",
+    }),
+    uploadCompletedTotal: Metric.counter("upload_completed_total", {
+        description: "Total number of uploads completed successfully",
+    }),
+    uploadFailedTotal: Metric.counter("upload_failed_total", {
+        description: "Total number of uploads that failed",
+    }),
+    chunkUploadedTotal: Metric.counter("chunk_uploaded_total", {
+        description: "Total number of chunks uploaded",
+    }),
+    uploadFromUrlTotal: Metric.counter("upload_from_url_total", {
+        description: "Total number of URL-based uploads",
+    }),
+    uploadFromUrlSuccessTotal: Metric.counter("upload_from_url_success_total", {
+        description: "Total number of successful URL-based uploads",
+    }),
+    uploadFromUrlFailedTotal: Metric.counter("upload_from_url_failed_total", {
+        description: "Total number of failed URL-based uploads",
+    }),
+    // Histogram metrics
+    uploadDurationHistogram: Metric.histogram("upload_duration_seconds", MetricBoundaries.exponential({
+        start: 0.01, // 10ms
+        factor: 2,
+        count: 20, // Up to ~10 seconds
+    }), "Duration of complete upload operations in seconds"),
+    chunkUploadDurationHistogram: Metric.histogram("chunk_upload_duration_seconds", MetricBoundaries.exponential({
+        start: 0.001, // 1ms
+        factor: 2,
+        count: 15, // Up to ~32 seconds
+    }), "Duration of individual chunk uploads in seconds"),
+    uploadFileSizeHistogram: Metric.histogram("upload_file_size_bytes", MetricBoundaries.exponential({
+        start: 1024, // 1KB
+        factor: 2,
+        count: 25, // Up to ~33GB
+    }), "Size of uploaded files in bytes"),
+    chunkSizeHistogram: Metric.histogram("chunk_size_bytes", MetricBoundaries.linear({
+        start: 262_144, // 256KB
+        width: 262_144, // 256KB increments
+        count: 20, // Up to ~5MB
+    }), "Size of uploaded chunks in bytes"),
+    // Gauge metrics
+    activeUploadsGauge: Metric.gauge("active_uploads", {
+        description: "Number of currently active uploads",
+    }),
+    uploadThroughputGauge: Metric.gauge("upload_throughput_bytes_per_second", {
+        description: "Current upload throughput in bytes per second",
+    }),
+    // Summary metrics for latency percentiles
+    uploadLatencySummary: Metric.summary({
+        name: "upload_latency_seconds",
+        maxAge: "10 minutes",
+        maxSize: 1000,
+        error: 0.01,
+        quantiles: [0.5, 0.9, 0.95, 0.99],
+        description: "Upload operation latency percentiles",
+    }),
+    chunkLatencySummary: Metric.summary({
+        name: "chunk_latency_seconds",
+        maxAge: "10 minutes",
+        maxSize: 1000,
+        error: 0.01,
+        quantiles: [0.5, 0.9, 0.95, 0.99],
+        description: "Chunk upload latency percentiles",
+    }),
+});
+/**
+ * Default upload server metrics instance
+ */
+export const uploadServerMetrics = createUploadServerMetrics();

package/dist/upload/testing.d.ts

@@ -0,0 +1,32 @@
+import { Layer } from "effect";
+import { UploadObservability } from "../core/layers.js";
+/**
+ * Create a test upload observability layer that doesn't actually emit metrics
+ * but validates that the observability system is wired correctly
+ */
+export declare const UploadObservabilityTest: Layer.Layer<UploadObservability, never, never>;
+/**
+ * Get metrics for validation (useful for testing metric definitions)
+ */
+export declare const getTestMetrics: () => {
+    uploadCreatedTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadCompletedTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadFailedTotal: import("effect/Metric").Metric.Counter<number>;
+    chunkUploadedTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadFromUrlTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadFromUrlSuccessTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadFromUrlFailedTotal: import("effect/Metric").Metric.Counter<number>;
+    uploadDurationHistogram: import("effect/Metric").Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    chunkUploadDurationHistogram: import("effect/Metric").Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    uploadFileSizeHistogram: import("effect/Metric").Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    chunkSizeHistogram: import("effect/Metric").Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>;
+    activeUploadsGauge: import("effect/Metric").Metric.Gauge<number>;
+    uploadThroughputGauge: import("effect/Metric").Metric.Gauge<number>;
+    uploadLatencySummary: import("effect/Metric").Metric.Summary<number>;
+    chunkLatencySummary: import("effect/Metric").Metric.Summary<number>;
+};
+/**
+ * Validate that all required metrics exist
+ */
+export declare const validateMetricsExist: () => boolean;
+//# sourceMappingURL=testing.d.ts.map

package/dist/upload/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/upload/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAOxD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,gDASlC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAAoC,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,oBAAoB,eA4BhC,CAAC"}

package/dist/upload/testing.js

@@ -0,0 +1,52 @@
+import { Layer } from "effect";
+import { UploadObservability } from "../core/layers.js";
+import { createUploadServerMetrics } from "./metrics.js";
+// ============================================================================
+// Upload Observability Testing Utilities
+// ============================================================================
+/**
+ * Create a test upload observability layer that doesn't actually emit metrics
+ * but validates that the observability system is wired correctly
+ */
+export const UploadObservabilityTest = Layer.succeed(UploadObservability, {
+    serviceName: "uploadista-upload-server-test",
+    enabled: true,
+    metrics: {
+        uploadCreated: () => Promise.resolve(),
+        uploadCompleted: () => Promise.resolve(),
+        uploadFailed: () => Promise.resolve(),
+        chunkUploaded: () => Promise.resolve(),
+    },
+});
+/**
+ * Get metrics for validation (useful for testing metric definitions)
+ */
+export const getTestMetrics = () => createUploadServerMetrics();
+/**
+ * Validate that all required metrics exist
+ */
+export const validateMetricsExist = () => {
+    const metrics = getTestMetrics();
+    const requiredMetrics = [
+        "uploadCreatedTotal",
+        "uploadCompletedTotal",
+        "uploadFailedTotal",
+        "chunkUploadedTotal",
+        "uploadFromUrlTotal",
+        "uploadFromUrlSuccessTotal",
+        "uploadFromUrlFailedTotal",
+        "uploadDurationHistogram",
+        "chunkUploadDurationHistogram",
+        "uploadFileSizeHistogram",
+        "chunkSizeHistogram",
+        "activeUploadsGauge",
+        "uploadThroughputGauge",
+        "uploadLatencySummary",
+        "chunkLatencySummary",
+    ];
+    const missingMetrics = requiredMetrics.filter((name) => !(name in metrics));
+    if (missingMetrics.length > 0) {
+        throw new Error(`Missing required metrics: ${missingMetrics.join(", ")}`);
+    }
+    return true;
+};

package/dist/upload/tracing.d.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+/**
+ * Wrap an Effect with an upload operation span
+ */
+export declare const withUploadSpan: <A, E, R>(operation: string, attributes?: Record<string, unknown>) => (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * Add upload context to the current span
+ */
+export declare const withUploadContext: (context: {
+    uploadId?: string;
+    fileName?: string;
+    fileSize?: number;
+    storageId?: string;
+    mimeType?: string;
+}) => Effect.Effect<void, never, never>;
+/**
+ * Add chunk context to the current span
+ */
+export declare const withChunkContext: (context: {
+    uploadId: string;
+    chunkSize: number;
+    offset: number;
+    totalSize?: number;
+}) => Effect.Effect<void, never, never>;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/upload/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/upload/tracing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAMhC;;GAEG;AACH,eAAO,MAAM,cAAc,GACxB,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,MAAM,EAAE,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAChE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAQpD,CAAC;AAEN;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,sCAOG,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,sCAUG,CAAC"}

package/dist/upload/tracing.js

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+// ============================================================================
+// Upload Tracing Utilities
+// ============================================================================
+/**
+ * Wrap an Effect with an upload operation span
+ */
+export const withUploadSpan = (operation, attributes) => (effect) => effect.pipe(Effect.withSpan(`upload-${operation}`, {
+    attributes: {
+        "upload.operation": operation,
+        ...attributes,
+    },
+}));
+/**
+ * Add upload context to the current span
+ */
+export const withUploadContext = (context) => Effect.annotateCurrentSpan({
+    "upload.id": context.uploadId ?? "unknown",
+    "upload.file_name": context.fileName ?? "unknown",
+    "upload.file_size": context.fileSize?.toString() ?? "0",
+    "upload.storage_id": context.storageId ?? "unknown",
+    "upload.mime_type": context.mimeType ?? "unknown",
+});
+/**
+ * Add chunk context to the current span
+ */
+export const withChunkContext = (context) => Effect.annotateCurrentSpan({
+    "chunk.upload_id": context.uploadId,
+    "chunk.size": context.chunkSize.toString(),
+    "chunk.offset": context.offset.toString(),
+    "chunk.total_size": context.totalSize?.toString() ?? "0",
+    "chunk.progress": context.totalSize && context.totalSize > 0
+        ? ((context.offset / context.totalSize) * 100).toFixed(2)
+        : "0",
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@uploadista/observability",
+  "type": "module",
+  "version": "0.0.3",
+  "description": "Observability package for Uploadista",
+  "license": "MIT",
+  "author": "Uploadista",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@effect/opentelemetry": "0.58.0",
+    "@opentelemetry/sdk-logs": "0.206.0",
+    "@opentelemetry/sdk-metrics": "2.1.0",
+    "@opentelemetry/sdk-trace-base": "2.1.0",
+    "@opentelemetry/sdk-trace-node": "2.1.0",
+    "@opentelemetry/sdk-trace-web": "2.1.0",
+    "effect": "3.18.4"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "4.20251011.0",
+    "@types/node": "24.8.1",
+    "typescript": "5.9.3",
+    "@uploadista/typescript-config": "0.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "format": "biome format --write ./src",
+    "lint": "biome lint --write ./src",
+    "check": "biome check --write ./src",
+    "clean": "rimraf -rf dist && rimraf -rf .turbo && rimraf tsconfig.tsbuildinfo"
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,187 @@
+import { Effect, Metric } from "effect";
+import type { StorageMetrics } from "./metrics.js";
+
+// ============================================================================
+// Generic Storage Error Classification and Tracking
+// ============================================================================
+
+export type StorageErrorCategory =
+  | "network_error"
+  | "authentication_error"
+  | "authorization_error"
+  | "throttling_error"
+  | "server_error"
+  | "client_error"
+  | "unknown_error";
+
+// Generic error classifier - can be extended per storage type
+export const classifyStorageError = (error: unknown): StorageErrorCategory => {
+  if (!error || typeof error !== "object") return "unknown_error";
+
+  const errorCode = "code" in error ? error.code : undefined;
+  const errorName = "name" in error ? error.name : undefined;
+  const errorMessage =
+    error instanceof Error ? error.message.toLowerCase() : "";
+
+  // Network errors (common across all storage types)
+  if (
+    errorCode === "NetworkError" ||
+    errorCode === "ECONNRESET" ||
+    errorCode === "ENOTFOUND" ||
+    errorCode === "ETIMEDOUT" ||
+    errorMessage.indexOf("network") >= 0 ||
+    errorMessage.indexOf("timeout") >= 0
+  ) {
+    return "network_error";
+  }
+
+  // Authentication errors (common patterns)
+  if (
+    errorCode === "InvalidAccessKeyId" ||
+    errorCode === "SignatureDoesNotMatch" ||
+    errorCode === "TokenRefreshRequired" ||
+    errorCode === "AuthenticationFailed" ||
+    errorName === "AuthenticationError" ||
+    errorMessage.indexOf("authentication") >= 0 ||
+    errorMessage.indexOf("unauthorized") >= 0
+  ) {
+    return "authentication_error";
+  }
+
+  // Authorization errors
+  if (
+    errorCode === "AccessDenied" ||
+    errorCode === "AccountProblem" ||
+    errorCode === "Forbidden" ||
+    errorName === "AuthorizationError" ||
+    errorMessage.indexOf("forbidden") >= 0 ||
+    errorMessage.indexOf("permission") >= 0
+  ) {
+    return "authorization_error";
+  }
+
+  // Throttling errors
+  if (
+    errorCode === "SlowDown" ||
+    errorCode === "RequestTimeTooSkewed" ||
+    errorCode === "TooManyRequests" ||
+    errorName === "ThrottlingError" ||
+    errorMessage.indexOf("throttl") >= 0 ||
+    errorMessage.indexOf("rate limit") >= 0
+  ) {
+    return "throttling_error";
+  }
+
+  // Server errors
+  if (
+    errorCode === "InternalError" ||
+    errorCode === "ServiceUnavailable" ||
+    errorCode === "InternalServerError" ||
+    errorName === "ServerError" ||
+    errorMessage.indexOf("server error") >= 0 ||
+    errorMessage.indexOf("service unavailable") >= 0
+  ) {
+    return "server_error";
+  }
+
+  // Client errors
+  if (
+    errorCode === "InvalidRequest" ||
+    errorCode === "MalformedXML" ||
+    errorCode === "RequestEntityTooLarge" ||
+    errorCode === "BadRequest" ||
+    errorName === "ClientError" ||
+    errorMessage.indexOf("bad request") >= 0 ||
+    errorMessage.indexOf("invalid") >= 0
+  ) {
+    return "client_error";
+  }
+
+  return "unknown_error";
+};
+
+// Storage-specific error classifier factory
+export const createStorageErrorClassifier = (
+  storageType: string,
+  customErrorMapping?: (error: unknown) => StorageErrorCategory | null,
+) => {
+  return (error: unknown): StorageErrorCategory => {
+    // Try custom mapping first
+    if (customErrorMapping) {
+      const customResult = customErrorMapping(error);
+      if (customResult !== null) return customResult;
+    }
+
+    // Fall back to generic classification
+    return classifyStorageError(error);
+  };
+};
+
+// Generic error tracking function
+export const trackStorageError = (
+  storageType: string,
+  metrics: StorageMetrics,
+  operation: string,
+  error: unknown,
+  context: Record<string, unknown> = {},
+  errorClassifier = classifyStorageError,
+) =>
+  Effect.gen(function* () {
+    const errorCategory = errorClassifier(error);
+
+    // Record error metrics
+    const errorMetric = metrics.uploadErrorsTotal.pipe(
+      Metric.tagged("operation", operation),
+      Metric.tagged("error_category", errorCategory),
+    );
+    yield* errorMetric(Effect.succeed(1));
+
+    // Create detailed error context
+    const errorDetails = {
+      storage_type: storageType,
+      operation,
+      error_category: errorCategory,
+      error_type: typeof error,
+      error_message: error instanceof Error ? error.message : String(error),
+      error_code:
+        error && typeof error === "object" && "code" in error
+          ? error.code
+          : undefined,
+      error_name:
+        error && typeof error === "object" && "name" in error
+          ? error.name
+          : undefined,
+      ...context,
+    };
+
+    // Log structured error
+    yield* Effect.logError(
+      `${storageType.toUpperCase()} ${operation} failed`,
+    ).pipe(Effect.annotateLogs(errorDetails));
+  });
+
+// Factory for storage-specific error tracking
+export const createStorageErrorTracker = (
+  storageType: string,
+  metrics: StorageMetrics,
+  customErrorClassifier?: (error: unknown) => StorageErrorCategory | null,
+) => {
+  const errorClassifier = createStorageErrorClassifier(
+    storageType,
+    customErrorClassifier,
+  );
+
+  return (
+    operation: string,
+    error: unknown,
+    context: Record<string, unknown> = {},
+  ) =>
+    trackStorageError(
+      storageType,
+      metrics,
+      operation,
+      error,
+      context,
+      errorClassifier,
+    );
+};

package/src/core/index.ts

@@ -0,0 +1,9 @@
+// Core observability exports
+
+export * from "./errors.js";
+export * from "./layers.js";
+export * from "./logging.js";
+export * from "./metrics.js";
+export * from "./testing.js";
+export * from "./tracing.js";
+export * from "./utilities.js";

package/src/core/layers.ts

@@ -0,0 +1,205 @@
+import { Context, Effect, Layer, Option } from "effect";
+import type { StorageMetrics } from "./metrics.js";
+
+// ============================================================================
+// Observability Layer Interfaces
+// ============================================================================
+
+/**
+ * Core observability service providing tracing, metrics, and logging capabilities
+ */
+export interface ObservabilityService {
+  readonly serviceName: string;
+  readonly enabled: boolean;
+}
+
+/**
+ * Observability service tag for Effect Context
+ */
+export class Observability extends Context.Tag("Observability")<
+  Observability,
+  ObservabilityService
+>() {}
+
+/**
+ * Storage observability service extending base observability with storage-specific metrics
+ */
+export interface StorageObservabilityService extends ObservabilityService {
+  readonly storageType: string;
+  readonly metrics: StorageMetrics;
+}
+
+/**
+ * Storage observability service tag
+ */
+export class StorageObservability extends Context.Tag("StorageObservability")<
+  StorageObservability,
+  StorageObservabilityService
+>() {}
+
+/**
+ * Upload observability service for upload-specific operations
+ */
+export interface UploadObservabilityService extends ObservabilityService {
+  readonly metrics: {
+    uploadCreated: Effect.Effect<void>;
+    uploadCompleted: Effect.Effect<void>;
+    uploadFailed: Effect.Effect<void>;
+    chunkUploaded: Effect.Effect<void>;
+  };
+}
+
+/**
+ * Upload observability service tag
+ */
+export class UploadObservability extends Context.Tag("UploadObservability")<
+  UploadObservability,
+  UploadObservabilityService
+>() {}
+
+/**
+ * Flow observability service for flow execution operations
+ */
+export interface FlowObservabilityService extends ObservabilityService {
+  readonly metrics: {
+    flowStarted: Effect.Effect<void>;
+    flowCompleted: Effect.Effect<void>;
+    flowFailed: Effect.Effect<void>;
+    nodeExecuted: Effect.Effect<void>;
+  };
+}
+
+/**
+ * Flow observability service tag
+ */
+export class FlowObservability extends Context.Tag("FlowObservability")<
+  FlowObservability,
+  FlowObservabilityService
+>() {}
+
+// ============================================================================
+// Layer Factories
+// ============================================================================
+
+/**
+ * Create a base observability layer
+ */
+export const makeObservabilityLayer = (
+  serviceName: string,
+  enabled = true,
+): Layer.Layer<Observability> =>
+  Layer.succeed(Observability, {
+    serviceName,
+    enabled,
+  });
+
+/**
+ * Create a storage observability layer
+ */
+export const makeStorageObservabilityLayer = (
+  storageType: string,
+  metrics: StorageMetrics,
+  enabled = true,
+): Layer.Layer<StorageObservability> =>
+  Layer.succeed(StorageObservability, {
+    serviceName: `uploadista-${storageType}-store`,
+    storageType,
+    metrics,
+    enabled,
+  });
+
+/**
+ * Create an upload observability layer
+ */
+export const makeUploadObservabilityLayer = (
+  enabled = true,
+): Layer.Layer<UploadObservability> =>
+  Layer.succeed(UploadObservability, {
+    serviceName: "uploadista-upload-server",
+    enabled,
+    metrics: {
+      uploadCreated: Effect.void,
+      uploadCompleted: Effect.void,
+      uploadFailed: Effect.void,
+      chunkUploaded: Effect.void,
+    },
+  });
+
+/**
+ * Create a flow observability layer
+ */
+export const makeFlowObservabilityLayer = (
+  enabled = true,
+): Layer.Layer<FlowObservability> =>
+  Layer.succeed(FlowObservability, {
+    serviceName: "uploadista-flow-engine",
+    enabled,
+    metrics: {
+      flowStarted: Effect.void,
+      flowCompleted: Effect.void,
+      flowFailed: Effect.void,
+      nodeExecuted: Effect.void,
+    },
+  });
+
+// ============================================================================
+// No-op Layers (for testing and opt-out)
+// ============================================================================
+
+/**
+ * No-op observability layer (disabled)
+ */
+export const ObservabilityDisabled = makeObservabilityLayer(
+  "uploadista-disabled",
+  false,
+);
+
+/**
+ * No-op storage observability layer
+ */
+export const StorageObservabilityDisabled = (storageType: string) =>
+  makeStorageObservabilityLayer(
+    storageType,
+    {} as StorageMetrics, // No-op metrics
+    false,
+  );
+
+/**
+ * No-op upload observability layer
+ */
+export const UploadObservabilityDisabled = makeUploadObservabilityLayer(false);
+
+/**
+ * No-op flow observability layer
+ */
+export const FlowObservabilityDisabled = makeFlowObservabilityLayer(false);
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if observability is enabled in the current context
+ */
+export const isObservabilityEnabled = Effect.gen(function* () {
+  const observability = yield* Effect.serviceOption(Observability);
+  return Option.match(observability, {
+    onNone: () => false,
+    onSome: (obs) => obs.enabled,
+  });
+});
+
+/**
+ * Execute an effect only if observability is enabled
+ */
+export const whenObservabilityEnabled = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<Option.Option<A>, E, R | Observability> =>
+  Effect.gen(function* () {
+    const enabled = yield* isObservabilityEnabled;
+    if (enabled) {
+      const result = yield* effect;
+      return Option.some(result);
+    }
+    return Option.none();
+  });