Code documentation

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/OpenTelemetry.scala

@@ -7,17 +7,46 @@ import zio.telemetry.opentelemetry.logging.Logging
 import zio.telemetry.opentelemetry.metrics.Meter
 import zio.telemetry.opentelemetry.tracing.Tracing
 
+/**
+ * The entrypoint to telemetry functionality for tracing, metrics, logging and baggage.
+ */
 object OpenTelemetry {
 
-  def global: TaskLayer[api.OpenTelemetry] =
+  /**
+   * A global singleton for the entrypoint to telemetry functionality for tracing, metrics, logging and baggage. Should
+   * be used with <a href="https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/">SDK
+   * Autoconfiguration</a> module and/or <a href="">Automatic instrumentation</a> Java agent.
+   *
+   * @see
+   *   <a href="https://zio.dev/zio-telemetry/opentelemetry/#usage-with-opentelemetry-automatic-instrumentation">Usage
+   *   with OpenTelemetry automatic instrumentation</a>
+   */
+  val global: TaskLayer[api.OpenTelemetry] =
     ZLayer(ZIO.attempt(api.GlobalOpenTelemetry.get()))
 
+  /**
+   * Use when you need to configure an instance of OpenTelemetry programmatically.
+   *
+   * Example:
+   * [[https://github.com/zio/zio-telemetry/blob/series/2.x/opentelemetry-example/src/main/scala/zio/telemetry/opentelemetry/example/otel/OtelSdk.scala]]
+   *
+   * @param zio
+   *   scoped ZIO value that returns a configured instance of [[io.opentelemetry.api.OpenTelemetry]], thus ensuring that
+   *   the returned instance will be closed.
+   */
   def custom(zio: => ZIO[Scope, Throwable, api.OpenTelemetry]): TaskLayer[api.OpenTelemetry] =
     ZLayer.scoped(zio)
 
-  def noop: TaskLayer[api.OpenTelemetry] =
+  val noop: TaskLayer[api.OpenTelemetry] =
     ZLayer.succeed(api.OpenTelemetry.noop())
 
+  /**
+   * Use when you need to instrument spans manually.
+   *
+   * @param instrumentationScopeName
+   * @param instrumentationVersion
+   * @param schemaUrl
+   */
   def tracing(
     instrumentationScopeName: String,
     instrumentationVersion: Option[String] = None,
@@ -37,6 +66,13 @@ object OpenTelemetry {
     tracerLayer >>> Tracing.live
   }
 
+  /**
+   * Use when you need to instrument metrics manually.
+   *
+   * @param instrumentationScopeName
+   * @param instrumentationVersion
+   * @param schemaUrl
+   */
   def meter(
     instrumentationScopeName: String,
     instrumentationVersion: Option[String] = None,
@@ -56,6 +92,13 @@ object OpenTelemetry {
     meterLayer >>> Meter.live
   }
 
+  /**
+   * Use when you need to propagate calls to `ZIO.log*` as OTEL Log signals.
+   *
+   * @param instrumentationScopeName
+   * @param logLevel
+   *   configures the logger to propagate the log records only when the log level is more than specified
+   */
   def logging(
     instrumentationScopeName: String,
     logLevel: LogLevel = LogLevel.Info

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/common/Attribute.scala

@@ -1,8 +1,18 @@
 package zio.telemetry.opentelemetry.common
 
 import io.opentelemetry.api.common.AttributeKey
+
 import scala.jdk.CollectionConverters._
 
+/**
+ * Scala wrapper for Java attribute key/value API. It simplifies the creation of key/value pairs without having to box
+ * Scala primitives to Java ones.
+ *
+ * @param key
+ * @param value
+ * @tparam T
+ *   Java-specific type `java.lang.*`
+ */
 final case class Attribute[T](key: AttributeKey[T], value: T)
 
 object Attribute {

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/common/Attributes.scala

@@ -4,7 +4,7 @@ import io.opentelemetry.api
 
 object Attributes {
 
-  def empty: api.common.Attributes = 
+  def empty: api.common.Attributes =
     api.common.Attributes.empty()
 
   def apply[T](attributes: Attribute[T]*): api.common.Attributes = {

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/metrics/Counter.scala

@@ -5,10 +5,36 @@ import io.opentelemetry.api.metrics.LongCounter
 import zio._
 import zio.telemetry.opentelemetry.context.ContextStorage
 
+/**
+ * A Counter instrument that records values of type `A`
+ *
+ * @tparam A
+ *   according to the specification, it can be either [[scala.Long]] or [[scala.Double]] type
+ */
 trait Counter[-A] {
 
+  /**
+   * Records a value.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param value
+   *   The increment amount. MUST be non-negative
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def add(value: A, attributes: Attributes = Attributes.empty): UIO[Unit]
 
+  /**
+   * Increments a counter by one.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def inc(attributes: Attributes = Attributes.empty): UIO[Unit]
 }
 

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/metrics/Histogram.scala

@@ -1,12 +1,29 @@
 package zio.telemetry.opentelemetry.metrics
 
-import zio._
-import zio.telemetry.opentelemetry.context.ContextStorage
 import io.opentelemetry.api.common.Attributes
 import io.opentelemetry.api.metrics.DoubleHistogram
+import zio._
+import zio.telemetry.opentelemetry.context.ContextStorage
 
+/**
+ * A Histogram instrument that records values of type `A`
+ *
+ * @tparam A
+ *   according to the specification, it can be either [[scala.Long]] or [[scala.Double]] type
+ */
 trait Histogram[-A] {
 
+  /**
+   * Records a value.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param value
+   *   The increment amount. MUST be non-negative
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def record(value: A, attributes: Attributes = Attributes.empty): UIO[Unit]
 
 }

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/metrics/Meter.scala

@@ -4,38 +4,124 @@ import io.opentelemetry.api
 import zio._
 import zio.telemetry.opentelemetry.context.ContextStorage
 
+/**
+ * Provides instruments used to record measurements which are aggregated to metrics.
+ *
+ * @see
+ *   <a
+ *   href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/supplementary-guidelines.md#instrument-selection">Instrument
+ *   Selection Guidelines </a>
+ */
 trait Meter {
 
+  /**
+   * Constructs a Counter instrument.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   The description is an optional free-form text provided by the author of the instrument. The API MUST treat it as
+   *   an opaque string
+   */
   def counter(
     name: String,
     unit: Option[String] = None,
     description: Option[String] = None
   ): UIO[Counter[Long]]
 
+  /**
+   * Constructs a UpDownCounter instrument.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   description is an optional free-form text provided by the author of the instrument. The API MUST treat it as an
+   *   opaque string
+   */
   def upDownCounter(
     name: String,
     unit: Option[String] = None,
     description: Option[String] = None
   ): UIO[UpDownCounter[Long]]
 
+  /**
+   * Constructs a Historgram instrument.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   description is an optional free-form text provided by the author of the instrument. The API MUST treat it as an
+   *   opaque string
+   */
   def histogram(
     name: String,
     unit: Option[String] = None,
     description: Option[String] = None
   ): UIO[Histogram[Double]]
 
+  /**
+   * Builds an Asynchronous Counter instrument with the given callback.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   description is an optional free-form text provided by the author of the instrument. The API MUST treat it as an
+   *   opaque string
+   * @param callback
+   *   callback which observes measurements when invoked
+   */
   def observableCounter(
     name: String,
     unit: Option[String] = None,
     description: Option[String] = None
   )(callback: ObservableMeasurement[Long] => Task[Unit]): RIO[Scope, Unit]
 
+  /**
+   * Builds an Asynchronous UpDownCounter instrument with the given callback.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   description is an optional free-form text provided by the author of the instrument. The API MUST treat it as an
+   *   opaque string
+   * @param callback
+   *   callback which observes measurements when invoked
+   */
   def observableUpDownCounter(
     name: String,
     unit: Option[String] = None,
     description: Option[String] = None
   )(callback: ObservableMeasurement[Long] => Task[Unit]): RIO[Scope, Unit]
 
+  /**
+   * Builds an Asynchronous Gauge instrument with the given callback.
+   *
+   * @param name
+   *   the name of the Counter. Instrument names must consist of 255 or fewer characters including alphanumeric, _, .,
+   *   -, and start with a letter
+   * @param unit
+   *   instrument units must be 63 or fewer ASCII characters
+   * @param description
+   *   description is an optional free-form text provided by the author of the instrument. The API MUST treat it as an
+   *   opaque string
+   * @param callback
+   *   callback which observes measurements when invoked
+   */
   def observableGauge(
     name: String,
     unit: Option[String] = None,

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/metrics/ObservableMeasurement.scala

@@ -4,8 +4,22 @@ import io.opentelemetry.api
 import io.opentelemetry.api.common.Attributes
 import zio._
 
+/**
+ * An instrument for observing measurements with values of type `A`
+ *
+ * @tparam A
+ *   according to the specification, it can be either [[scala.Long]] or [[scala.Double]] type
+ */
 trait ObservableMeasurement[-A] {
 
+  /**
+   * Records a measurement.
+   *
+   * @param value
+   *   The measurement value
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def record(value: A, attributes: Attributes = Attributes.empty): Task[Unit]
 
 }

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/metrics/UpDownCounter.scala

@@ -1,16 +1,51 @@
 package zio.telemetry.opentelemetry.metrics
 
-import zio._
 import io.opentelemetry.api.common.Attributes
-import zio.telemetry.opentelemetry.context.ContextStorage
 import io.opentelemetry.api.metrics.LongUpDownCounter
+import zio._
+import zio.telemetry.opentelemetry.context.ContextStorage
 
+/**
+ * A UpDownCounter instrument that records values of type `A`
+ *
+ * @tparam A
+ *   according to the specification, it can be either [[scala.Long]] or [[scala.Double]] type
+ */
 trait UpDownCounter[-A] {
 
+  /**
+   * Records a value.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param value
+   *   The increment amount. May be positive, negative or zero.
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def add(value: A, attributes: Attributes = Attributes.empty): UIO[Unit]
 
+  /**
+   * Increments a counter by one.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def inc(attributes: Attributes = Attributes.empty): UIO[Unit]
 
+  /**
+   * Decrements a counter by one.
+   *
+   * It uses the context taken from the [[zio.telemetry.opentelemetry.context.ContextStorage]] to associate with this
+   * measurement.
+   *
+   * @param attributes
+   *   A set of attributes to associate with the value
+   */
   def dec(attributes: Attributes = Attributes.empty): UIO[Unit]
 
 }

opentelemetry/src/main/scala/zio/telemetry/opentelemetry/tracing/StatusMapper.scala

@@ -30,7 +30,7 @@ import zio.telemetry.opentelemetry.tracing.StatusMapper.Result
  * @param failure
  *   partial function to map the ZIO failure to [[io.opentelemetry.api.trace.StatusCode]] and [[java.lang.Throwable]].
  *   The latter is used to record the exception, see:
- *   [[https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/exceptions.md#recording-an-exception Recording an exception]]
+ *   [[https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/exceptions.md#recording-an-exception]]
  * @param success
  *   partial function to map the ZIO success to [[io.opentelemetry.api.trace.StatusCode]] and status description
  * @tparam E