doc: update metric naming spec (#984)

## Problem

We do not have a clear defined format for metric names.

## Solution

Update the doc that defines how to name a metric.

- 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.

- The benefits of this new structure `{namespace}_{noun}{Verb}` are that
it will group related metrics in the definitions file since they are
alphabetically ordered. Also when getting IDE completions all relevant
options will be grouped together. This should help for
searchability/reusability.

<!---
    REMINDER:
    - Read CONTRIBUTING.md first.
    - Add test coverage for your changes.
    - Link to related issues/commits.
    - Testing: how did you test your changes?
    - Screenshots if applicable
-->

## License

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

---------

Signed-off-by: nkomonen-amazon <[email protected]>

Author: nkomonen-amazon

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}_{did|will| }{verb}{Noun}` (eg: `toolkit_willOpenModule`, `toolkit_didLoadModule`, `toolkit_closeModule`)
+    - This format aligns with legacy names while standardizing conventions for new names going forward, though we might have chosen differently if starting from scratch.
+  - the part after the namespace must be in camelCase. `namespace_camelCaseName` (e.g. `s3_uploadObject`).
+  - Common Namespaces:
+    - `toolkit_` is for general non-feature-specific metrics created by the toolkit. Eg: `toolkit_openModule`
+    - `ide_` is for IDE specific metrics, not controlled by our extension. Eg: `ide_openEditor`
+  - 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.
+  - 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": [