From e85aa7dd3c150a09668f672510eaffe58256c488 Mon Sep 17 00:00:00 2001 From: nkomonen-amazon Date: Wed, 26 Feb 2025 12:41:53 -0500 Subject: [PATCH 1/2] doc: update metric naming spec See changes for the new spec when it comes to metric naming. - This will NOT retroactively apply to all existing metrics since this will require significant work refactoring that we do not want to do at the moment. Signed-off-by: nkomonen-amazon --- telemetry/telemetryformat.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/telemetry/telemetryformat.md b/telemetry/telemetryformat.md index d23488de..494921e3 100644 --- a/telemetry/telemetryformat.md +++ b/telemetry/telemetryformat.md @@ -26,9 +26,20 @@ _types_ is an array that holds telemetry metadata types. This is the information ### Metrics -_metrics_ is an array that contains the actual metrics posted to the service. `name` defines the metric name what is -posted to the service, `metadata` contains data from `types` that define characteristics of the telemetry beyond -`createTime` and a `value`. `name` must be in the format`namespace_camelCaseName` (e.g. `s3_uploadObject`). The field is optional. +_metrics_ is an array that contains the actual metrics posted to the service. +- `name` defines the metric name + - it must be in the format `namespace_camelCaseName` (e.g. `s3_objectUpload`). + - it must be in the format `{namespace}_{noun}{Verb}` (eg: `toolkit_moduleInit`) + - Common Namespaces: + - `toolkit_` is for general non-feature-specific metrics created by the toolkit. Eg: `toolkit_moduleOpen` + - `ide_` is for IDE specific metrics, not controlled by our extension. Eg: `ide_editorOpen` + - NOTE: due to legacy reasons the above spec may not be followed, but all future definitions must follow it. +- `description` explains what the metric means + - put effort to explaining the metrics purpose in detail. This tends to be the source of truth for + what the metric actually means and how it should be used. +- `metadata` contains data from `types` that define characteristics of the telemetry beyond +`createTime` and a `value`. + - This field is optional, but default `types` are automatically added regardless. ``` "metrics": [ From fdf33201d896b859b9e3d42febf2f2e38335042c Mon Sep 17 00:00:00 2001 From: nkomonen-amazon Date: Wed, 26 Feb 2025 14:31:10 -0500 Subject: [PATCH 2/2] address PR comments Signed-off-by: nkomonen-amazon --- telemetry/telemetryformat.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/telemetry/telemetryformat.md b/telemetry/telemetryformat.md index 494921e3..2db17b2e 100644 --- a/telemetry/telemetryformat.md +++ b/telemetry/telemetryformat.md @@ -30,16 +30,16 @@ _metrics_ is an array that contains the actual metrics posted to the service. - `name` defines the metric name - it must be in the format `namespace_camelCaseName` (e.g. `s3_objectUpload`). - it must be in the format `{namespace}_{noun}{Verb}` (eg: `toolkit_moduleInit`) + - This format enables a natural grouping of related metrics in our definitions file, as well as improved searchability. - Common Namespaces: - `toolkit_` is for general non-feature-specific metrics created by the toolkit. Eg: `toolkit_moduleOpen` - `ide_` is for IDE specific metrics, not controlled by our extension. Eg: `ide_editorOpen` - - NOTE: due to legacy reasons the above spec may not be followed, but all future definitions must follow it. + - NOTE: legacy metrics don't always follow the above rules, but new definitions must follow them. - `description` explains what the metric means - - put effort to explaining the metrics purpose in detail. This tends to be the source of truth for - what the metric actually means and how it should be used. -- `metadata` contains data from `types` that define characteristics of the telemetry beyond -`createTime` and a `value`. - - This field is optional, but default `types` are automatically added regardless. + - put effort to explaining the metrics purpose in detail. This tends to be the source of truth for what the metric actually means and how it should be used. + - if a metric is deprecated, it must be indicated here +- `metadata` contains fields (`types`) that define characteristics of the telemetry beyond `createTime` and a `value`. + - This field is optional, but default fields (`types`) are always present on generated metrics. ``` "metrics": [