docs: telemetry #3779

Author: justinmk3

.editorconfig

@@ -8,10 +8,10 @@ end_of_line = lf
 insert_final_newline = true
 indent_size = 4
 indent_style = space
+max_line_length = 100
 
 [*.{js,ts,py}]
 charset = utf-8
-max_line_length = 100
 
 [Makefile]
 indent_style = tab

CONTRIBUTING.md

@@ -273,6 +273,21 @@ then following the log with:
 
     tail -F ~/awstoolkit.log
 
+### Telemetry
+
+See [aws-toolkit-common/telemetry](https://github.com/aws/aws-toolkit-common/tree/main/telemetry#telemetry) for full details about defining telemetry metrics.
+
+-   You can define new metrics during development by adding items to
+    [telemetry/vscodeTelemetry.json](https://github.com/aws/aws-toolkit-vscode/blob/21ca0fca26d677f105caef81de2638b2e4796804/src/shared/telemetry/vscodeTelemetry.json).
+    -   Building the project will trigger the `generateClients` build task, which generates new symbols in `shared/telemetry/telemetry`, which you can import via:
+        ```
+        import { telemetry } from '../../shared/telemetry/telemetry'
+        ```
+    -   The metrics defined in `vscodeTelemetry.json` should be upstreamed to [aws-toolkit-common](https://github.com/aws/aws-toolkit-common/blob/main/telemetry/definitions/commonDefinitions.json) after launch (at the latest).
+-   Metrics are dropped (not posted to the service) if the extension is running in [CI or other
+    automation tasks](https://github.com/aws/aws-toolkit-vscode/blob/21ca0fca26d677f105caef81de2638b2e4796804/src/shared/vscode/env.ts#L71-L73).
+    -   You can always _test_ telemetry via [assertTelemetry()](https://github.com/aws/aws-toolkit-vscode/blob/21ca0fca26d677f105caef81de2638b2e4796804/src/test/testUtil.ts#L164), regardless of the current environment.
+
 ### Service Endpoints
 
 Endpoint overrides can be set per-service using the `aws.dev.endpoints` settings. This is a JSON object where each key is the service ID (case-insensitive) and each value is the endpoint. Refer to the SDK [API models](https://github.com/aws/aws-sdk-js/tree/master/apis) to find relevant service IDs.
@@ -285,13 +300,6 @@ Example:
 }
 ```
 
-### Telemetry and Automation
-
-Metrics are only emitted if the extension is assumed to be ran from an actual user rather than automation scripts.
-This condition is checked through an environment variable `AWS_TOOLKIT_AUTOMATION` which is set by test entry points.
-If any truthy value is present, telemetry will be dropped if the current build is not a release version. Utility functions,
-such as `assertTelemetry`, can be used to test specific telemetry emits even in automation.
-
 ### SAM/CFN ("goformation") JSON schema
 
 See [docs/cfn-schema-support.md](./docs/cfn-schema-support.md) for how to fix