From f75a72ac8ee882f2eae9afe0f87bb5db3ec5068b Mon Sep 17 00:00:00 2001
From: Lucas Satabin <lucas.satabin@commercetools.com>
Date: Thu, 4 Jul 2024 12:28:26 +0200
Subject: [PATCH] Add documentation for queue statistics

---
 docs/getting-started/directory.conf |  1 +
 docs/getting-started/queues.md      |  2 +
 docs/getting-started/stats.md       | 61 +++++++++++++++++++++++++++++
 docs/systems/index.md               |  2 +
 4 files changed, 66 insertions(+)
 create mode 100644 docs/getting-started/stats.md

diff --git a/docs/getting-started/directory.conf b/docs/getting-started/directory.conf
index d3c9e98..3f0d235 100644
--- a/docs/getting-started/directory.conf
+++ b/docs/getting-started/directory.conf
@@ -4,6 +4,7 @@ laika.navigationOrder = [
   queues.md
   publishing.md
   subscribing.md
+  stats.md
   administration.md
   serialization.md
 ]
diff --git a/docs/getting-started/queues.md b/docs/getting-started/queues.md
index 570b3aa..6766c2b 100644
--- a/docs/getting-started/queues.md
+++ b/docs/getting-started/queues.md
@@ -13,6 +13,8 @@ There are several views possible on a queue:
 
  - as a `QueuePublisher` when you only need to [publish messages](publishing.md) to an existing queue.
  - as a `QueueSubscriber` when you only need to [subscribe](subscribing.md) to an existing queue.
+ - as a `QueueStatistics` when you only need to [gather queue statistics](stats.md) from an existing queue.
+ - as a `QueueSubscriber` when you only need to [subscribe](subscribing.md) to an existing queue.
  - as a `QueueAdministration` when you need to [manage](administration.md) queues (creation, deletion, ...).
 
 The entry point is the `QueueClient` factory for each underlying queue system.
diff --git a/docs/getting-started/stats.md b/docs/getting-started/stats.md
new file mode 100644
index 0000000..d1f27a6
--- /dev/null
+++ b/docs/getting-started/stats.md
@@ -0,0 +1,61 @@
+{% nav = true %}
+# Queue Statistics
+
+The library exposes a simple interface to access basic queue statistics through a @:api(com.commercetools.queue.QueueStatistics).
+
+@:callout(warning)
+The numbers reported by the statistics are approximate numbers. Depending on the underlying system, there might be some delay in data availability.
+
+When in doubt, refer to the queue provider documentation.
+@:@
+
+```scala mdoc
+import cats.effect.IO
+
+import com.commercetools.queue.{QueueClient, QueueStatistics}
+
+def client: QueueClient[IO] = ???
+
+// returns a statistics accessor for the queue named `my-queue`
+def stats: QueueStatistics[IO] =
+  client.statistics("my-queue")
+```
+
+## Building a stream of statistics
+
+This interface expoes a way to build a stream of statistics, polling them at some configured interval. For instance, this code will print the statistics polled every 20 seconds.
+
+```scala mdoc:compile-only
+import scala.concurrent.duration._
+
+stats
+  .stream(interval = 20.seconds)
+  .evalMap { 
+    case Right(stats) => IO.println(stats)
+    case Left(t) => IO.println(s"Statistics failed to be retrieved: ${t.getMessage()}")
+  }
+  .drain
+```
+
+If you want the stream to fail upon the first fetching error, you can use the `strictStream` variant.
+
+## Explicit fetch
+
+If you are integrating this library with an existing code base that performs explicit fetches for queue statistics, you can access the @:api(com.commercetools.queue.QueueStatsFetcher) lower level API, which exposes a way to fetch statistics explicitly.
+
+A `QueueStatsFetcher` is accessed as a [`Resource`][cats-effect-resource] as it usually implies using a connection pool. When the resource is released, the pools will be disposed properly.
+
+The explicitly fetch and report statistics every 20 seconds, one can use this approach (errors are not properly handled, and the stream approach above should be preferred):
+
+```scala mdoc:compile-only
+import scala.concurrent.duration._
+
+stats.fetcher.use { statsFetcher =>
+  (statsFetcher
+    .fetch
+    .flatMap(IO.println(_)) *>
+   IO.sleep(20.seconds)).foreverM
+}
+```
+
+[cats-effect-resource]: https://typelevel.org/cats-effect/docs/std/resource
diff --git a/docs/systems/index.md b/docs/systems/index.md
index 5b68aab..ee76f88 100644
--- a/docs/systems/index.md
+++ b/docs/systems/index.md
@@ -16,6 +16,7 @@ import com.commercetools.queue.{
   QueueClient,
   QueueAdministration,
   QueuePublisher,
+  QueueStatistics,
   QueueSubscriber,
   Serializer
 }
@@ -23,6 +24,7 @@ import com.commercetools.queue.testkit.QueueClientSuite
 
 class MyQueueClient[F[_]] extends QueueClient[F] {
   def administration: QueueAdministration[F] = ???
+  def statistics(name: String): QueueStatistics[F] = ???
   def publish[T: Serializer](name: String): QueuePublisher[F,T] = ???
   def subscribe[T: Deserializer](name: String): QueueSubscriber[F,T] = ???