From 42d9e90e58133ca11696ce27db7e1be9732a69b5 Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Fri, 26 Apr 2024 18:49:08 +0200 Subject: [PATCH 01/11] Update README file --- README.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 43c8252..777ff28 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,41 @@ # asyncapi-adoption-metrics -Metrics for measuring AsyncAPI adoption +Metrics library for measuring AsyncAPI tooling adoption. + +It aids in comprehending how AsyncAPI tools are used and adopted, facilitating ongoing improvements to our specifications and tools. Currently is being used by @asyncapi/cli as a POC and next step will be making use of it on @asyncapi/studio as well. + Requires NodeJS v18 or greater. + +## Metrics collected +We are collecting the following metrics: + +- `asyncapi_adoption.action.invoked`: +With this metric we are tracking the command executed on the CLI as soon as the command is invoked, so it hasn't been completely executed and not finished yet. We just want to know which commands are used, regardless they have failed or succeeded. + +- `asyncapi_adoption.action.finished`: +This metric tracks the command executed once it has already finished, carrying the result of the execution and some metadata based on the AsyncAPI document in place. + +## Examples +Example for `validate` command after being invoked: +``` +asyncapi_adoption.action.invoked COUNTER { action: 'validate' } 1 +``` + +Example of the data collected when the `validate` command has been executed and finished: +``` +asyncapi_adoption.action.finished COUNTER { + validation_result: 'valid', + success: true, + asyncapi_version: '2.6.0', + asyncapi_servers: 2, + asyncapi_channels: 4, + asyncapi_messages: 3, + asyncapi_operations_send: 3, + asyncapi_operations_receive: 1, + asyncapi_schemas: 52, + action: 'validate' + } 1 +``` + +## Data storage +We are making use of [New Relic API](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/#rest-api) to send the metrics collected to the _New Relic_ servers, where they are stored, and finally visualized on our own dashboards at the AsyncAPI website. + From e5c72743119b5e4bd1f7419b3a3642e2bb0f7c91 Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Mon, 29 Apr 2024 17:43:11 +0200 Subject: [PATCH 02/11] Add requested changes --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 777ff28..adef156 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ Requires NodeJS v18 or greater. We are collecting the following metrics: - `asyncapi_adoption.action.invoked`: -With this metric we are tracking the command executed on the CLI as soon as the command is invoked, so it hasn't been completely executed and not finished yet. We just want to know which commands are used, regardless they have failed or succeeded. +With this metric we are tracking any action started (but not finished) in a tool. For example, a command that got executed on the [CLI](https://github.com/asyncapi/cli/) but didn't finish yet. We just want to know which commands are used, regardless they have failed or succeeded. - `asyncapi_adoption.action.finished`: -This metric tracks the command executed once it has already finished, carrying the result of the execution and some metadata based on the AsyncAPI document in place. +With this metric we are tracking the action executed once it has already finished, carrying the result of the execution and some metadata. ## Examples -Example for `validate` command after being invoked: +Example for [CLI](https://github.com/asyncapi/cli/) `validate` command after being invoked: ``` asyncapi_adoption.action.invoked COUNTER { action: 'validate' } 1 ``` @@ -37,5 +37,5 @@ asyncapi_adoption.action.finished COUNTER { ``` ## Data storage -We are making use of [New Relic API](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/#rest-api) to send the metrics collected to the _New Relic_ servers, where they are stored, and finally visualized on our own dashboards at the AsyncAPI website. +We are making use of [New Relic API](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/#rest-api) to send the metrics collected to the _New Relic_ servers, where they are stored, and finally visualized on our own dashboards at the AsyncAPI website (WIP). From 153641e3ce35bd1c607c1c01f8219174a4961095 Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Mon, 29 Apr 2024 18:01:12 +0200 Subject: [PATCH 03/11] Include 'data privacy' section --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index adef156..9f68db4 100644 --- a/README.md +++ b/README.md @@ -39,3 +39,14 @@ asyncapi_adoption.action.finished COUNTER { ## Data storage We are making use of [New Relic API](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/#rest-api) to send the metrics collected to the _New Relic_ servers, where they are stored, and finally visualized on our own dashboards at the AsyncAPI website (WIP). +## Data privacy +All the data is anonymized, ensuring no sensitive data reaches our servers. + +Even though metrics collection is enabled by default, you can always disable tracking if you wish. To disable tracking, please run the following command: +`asyncapi config analytics --disable` + +Once disabled, if you want to enable tracking back again then run: +`asyncapi config analytics --enable` + + + From 300bf12a50a2983d668132650b0b0f1115de899e Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Mon, 29 Apr 2024 18:29:29 +0200 Subject: [PATCH 04/11] Add 'installation' section --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 9f68db4..3778bc5 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,19 @@ Metrics library for measuring AsyncAPI tooling adoption. It aids in comprehending how AsyncAPI tools are used and adopted, facilitating ongoing improvements to our specifications and tools. Currently is being used by @asyncapi/cli as a POC and next step will be making use of it on @asyncapi/studio as well. +## Installation Requires NodeJS v18 or greater. +``` +npm install @smoya/@asyncapi-adoption-metrics +yarn add @smoya/@asyncapi-adoption-metrics +``` + +## Usage + + + + + ## Metrics collected We are collecting the following metrics: @@ -48,5 +60,7 @@ Even though metrics collection is enabled by default, you can always disable tra Once disabled, if you want to enable tracking back again then run: `asyncapi config analytics --enable` +## Contributing + From 1f44977a7013e01fc6daced9f20f8f7d6c75502a Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 10:42:55 +0200 Subject: [PATCH 05/11] Include 'usage' section --- README.md | 72 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3778bc5..797a525 100644 --- a/README.md +++ b/README.md @@ -5,26 +5,62 @@ It aids in comprehending how AsyncAPI tools are used and adopted, facilitating o ## Installation Requires NodeJS v18 or greater. -``` +```bash npm install @smoya/@asyncapi-adoption-metrics yarn add @smoya/@asyncapi-adoption-metrics ``` ## Usage +The package exposes several classes, from which we can remark: +- class `Metric`: +Used to create an object containing all the properties needed to identify the metrics collected. These properties are: +```ts + name: string; + type: MetricType; + value: any; + metadata: { [key: string]: any }; +``` - - - - - -## Metrics collected -We are collecting the following metrics: - -- `asyncapi_adoption.action.invoked`: -With this metric we are tracking any action started (but not finished) in a tool. For example, a command that got executed on the [CLI](https://github.com/asyncapi/cli/) but didn't finish yet. We just want to know which commands are used, regardless they have failed or succeeded. - -- `asyncapi_adoption.action.finished`: -With this metric we are tracking the action executed once it has already finished, carrying the result of the execution and some metadata. +- class `Recorder`: +Contains all the functions needed to record the different metrics we collect, like: + - `asyncapi_adoption.action.invoked`: + With this metric we are tracking any action started (but not finished) in a tool. For example, a command that got executed on the [CLI](https://github.com/asyncapi/cli/) but didn't finish yet. We just want to know which commands are used, regardless they have failed or succeeded. + ```ts + async recordActionInvoked(actionName: string, metadata: MetricMetadata = {}) { + metadata['action'] = actionName; + this.record(new Metric('action.invoked', MetricType.Counter, 1, metadata)); + } + ``` + Example where this function is used: + ```ts + async init(): Promise { + await super.init(); + const commandName : string = this.id || ''; + await this.recordActionInvoked(commandName, this.metricsMetadata); + } + ``` + + - `asyncapi_adoption.action.finished`: + With this metric we are tracking the action executed once it has already finished, carrying the result of the execution and some metadata. + ```ts + async recordActionFinished(actionName: string, metadata: MetricMetadata = {}) { + metadata['action'] = actionName; + this.record(new Metric('action.finished', MetricType.Counter, 1, metadata)); + } + ``` + Example where this function is used: + ```ts + async finally(error: Error | undefined): Promise { + await super.finally(error); + this.metricsMetadata['success'] = error === undefined; + await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); + } + ``` + +Utils exposed by the library to operate mainly with the `Sink` interface and the metadata retrieved from the asyncapi files: +```ts +import { MetadataFromDocument, MetricMetadata, Recorder, Sink, StdOutSink } from '@smoya/asyncapi-adoption-metrics'; +``` ## Examples Example for [CLI](https://github.com/asyncapi/cli/) `validate` command after being invoked: @@ -54,13 +90,7 @@ We are making use of [New Relic API](https://docs.newrelic.com/docs/apis/intro-a ## Data privacy All the data is anonymized, ensuring no sensitive data reaches our servers. -Even though metrics collection is enabled by default, you can always disable tracking if you wish. To disable tracking, please run the following command: -`asyncapi config analytics --disable` - -Once disabled, if you want to enable tracking back again then run: -`asyncapi config analytics --enable` - -## Contributing +Every tool making use of this library should provide a mechanism to disable metrics, as you can see [here](https://github.com/asyncapi/cli/blob/master/docs/metrics_collection.md#how-to-disable-tracking). From 8d27ec345c9624c226caec13596d6e58678c5f5a Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 11:15:56 +0200 Subject: [PATCH 06/11] Include 'contributors' section --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 797a525..8148389 100644 --- a/README.md +++ b/README.md @@ -92,5 +92,27 @@ All the data is anonymized, ensuring no sensitive data reaches our servers. Every tool making use of this library should provide a mechanism to disable metrics, as you can see [here](https://github.com/asyncapi/cli/blob/master/docs/metrics_collection.md#how-to-disable-tracking). +## Contributing +Read [CONTRIBUTING](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md) guide. +## Contributors +Thanks go to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + + + +
Sergio Moya
Sergio Moya
💬 🐛 💻 🤔 👀 ⚠️		Pedro Ramos
Pedro Ramos
💬 💻 📖 🤔 🚧 👀
+ + + + + + +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! From c28672ed30be82497317c8f8ba6638e196dc85ae Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 11:32:23 +0200 Subject: [PATCH 07/11] Make some adjustments --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8148389..1efd56d 100644 --- a/README.md +++ b/README.md @@ -6,56 +6,56 @@ It aids in comprehending how AsyncAPI tools are used and adopted, facilitating o ## Installation Requires NodeJS v18 or greater. ```bash -npm install @smoya/@asyncapi-adoption-metrics -yarn add @smoya/@asyncapi-adoption-metrics +npm install @smoya/asyncapi-adoption-metrics +yarn add @smoya/asyncapi-adoption-metrics ``` ## Usage The package exposes several classes, from which we can remark: - class `Metric`: Used to create an object containing all the properties needed to identify the metrics collected. These properties are: -```ts + ```ts name: string; type: MetricType; value: any; metadata: { [key: string]: any }; -``` + ``` - class `Recorder`: Contains all the functions needed to record the different metrics we collect, like: - `asyncapi_adoption.action.invoked`: With this metric we are tracking any action started (but not finished) in a tool. For example, a command that got executed on the [CLI](https://github.com/asyncapi/cli/) but didn't finish yet. We just want to know which commands are used, regardless they have failed or succeeded. - ```ts - async recordActionInvoked(actionName: string, metadata: MetricMetadata = {}) { + ```ts + async recordActionInvoked(actionName: string, metadata: MetricMetadata = {}) { metadata['action'] = actionName; this.record(new Metric('action.invoked', MetricType.Counter, 1, metadata)); } - ``` - Example where this function is used: - ```ts + ``` + Example where this function is used: + ```ts async init(): Promise { await super.init(); const commandName : string = this.id || ''; await this.recordActionInvoked(commandName, this.metricsMetadata); } - ``` + ``` - `asyncapi_adoption.action.finished`: With this metric we are tracking the action executed once it has already finished, carrying the result of the execution and some metadata. - ```ts + ```ts async recordActionFinished(actionName: string, metadata: MetricMetadata = {}) { metadata['action'] = actionName; this.record(new Metric('action.finished', MetricType.Counter, 1, metadata)); } - ``` - Example where this function is used: - ```ts + ``` + Example where this function is used: + ```ts async finally(error: Error | undefined): Promise { await super.finally(error); this.metricsMetadata['success'] = error === undefined; await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); } - ``` + ``` Utils exposed by the library to operate mainly with the `Sink` interface and the metadata retrieved from the asyncapi files: ```ts From 309899a13654dc8ed7994e334c6e1663f674edad Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 11:35:11 +0200 Subject: [PATCH 08/11] More adjustments --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1efd56d..70439ff 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Contains all the functions needed to record the different metrics we collect, li this.record(new Metric('action.invoked', MetricType.Counter, 1, metadata)); } ``` - Example where this function is used: + Example where this function is used: ```ts async init(): Promise { await super.init(); @@ -48,7 +48,7 @@ Contains all the functions needed to record the different metrics we collect, li this.record(new Metric('action.finished', MetricType.Counter, 1, metadata)); } ``` - Example where this function is used: + Example where this function is used: ```ts async finally(error: Error | undefined): Promise { await super.finally(error); From c21d791670ec278afbbf1b3d805e38d662352ee9 Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 13:34:06 +0200 Subject: [PATCH 09/11] Add more contributors --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 70439ff..2d2aa33 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Contains all the functions needed to record the different metrics we collect, li } ``` Example where this function is used: + ```ts async init(): Promise { await super.init(); @@ -49,6 +50,7 @@ Contains all the functions needed to record the different metrics we collect, li } ``` Example where this function is used: + ```ts async finally(error: Error | undefined): Promise { await super.finally(error); @@ -106,6 +108,8 @@ Thanks go to these wonderful people ([emoji key](https://allcontributors.org/doc Sergio Moya
Sergio Moya
💬 🐛 💻 🤔 👀 ⚠️ Pedro Ramos
Pedro Ramos
💬 💻 📖 🤔 🚧 👀 + Amzani
Amzani
🤔 🐛 + Khuda Dad Nomani
Khuda Dad Nomani
🐛 From 552c92ab5ad89ec38cd2258cb4a12108c33f8e58 Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 13:45:37 +0200 Subject: [PATCH 10/11] Make some tabs adjustments --- README.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 2d2aa33..574a00e 100644 --- a/README.md +++ b/README.md @@ -32,13 +32,12 @@ Contains all the functions needed to record the different metrics we collect, li } ``` Example where this function is used: - ```ts - async init(): Promise { - await super.init(); - const commandName : string = this.id || ''; - await this.recordActionInvoked(commandName, this.metricsMetadata); - } + async init(): Promise { + await super.init(); + const commandName : string = this.id || ''; + await this.recordActionInvoked(commandName, this.metricsMetadata); + } ``` - `asyncapi_adoption.action.finished`: @@ -50,13 +49,12 @@ Contains all the functions needed to record the different metrics we collect, li } ``` Example where this function is used: - ```ts - async finally(error: Error | undefined): Promise { - await super.finally(error); - this.metricsMetadata['success'] = error === undefined; - await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); - } + async finally(error: Error | undefined): Promise { + await super.finally(error); + this.metricsMetadata['success'] = error === undefined; + await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); + } ``` Utils exposed by the library to operate mainly with the `Sink` interface and the metadata retrieved from the asyncapi files: From 69bef4b31ea89bb1370774626a1d3948de28d43f Mon Sep 17 00:00:00 2001 From: Pedro Ramos Date: Tue, 30 Apr 2024 13:48:32 +0200 Subject: [PATCH 11/11] More tabs adjustments --- README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 574a00e..d678e33 100644 --- a/README.md +++ b/README.md @@ -31,14 +31,14 @@ Contains all the functions needed to record the different metrics we collect, li this.record(new Metric('action.invoked', MetricType.Counter, 1, metadata)); } ``` - Example where this function is used: - ```ts - async init(): Promise { - await super.init(); - const commandName : string = this.id || ''; - await this.recordActionInvoked(commandName, this.metricsMetadata); - } - ``` +Example where this function is used: + ```ts + async init(): Promise { + await super.init(); + const commandName : string = this.id || ''; + await this.recordActionInvoked(commandName, this.metricsMetadata); + } + ``` - `asyncapi_adoption.action.finished`: With this metric we are tracking the action executed once it has already finished, carrying the result of the execution and some metadata. @@ -48,14 +48,14 @@ Contains all the functions needed to record the different metrics we collect, li this.record(new Metric('action.finished', MetricType.Counter, 1, metadata)); } ``` - Example where this function is used: - ```ts - async finally(error: Error | undefined): Promise { - await super.finally(error); - this.metricsMetadata['success'] = error === undefined; - await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); - } - ``` +Example where this function is used: + ```ts + async finally(error: Error | undefined): Promise { + await super.finally(error); + this.metricsMetadata['success'] = error === undefined; + await this.recordActionFinished(this.id as string, this.metricsMetadata, this.specFile?.text()); + } + ``` Utils exposed by the library to operate mainly with the `Sink` interface and the metadata retrieved from the asyncapi files: ```ts