feat: provide abstract telemetry classes (#1078)

.changes/0523c42d-d3a6-4789-800b-b613e6589170.json

@@ -0,0 +1,5 @@
+{
+    "id": "0523c42d-d3a6-4789-800b-b613e6589170",
+    "type": "feature",
+    "description": "Provide new abstract versions of telemetry classes to simplify the creation of custom telemetry providers"
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/AbstractTelemetryProvider.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package aws.smithy.kotlin.runtime.telemetry
+
+import aws.smithy.kotlin.runtime.ExperimentalApi
+import aws.smithy.kotlin.runtime.telemetry.context.ContextManager
+import aws.smithy.kotlin.runtime.telemetry.logging.LoggerProvider
+import aws.smithy.kotlin.runtime.telemetry.metrics.MeterProvider
+import aws.smithy.kotlin.runtime.telemetry.trace.TracerProvider
+
+/**
+ * An abstract implementation of a telemetry provider. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractTelemetryProvider : TelemetryProvider {
+    @ExperimentalApi
+    override val meterProvider: MeterProvider = MeterProvider.None
+
+    @ExperimentalApi
+    override val tracerProvider: TracerProvider = TracerProvider.None
+
+    @ExperimentalApi
+    override val loggerProvider: LoggerProvider = LoggerProvider.None
+
+    @ExperimentalApi
+    override val contextManager: ContextManager = ContextManager.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/TelemetryProvider.kt

@@ -20,7 +20,7 @@ public interface TelemetryProvider {
         /**
          * Default (no-op) telemetry provider
          */
-        public val None: TelemetryProvider = NoOpTelemetryProvider
+        public val None: TelemetryProvider = object : AbstractTelemetryProvider() { }
     }
 
     /**
@@ -47,11 +47,3 @@ public interface TelemetryProvider {
     @ExperimentalApi
     public val contextManager: ContextManager
 }
-
-@OptIn(ExperimentalApi::class)
-private object NoOpTelemetryProvider : TelemetryProvider {
-    override val meterProvider: MeterProvider = MeterProvider.None
-    override val tracerProvider: TracerProvider = TracerProvider.None
-    override val loggerProvider: LoggerProvider = LoggerProvider.None
-    override val contextManager: ContextManager = ContextManager.None
-}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/AbstractContext.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.context
+
+/**
+ * An abstract implementation of telemetry provider context. By default, this class uses no-op implementations for all
+ * members unless overridden in a subclass.
+ */
+public abstract class AbstractContext : Context {
+    override fun makeCurrent(): Scope = Scope.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/AbstractContextManager.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.context
+
+/**
+ * An abstract implementation of a context manager. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractContextManager : ContextManager {
+    override fun current(): Context = Context.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/AbstractScope.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.context
+
+/**
+ * An abstract implementation of a scope. By default, this class uses no-op implementations for all members unless
+ * overridden in a subclass.
+ */
+public abstract class AbstractScope : Scope {
+    override fun close() { }
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/Context.kt

@@ -14,7 +14,7 @@ public interface Context {
         /**
          * A no-op [Context]
          */
-        public val None: Context = NoOpContext
+        public val None: Context = object : AbstractContext() { }
     }
 
     /**
@@ -25,11 +25,3 @@ public interface Context {
      */
     public fun makeCurrent(): Scope
 }
-
-private object NoOpContext : Context {
-    override fun makeCurrent(): Scope = NoOpScope
-}
-
-private object NoOpScope : Scope {
-    override fun close() {}
-}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/ContextManager.kt

@@ -11,15 +11,14 @@ package aws.smithy.kotlin.runtime.telemetry.context
  */
 public interface ContextManager {
     public companion object {
-        public val None: ContextManager = NoOpContextManager
+        /**
+         * A [ContextManager] that does nothing
+         */
+        public val None: ContextManager = object : AbstractContextManager() { }
     }
 
     /**
      * Return the current [Context]
      */
     public fun current(): Context
 }
-
-private object NoOpContextManager : ContextManager {
-    override fun current(): Context = Context.None
-}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/context/Scope.kt

@@ -10,4 +10,11 @@ import aws.smithy.kotlin.runtime.io.Closeable
 /**
  * Delineates a logical scope that has a beginning and end (e.g. a function)
  */
-public interface Scope : Closeable
+public interface Scope : Closeable {
+    public companion object {
+        /**
+         * A [Scope] that does nothing
+         */
+        public val None: Scope = object : AbstractScope() { }
+    }
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/AbstractLogRecordBuilder.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.logging
+
+/**
+ * An abstract implementation of a log record builder. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractLogRecordBuilder : LogRecordBuilder {
+    override fun setCause(ex: Throwable) { }
+    override fun setMessage(message: String) { }
+    override fun setMessage(message: MessageSupplier) { }
+    override fun setKeyValuePair(key: String, value: Any) { }
+    override fun emit() { }
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/AbstractLogger.kt

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.logging
+
+/**
+ * An abstract implementation of a logger. This class delegates the [trace], [debug], [info], [warn], and [error]
+ * methods to a centralized [log] method which accepts [LogLevel] as a parameter. By default, this class uses no-op
+ * implementations for all other members unless overridden in a subclass.
+ */
+public abstract class AbstractLogger : Logger {
+    override fun trace(t: Throwable?, msg: MessageSupplier) {
+        if (isEnabledFor(LogLevel.Trace)) log(LogLevel.Trace, t, msg)
+    }
+
+    override fun debug(t: Throwable?, msg: MessageSupplier) {
+        if (isEnabledFor(LogLevel.Debug)) log(LogLevel.Debug, t, msg)
+    }
+
+    override fun info(t: Throwable?, msg: MessageSupplier) {
+        if (isEnabledFor(LogLevel.Info)) log(LogLevel.Info, t, msg)
+    }
+
+    override fun warn(t: Throwable?, msg: MessageSupplier) {
+        if (isEnabledFor(LogLevel.Warning)) log(LogLevel.Warning, t, msg)
+    }
+
+    override fun error(t: Throwable?, msg: MessageSupplier) {
+        if (isEnabledFor(LogLevel.Error)) log(LogLevel.Error, t, msg)
+    }
+
+    public open fun log(level: LogLevel, t: Throwable?, msg: MessageSupplier) { }
+
+    override fun isEnabledFor(level: LogLevel): Boolean = false
+
+    override fun atLevel(level: LogLevel): LogRecordBuilder = LogRecordBuilder.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/AbstractLoggerProvider.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.logging
+
+/**
+ * An abstract implementation of a logger provider. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractLoggerProvider : LoggerProvider {
+    override fun getOrCreateLogger(name: String): Logger = Logger.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/LogRecordBuilder.kt

@@ -9,6 +9,13 @@ package aws.smithy.kotlin.runtime.telemetry.logging
  * Construct a logging record that can be emitted to an underlying logger.
  */
 public interface LogRecordBuilder {
+    public companion object {
+        /**
+         * A [LogRecordBuilder] that does nothing
+         */
+        public val None: LogRecordBuilder = object : AbstractLogRecordBuilder() { }
+    }
+
     /**
      * Set an exception associated with this event
      * Some loggers will do additional formatting for exceptions.

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/Logger.kt

@@ -15,7 +15,7 @@ public interface Logger {
         /**
          * A no-op [Logger] that does nothing
          */
-        public val None: Logger = NoOpLogger
+        public val None: Logger = object : AbstractLogger() { }
     }
 
     /**

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/logging/LoggerProvider.kt

@@ -13,7 +13,7 @@ public interface LoggerProvider {
         /**
          * A no-op [LoggerProvider] that does nothing
          */
-        public val None: LoggerProvider = NoOpLoggerProvider
+        public val None: LoggerProvider = object : AbstractLoggerProvider() { }
     }
 
     /**

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/metrics/AbstractGauge.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.metrics
+
+/**
+ * An abstract implementation of an asynchronous measurement handle. By default, this class uses no-op implementations
+ * for all members unless overridden in a subclass.
+ */
+public abstract class AbstractAsyncMeasurementHandle : AsyncMeasurementHandle {
+    override fun stop() { }
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/metrics/AbstractHistogram.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.metrics
+
+import aws.smithy.kotlin.runtime.collections.Attributes
+import aws.smithy.kotlin.runtime.telemetry.context.Context
+
+/**
+ * An abstract implementation of a histogram. By default, this class uses no-op implementations for all members unless
+ * overridden in a subclass.
+ */
+public abstract class AbstractHistogram<T : Number> : Histogram<T> {
+    override fun record(value: T, attributes: Attributes, context: Context?) { }
+}
+
+public typealias AbstractLongHistogram = AbstractHistogram<Long>
+public typealias AbstractDoubleHistogram = AbstractHistogram<Double>

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/metrics/AbstractMeter.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.metrics
+
+/**
+ * An abstract implementation of a meter. By default, this class uses no-op implementations for all members unless
+ * overridden in a subclass.
+ */
+public abstract class AbstractMeter : Meter {
+    override fun createUpDownCounter(name: String, units: String?, description: String?): UpDownCounter =
+        UpDownCounter.None
+
+    override fun createAsyncUpDownCounter(
+        name: String,
+        callback: LongUpDownCounterCallback,
+        units: String?,
+        description: String?,
+    ): AsyncMeasurementHandle = AsyncMeasurementHandle.None
+
+    override fun createMonotonicCounter(name: String, units: String?, description: String?): MonotonicCounter =
+        MonotonicCounter.None
+
+    override fun createLongHistogram(name: String, units: String?, description: String?): LongHistogram =
+        Histogram.LongNone
+
+    override fun createDoubleHistogram(name: String, units: String?, description: String?): DoubleHistogram =
+        Histogram.DoubleNone
+
+    override fun createLongGauge(
+        name: String,
+        callback: LongGaugeCallback,
+        units: String?,
+        description: String?,
+    ): AsyncMeasurementHandle = AsyncMeasurementHandle.None
+
+    override fun createDoubleGauge(
+        name: String,
+        callback: DoubleGaugeCallback,
+        units: String?,
+        description: String?,
+    ): AsyncMeasurementHandle = AsyncMeasurementHandle.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/metrics/AbstractMeterProvider.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.metrics
+
+/**
+ * An abstract implementation of a meter provider. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractMeterProvider : MeterProvider {
+    override fun getOrCreateMeter(scope: String): Meter = Meter.None
+}

runtime/observability/telemetry-api/common/src/aws/smithy/kotlin/runtime/telemetry/metrics/AbstractMonotonicCounter.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.telemetry.metrics
+
+import aws.smithy.kotlin.runtime.collections.Attributes
+import aws.smithy.kotlin.runtime.telemetry.context.Context
+
+/**
+ * An abstract implementation of a monotonic counter. By default, this class uses no-op implementations for all members
+ * unless overridden in a subclass.
+ */
+public abstract class AbstractMonotonicCounter : MonotonicCounter {
+    override fun add(value: Long, attributes: Attributes, context: Context?) { }
+}