From d21e23fd1909c17401be868ac2c0f573dfdcd27a Mon Sep 17 00:00:00 2001 From: jczuchnowski Date: Tue, 11 Apr 2023 14:13:58 +0200 Subject: [PATCH] Reorganize and update docs --- docs/configuration.md | 57 ---------------- docs/supported-libraries/_category_.yaml | 3 + docs/supported-libraries/akka/_category_.yaml | 3 + .../akka/actor-grouping.md | 58 +++++++++++++++++ .../akka/supported-metrics.md | 50 ++++++++++++++ docs/supported-libraries/zio/_category_.yaml | 3 + .../zio}/supported-metrics.md | 65 ++++--------------- .../zio}/zio-example.md | 4 +- 8 files changed, 131 insertions(+), 112 deletions(-) create mode 100644 docs/supported-libraries/_category_.yaml create mode 100644 docs/supported-libraries/akka/_category_.yaml create mode 100644 docs/supported-libraries/akka/actor-grouping.md create mode 100644 docs/supported-libraries/akka/supported-metrics.md create mode 100644 docs/supported-libraries/zio/_category_.yaml rename docs/{ => supported-libraries/zio}/supported-metrics.md (59%) rename docs/{ => supported-libraries/zio}/zio-example.md (99%) diff --git a/docs/configuration.md b/docs/configuration.md index 6c0eff01..f7848ed2 100644 --- 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.""=`. 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 new file mode 100644 index 00000000..6c8a17a0 --- /dev/null +++ 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 new file mode 100644 index 00000000..74ef6bf8 --- /dev/null +++ b/docs/supported-libraries/akka/_category_.yaml @@ -0,0 +1,3 @@ +label: 'Akka' +collapsible: true +collapsed: false \ No newline at end of file diff --git a/docs/supported-libraries/akka/actor-grouping.md b/docs/supported-libraries/akka/actor-grouping.md new file mode 100644 index 00000000..978f19d2 --- /dev/null +++ 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.""=`. 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 new file mode 100644 index 00000000..784faf8f --- /dev/null +++ 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 new file mode 100644 index 00000000..21cbd7a6 --- /dev/null +++ b/docs/supported-libraries/zio/_category_.yaml @@ -0,0 +1,3 @@ +label: 'ZIO' +collapsible: true +collapsed: false \ No newline at end of file diff --git a/docs/supported-metrics.md b/docs/supported-libraries/zio/supported-metrics.md similarity index 59% rename from docs/supported-metrics.md rename to docs/supported-libraries/zio/supported-metrics.md index 40a66d6a..a0d7b035 100644 --- a/docs/supported-metrics.md +++ b/docs/supported-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 b/docs/supported-libraries/zio/zio-example.md similarity index 99% rename from docs/zio-example.md rename to docs/supported-libraries/zio/zio-example.md index 3e92c8a1..498fd09f 100644 --- a/docs/zio-example.md +++ b/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.