@daytonaio/sdk 0.139.0 → 0.141.0

package/src/utils/otel.decorator.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Configuration options for span instrumentation
+ */
+export interface SpanConfig {
+    /**
+     * Custom name for the span. If not provided, uses `ClassName.methodName` format
+     */
+    name?: string;
+    /**
+     * Additional attributes to attach to the span
+     */
+    attributes?: Record<string, string>;
+}
+/**
+ * Configuration options for metric instrumentation
+ */
+export interface MetricConfig {
+    /**
+     * Custom name for the metric. If not provided, uses `ClassName.methodName` format
+     */
+    name?: string;
+    /**
+     * Description for the metrics being collected
+     */
+    description?: string;
+    /**
+     * Additional labels to attach to the metrics
+     */
+    labels?: Record<string, string>;
+}
+/**
+ * Configuration options for the combined instrumentation decorator
+ */
+export interface InstrumentationConfig {
+    /**
+     * Custom name for the span and metric. If not provided, uses `ClassName.methodName` format
+     */
+    name?: string;
+    /**
+     * Description for the metrics being collected
+     */
+    description?: string;
+    /**
+     * Additional labels/attributes to attach to spans and metrics
+     */
+    labels?: Record<string, string>;
+    /**
+     * Enable trace collection (default: true)
+     */
+    enableTraces?: boolean;
+    /**
+     * Enable metrics collection (default: true)
+     */
+    enableMetrics?: boolean;
+}
+/**
+ * Decorator for instrumenting methods with OpenTelemetry spans (traces only)
+ *
+ * @param config - Configuration object or string name for the span
+ *
+ */
+export declare function WithSpan(config?: string | SpanConfig): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator for instrumenting methods with OpenTelemetry metrics (metrics only)
+ *
+ * Collects two metrics:
+ * - Counter: `{name}_executions` - tracks number of executions with status (success/error)
+ * - Histogram: `{name}_duration` - tracks execution duration in milliseconds
+ *
+ * @param config - Configuration object or string name for the metric
+ *
+ */
+export declare function WithMetric(config?: string | MetricConfig): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator for instrumenting methods with both OpenTelemetry traces and metrics
+ *
+ * This decorator composes @WithSpan and @WithMetric to provide both trace and metric collection.
+ * You can selectively enable/disable traces or metrics using the config options.
+ *
+ * @param config - Configuration object or string name for the instrumentation
+ */
+export declare function WithInstrumentation(config?: string | InstrumentationConfig): MethodDecorator;

package/src/utils/otel.decorator.js

@@ -0,0 +1,141 @@
+"use strict";
+/*
+ * Copyright 2025 Daytona Platforms Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WithSpan = WithSpan;
+exports.WithMetric = WithMetric;
+exports.WithInstrumentation = WithInstrumentation;
+const api_1 = require("@opentelemetry/api");
+// Lazy initialization to ensure SDK is started before getting tracer/meter
+const getTracer = () => api_1.trace.getTracer('');
+const getMeter = () => api_1.metrics.getMeter('');
+const executionHistograms = new Map();
+/**
+ * Converts a string to snake_case for Prometheus-friendly metric names
+ */
+function toSnakeCase(str) {
+    return str
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '')
+        .replace(/\./g, '_');
+}
+/**
+ * Decorator for instrumenting methods with OpenTelemetry spans (traces only)
+ *
+ * @param config - Configuration object or string name for the span
+ *
+ */
+function WithSpan(config) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        const methodName = String(propertyKey);
+        descriptor.value = async function (...args) {
+            const cfg = typeof config === 'string' ? { name: config } : config || {};
+            const { name, attributes = {} } = cfg;
+            const spanName = name || `${target.constructor.name}.${methodName}`;
+            const allAttributes = {
+                component: target.constructor.name,
+                method: methodName,
+                ...attributes,
+            };
+            const span = getTracer().startSpan(spanName, {
+                attributes: allAttributes,
+            }, api_1.context.active());
+            return api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), async () => {
+                try {
+                    const result = await originalMethod.apply(this, args);
+                    span.setStatus({ code: api_1.SpanStatusCode.OK });
+                    return result;
+                }
+                catch (error) {
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    span.recordException(error instanceof Error ? error : new Error(String(error)));
+                    throw error;
+                }
+                finally {
+                    span.end();
+                }
+            });
+        };
+    };
+}
+/**
+ * Decorator for instrumenting methods with OpenTelemetry metrics (metrics only)
+ *
+ * Collects two metrics:
+ * - Counter: `{name}_executions` - tracks number of executions with status (success/error)
+ * - Histogram: `{name}_duration` - tracks execution duration in milliseconds
+ *
+ * @param config - Configuration object or string name for the metric
+ *
+ */
+function WithMetric(config) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        const methodName = String(propertyKey);
+        descriptor.value = async function (...args) {
+            const cfg = typeof config === 'string' ? { name: config } : config || {};
+            const { name, description, labels = {} } = cfg;
+            const metricName = toSnakeCase(name || `${target.constructor.name}.${methodName}`);
+            const allLabels = {
+                component: target.constructor.name,
+                method: methodName,
+                ...labels,
+            };
+            // Get or create histogram for this method
+            if (!executionHistograms.has(metricName)) {
+                executionHistograms.set(metricName, getMeter().createHistogram(`${metricName}_duration`, {
+                    description: description || `Duration of executions for ${metricName}`,
+                    unit: 'ms',
+                }));
+            }
+            const histogram = executionHistograms.get(metricName);
+            if (!histogram) {
+                throw new Error(`Histogram not found for metric: ${metricName}`);
+            }
+            const startTime = Date.now();
+            let status = 'success';
+            try {
+                const result = await originalMethod.apply(this, args);
+                return result;
+            }
+            catch (error) {
+                status = 'error';
+                throw error;
+            }
+            finally {
+                const duration = Date.now() - startTime;
+                histogram.record(duration, { ...allLabels, status });
+            }
+        };
+    };
+}
+/**
+ * Decorator for instrumenting methods with both OpenTelemetry traces and metrics
+ *
+ * This decorator composes @WithSpan and @WithMetric to provide both trace and metric collection.
+ * You can selectively enable/disable traces or metrics using the config options.
+ *
+ * @param config - Configuration object or string name for the instrumentation
+ */
+function WithInstrumentation(config) {
+    const cfg = typeof config === 'string' ? { name: config } : config || {};
+    const { enableTraces = true, enableMetrics = true, name, description, labels } = cfg;
+    const decorators = [];
+    if (enableTraces) {
+        decorators.push(WithSpan({ name, attributes: labels }));
+    }
+    if (enableMetrics) {
+        decorators.push(WithMetric({ name, description, labels }));
+    }
+    return (target, propertyKey, descriptor) => {
+        decorators.forEach((decorator) => decorator(target, propertyKey, descriptor));
+    };
+}
+//# sourceMappingURL=otel.decorator.js.map

package/src/utils/otel.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.decorator.js","sourceRoot":"","sources":["../../../../../libs/sdk-typescript/src/utils/otel.decorator.ts"],"names":[],"mappings":"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"}