Merge pull request #682 from ScalaConsultants/zio-docs-update

Reorganize and update docs
ScalaConsultants · Apr 11, 2023 · af50426 · af50426
2 parents 8dd2e6d + d21e23f
commit af50426
Show file tree

Hide file tree

Showing 8 changed files with 131 additions and 112 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -11,60 +11,3 @@ To provide the configuration file to the agent you can either `-Dotel.javaagent.
 ## OTEL namespace options
 
 You can find the full list of available configuration options [here](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md)
-
-## Mesmer options
-
-### Akka actors grouping
-
-When the actors' hierarchy grows or there are short-living actors referenced by a unique path name, it can be impractical to give each metric a unique set of attributes. This amplifies the amount of data exported and can affect collector performance. To solve this, Mesmer allows the definition of fine-grained rules on how metrics associated with different actors can be grouped together.
-
-There are three actor attributes grouping options:
-  - **group** - the metrics, collected for all the actors matching the given path, share the `actor_path` attribute.
-  - **instance** - the metrics, collected for actors matching this path, have a unique `actor_path` attribute.
-  - **disabled** - the metrics, collected for all the actors matching the given path, do not get `actor_path` attribute.
-
-By default the path grouping is disabled. You can change this by launching the Mesmer extension with `-Dio.scalac.mesmer.actor.reporting-default=group` configuration option. This will give all the actors' metrics the attribute `actor_path="/"`.
-
-Alternatively, it is possible to override a single path grouping strategy as following
-```sh
-java -javaagent:path/to/opentelemetry-javaagent.jar \
-  -Dotel.javaagent.extensions=path/to/mesmer-otel-extension.jar \
-  -Dio.scalac.mesmer.actor.reporting-default=ignore \
-  -Dio.scalac.mesmer.actor.rules."/user/**"=group \
-  -Dio.scalac.mesmer.actor.rules."/system/**"=group \
-  -jar your-app.jar
-```
-This configuration will aggregate metrics for system and user hierarchies separately, grouping them by `actor_path="/system"` and `actor_path="/user"` attributes correspondingly.
-
-The individual rule syntax is `io.scalac.mesmer.actor.rules."<MATCHING_PATH>"=<GROUPING_OPTION>`. The matching path supports limited set of wildcards, aiding to group metrics for variable path segments.
-
-- **/** - matches exactly one actor and therefore can be used only with the `instance` grouping option.
-  For a topology of */user/my-actor* and */user/my-actor/1* and the rules
-  ```
-  io.scalac.mesmer.actor.reporting-default=group
-  io.scalac.mesmer.actor.rules."/user/my-actor"=instance
-  ```
-  the metrics from */user/my-actor* will get the attribute `actor_path="/user/my-actor"` while the metrics from */user/my-actor/1* will get the attribute `actor_path="/"` and likely will be grouped with metrics from other actors.
-
-- **/\*** - matches a single variable tailing segment.
-  For a topology of */user/my-actor*, */user/my-actor/1*, */user/my-other-actor* and the rules
-  ```
-  io.scalac.mesmer.actor.reporting-default=ignore
-  io.scalac.mesmer.actor.rules."/user/*"=instance
-  ```
-  the metrics from */user/my-actor* and */user/my-other-actor* will get same values for `actor_path` attribute, while */user/my-actor/1* will be ignored.
-
-- **/\*\*** - matches all tailing segments.
-  For a topology of */user/my-actor*, */user/my-actor/1*, */user/my-other-actor* and the rules
-  ```
-  io.scalac.mesmer.actor.reporting-default=ignore
-  io.scalac.mesmer.actor.rules."/user/**"=instance
-  ```
-  this will produce a unique metric for each actor with root at */user*. This wildcard also can be applied using with grouping,
-
-  ```
-  io.scalac.mesmer.actor.reporting-default=ignore
-  io.scalac.mesmer.actor.rules."/user/**"=group
-  ```
-
-  Resulting in all metrics from actors with root at */user* to be aggregated using common attribute `actor_path="/user"`
diff --git a/docs/supported-libraries/_category_.yaml b/docs/supported-libraries/_category_.yaml
@@ -0,0 +1,3 @@
+label: 'Supported libraries'
+collapsible: false
+collapsed: false
diff --git a/docs/supported-libraries/akka/_category_.yaml b/docs/supported-libraries/akka/_category_.yaml
@@ -0,0 +1,3 @@
+label: 'Akka'
+collapsible: true
+collapsed: false
diff --git a/docs/supported-libraries/akka/actor-grouping.md b/docs/supported-libraries/akka/actor-grouping.md
@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+---
+
+# Actor grouping
+
+When the actors' hierarchy grows or there are short-living actors referenced by a unique path name, it can be impractical to give each metric a unique set of attributes. This amplifies the amount of data exported and can affect collector performance. To solve this, Mesmer allows the definition of fine-grained rules on how metrics associated with different actors can be grouped together.
+
+There are three actor attributes grouping options:
+  - **group** - the metrics, collected for all the actors matching the given path, share the `actor_path` attribute.
+  - **instance** - the metrics, collected for actors matching this path, have a unique `actor_path` attribute.
+  - **disabled** - the metrics, collected for all the actors matching the given path, do not get `actor_path` attribute.
+
+By default the path grouping is disabled. You can change this by launching the Mesmer extension with `-Dio.scalac.mesmer.actor.reporting-default=group` configuration option. This will give all the actors' metrics the attribute `actor_path="/"`.
+
+Alternatively, it is possible to override a single path grouping strategy as following
+```sh
+java -javaagent:path/to/opentelemetry-javaagent.jar \
+  -Dotel.javaagent.extensions=path/to/mesmer-otel-extension.jar \
+  -Dio.scalac.mesmer.actor.reporting-default=ignore \
+  -Dio.scalac.mesmer.actor.rules."/user/**"=group \
+  -Dio.scalac.mesmer.actor.rules."/system/**"=group \
+  -jar your-app.jar
+```
+This configuration will aggregate metrics for system and user hierarchies separately, grouping them by `actor_path="/system"` and `actor_path="/user"` attributes correspondingly.
+
+The individual rule syntax is `io.scalac.mesmer.actor.rules."<MATCHING_PATH>"=<GROUPING_OPTION>`. The matching path supports limited set of wildcards, aiding to group metrics for variable path segments.
+
+- **/** - matches exactly one actor and therefore can be used only with the `instance` grouping option.
+  For a topology of */user/my-actor* and */user/my-actor/1* and the rules
+  ```
+  io.scalac.mesmer.actor.reporting-default=group
+  io.scalac.mesmer.actor.rules."/user/my-actor"=instance
+  ```
+  the metrics from */user/my-actor* will get the attribute `actor_path="/user/my-actor"` while the metrics from */user/my-actor/1* will get the attribute `actor_path="/"` and likely will be grouped with metrics from other actors.
+
+- **/\*** - matches a single variable tailing segment.
+  For a topology of */user/my-actor*, */user/my-actor/1*, */user/my-other-actor* and the rules
+  ```
+  io.scalac.mesmer.actor.reporting-default=ignore
+  io.scalac.mesmer.actor.rules."/user/*"=instance
+  ```
+  the metrics from */user/my-actor* and */user/my-other-actor* will get same values for `actor_path` attribute, while */user/my-actor/1* will be ignored.
+
+- **/\*\*** - matches all tailing segments.
+  For a topology of */user/my-actor*, */user/my-actor/1*, */user/my-other-actor* and the rules
+  ```
+  io.scalac.mesmer.actor.reporting-default=ignore
+  io.scalac.mesmer.actor.rules."/user/**"=instance
+  ```
+  this will produce a unique metric for each actor with root at */user*. This wildcard also can be applied using with grouping,
+
+  ```
+  io.scalac.mesmer.actor.reporting-default=ignore
+  io.scalac.mesmer.actor.rules."/user/**"=group
+  ```
+
+  Resulting in all metrics from actors with root at */user* to be aggregated using common attribute `actor_path="/user"`
diff --git a/docs/supported-libraries/akka/supported-metrics.md b/docs/supported-libraries/akka/supported-metrics.md
@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+---
+
+# Supported metrics
+
+## Akka core
+
+| Metric             | OTel Type |
+|--------------------|-----------|
+| Running actors     | gauge     |
+| Mailbox size       | gauge     |
+| Stashed messaged   | counter   |
+| Mailbox time       | gauge     |
+| Processed messages | counter   |
+| Processing time    | gauge     |
+| Sent messages      | counter   |
+
+## Akka Cluster
+
+| Metric                | OTel Type |
+|-----------------------|-----------|
+| Shards per region     | gauge     |
+| Reachable nodes       | gauge     |
+| Unreachable nodes     | gauge     |
+| Entities per region   | gauge     |
+| Shard regions on node | gauge     |
+| Entities on node      | gauge     |
+| Nodes down            | counter   |
+
+## Akka Persistence
+
+| Metric                 | OTel Type |
+|------------------------|-----------|
+| Persisted events       | histogram |
+| Event persistence time | histogram |
+| Recovery total         | counter   |
+| Recovery time          | histogram |
+| Snapshots              | counter   |
+
+## Akka Streams (experimental)
+
+| Metric                       | OTel Type |
+|------------------------------|-----------|
+| Running streams              | gauge     |
+| Running operators per stream | gauge     |
+| Running operators            | gauge     |
+| Stream throughput            | counter   |
+| Operator throughput          | counter   |
+| Operator processing time     | counter   |
diff --git a/docs/supported-libraries/zio/_category_.yaml b/docs/supported-libraries/zio/_category_.yaml
@@ -0,0 +1,3 @@
+label: 'ZIO'
+collapsible: true
+collapsed: false
diff --git a/docs/supported-metrics.md → ...ported-libraries/zio/supported-metrics.md b/docs/supported-metrics.md → ...ported-libraries/zio/supported-metrics.md
@@ -1,63 +1,22 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
 ---
 
 # Supported metrics
 
-In Mesmer we support 3 types of metrics:
+## ZIO Metrics API
 
-* gauge - for sampled values
-* counter - monotonic counter
-* histograms - for recording value distributions
-
-## Akka core
-
-| Metric             | Type    |
-|--------------------|---------|
-| Running actors     | gauge   |
-| Mailbox size       | gauge   |
-| Stashed messaged   | counter |
-| Mailbox time       | gauge   |
-| Processed messages | counter |
-| Processing time    | gauge   |
-| Sent messages      | counter |
-
-## Akka Cluster
-
-| Metric                | Type    |
-|-----------------------|---------|
-| Shards per region     | gauge   |
-| Reachable nodes       | gauge   |
-| Unreachable nodes     | gauge   |
-| Entities per region   | gauge   |
-| Shard regions on node | gauge   |
-| Entities on node      | gauge   |
-| Nodes down            | counter |
-
-## Akka Persistence
-
-| Metric                 | Type      |
-|------------------------|-----------|
-| Persisted events       | histogram |
-| Event persistence time | histogram |
-| Recovery total         | counter   |
-| Recovery time          | histogram |
-| Snapshots              | counter   |
-
-## Akka Streams (experimental)
-
-| Metric                       | Type    |
-|------------------------------|---------|
-| Running streams              | gauge   |
-| Running operators per stream | gauge   |
-| Running operators            | gauge   |
-| Stream throughput            | counter |
-| Operator throughput          | counter |
-| Operator processing time     | counter |
+| ZIO Metric Type                       | OTel Type   |
+|---------------------------------------|-------------|
+| Counter                               | counter     |
+| Frequency                             | counter     |
+| Gauge                                 | gauge       |
+| Histogram                             | histogram   |
+| Summary                               | unsupported |
 
 ## ZIO Executor Metrics
 
-| Metric                                | Type      |
+| Metric                                | OTel Type |
 |---------------------------------------|-----------|
 | Executor Capacity                     | gauge     |
 | Executor Concurrency                  | gauge     |
@@ -68,7 +27,7 @@ In Mesmer we support 3 types of metrics:
 
 ## ZIO JVM Metrics
 
-| Metric                                | Type      |
+| Metric                                | OTel Type |
 |---------------------------------------|-----------|
 | JVM Buffer Pool Capacity Bytes        | gauge     |
 | JVM Buffer Pool Used Buffers          | gauge     |
@@ -97,7 +56,7 @@ In Mesmer we support 3 types of metrics:
 
 ## ZIO Runtime Metrics
 
-| Metric                                | Type      |
+| Metric                                | OTel Type |
 |---------------------------------------|-----------|
 | Forwarded Null                        | counter   |
 | Process CPU Seconds Total             | gauge     |

diff --git a/docs/zio-example.md → docs/supported-libraries/zio/zio-example.md b/docs/zio-example.md → docs/supported-libraries/zio/zio-example.md
@@ -1,8 +1,8 @@
 ---
-sidebar_position: 5
+sidebar_position: 2
 ---
 
-# ZIO Example
+# Example
 
 ZIO exposes a lot of information about its own and application internals out-of-the-box - like ZIO Executor metrics and JVM metrics. In addition integrated ZIO Metrics DSL allows us to create custom metrics measuring effects of our choice.