You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can find documentation to create VSCode IDE settings for CodeCatalyst blueprints at [docs/vscode-config.md](./docs/vscode-config.md).
@@ -221,11 +222,28 @@ To send a pull request:
221
222
2. Modify the source; focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
222
223
- Read the [project guidelines](#guidelines), this is very important for non-trivial changes.
223
224
3. Commit to your fork [using clear commit messages](#commit-messages).
224
-
4. Update the changelog by running `npm run newChange`.
225
-
- Note: the main purpose of the `newChange` task is to avoid merge conflicts.
225
+
4. Update the [changelog](#changelog).
226
226
5. [Create a pull request](https://help.github.com/articles/creating-a-pull-request/).
227
227
6. Pay attention to any CI failures reported in the pull request.
228
228
229
+
### Changelog
230
+
231
+
Pull requests that change customer-facing behavior (in any _describable_ way) should include
232
+
a changelog item(s). Update the changelog via:
233
+
234
+
npm run newChange
235
+
236
+
Guidelines:
237
+
238
+
- Describe the change in a way that is meaningful to the _customer_.
239
+
- ❌ `Remove the cache when the connection wizard is re-launched`
240
+
- ✅ `Connection wizard sometimes shows the old (stale) connection`
241
+
- If there are multiple unrelated changes, run `npm run newChange` for each change.
242
+
- **Bug Fix** changes should describe the _problem being fixed_. This tends to produce simpler,
243
+
more-readable descriptions. It's redundant to mention "Fixed" in the description. Example:
244
+
- ❌ `Fixed S3 bug which caused filenames to be uppercase`
245
+
- ✅ `S3 filenames are always uppercase`
246
+
229
247
### Commit messages
230
248
231
249
Generally your PR description should be a copy-paste of your commit message(s).
@@ -238,7 +256,6 @@ Follow these [commit message guidelines](https://cbea.ms/git-commit/):
238
256
- Imperative voice ("Fix bug", not "Fixed"/"Fixes"/"Fixing").
239
257
- Body: for non-trivial or uncommon changes, explain your motivation for the
240
258
change and contrast your implementation with previous behavior.
241
-
242
259
- Often you can save a _lot_ of words by using this simple template:
- Webviews very easily lead to the [inner-platform effect](https://en.wikipedia.org/wiki/Inner-platform_effect).
17
+
Because they are fully isolated from vscode and its extensions, they must include any code
18
+
and frameworks.
19
+
- Leads to extra dependencies.
20
+
- Webviews inherit none of vscode's standard features. This means features like keyboard
21
+
shortcuts, syntax highlighting, and editor navigation, are not available to users. Instead
22
+
users must learn the custom _web application_ embedded in the webview.
23
+
24
+
## Dependencies
25
+
26
+
Dependencies can be very high-leverage if they solve a difficult problem.
27
+
Dependencies are also a [maintenance burden](https://github.com/aws/aws-toolkit-vscode/pulls?q=is%3Apr+author%3Aapp%2Fdependabot+is%3Aclosed) and security risk
28
+
Copy-pasting or "inlining" a dependency doesn't solve that, of course--it only hides the problem (another cost).
29
+
So before taking on a new dependency, ask:
30
+
31
+
- is this solving a problem that is worth the cost?
32
+
- could the problem be solved in some other way that involves a smaller cost? For example, using
33
+
an isolated function with good test coverage, or a native vscode feature such as a TreeView or
34
+
quickpick menu.
14
35
15
36
## Naming
16
37
@@ -91,6 +112,13 @@ that is a net cost.
91
112
- Localize UI messages. Do _not_ localize log and exception messages.
92
113
- Use `extensionUtilities.getIdeProperties()` to automatically match IDE
Copy file name to clipboardExpand all lines: docs/develop.md
+15-1Lines changed: 15 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,22 @@ Notes about the codebase, its utilities, special globals, etc.
5
5
## VSCode context keys
6
6
7
7
VScode extensions can use vscode 'setContext' command to set special context keys which are
8
-
available in `package.json`. This extension sets the following keys:
8
+
available in `package.json`.
9
9
10
+
### Defining a new setContext key
11
+
12
+
If you must define a new key,
13
+
14
+
- Prefix it with `aws.` as recommended by the [vscode docs](https://code.visualstudio.com/api/extension-guides/command#using-a-custom-when-clause-context).
15
+
- Use brevity. Less is more.
16
+
- Document it in the list below.
17
+
18
+
### Toolkit setContext keys
19
+
20
+
We set the following keys:
21
+
22
+
-`isCloud9`: This is hardcoded by Cloud9 itself, not the Toolkit.
23
+
- Cloud9 _does not support setContext_. So this is the only usable key there.
10
24
-`aws.codecatalyst.connected`: CodeCatalyst connection is active.
11
25
-`CODEWHISPERER_ENABLED`: CodeWhisperer connection is active.
12
26
-`aws.isDevMode`: AWS Toolkit is running in "developer mode".
Copy file name to clipboardExpand all lines: docs/telemetry.md
+35-9Lines changed: 35 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,35 @@
1
1
# Telemetry
2
2
3
+
## Development
4
+
3
5
See [aws-toolkit-common/telemetry](https://github.com/aws/aws-toolkit-common/tree/main/telemetry#telemetry) for full details about defining telemetry metrics.
4
6
5
7
- You can define new metrics during development by adding items to
-Building the project will trigger the `generateClients` build task, which generates new symbols in `shared/telemetry/telemetry`, which you can import via:
9
+
-The `generateClients` build task generates new symbols in `shared/telemetry/telemetry`, which you can import via:
8
10
```
9
-
import { telemetry } from '../../shared/telemetry/telemetry'
11
+
import { telemetry } from '/shared/telemetry/telemetry'
10
12
```
11
-
- 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).
13
+
- When your feature is released, the "development" metrics you defined in `vscodeTelemetry.json` should be upstreamed to [aws-toolkit-common](https://github.com/aws/aws-toolkit-common/blob/main/telemetry/definitions/commonDefinitions.json).
12
14
- Metrics are dropped (not posted to the service) if the extension is running in [CI or other
- 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.
15
17
16
-
### Incrementally Building a Metric
18
+
## Guidelines
19
+
20
+
- Use `run()` where possible. It automatically sets the `result` and `reason` fields. See below for details.
21
+
- `run()` gets the `reason` value from the `Error.code` property of any exception that is thrown.
22
+
- Your code can throw `ToolkitError` with a `code` field to communicate errors, validation issues, or [cancellation](https://github.com/aws/aws-toolkit-vscode/blob/06661f84530c6b5331579871d685515700b7767e/src/auth/sso/model.ts#L138). See below.
23
+
- The `reason` and `result` fields are standard metric fields shared by all Toolkits (VSCode, JetBrains, VisualStudio).
24
+
They should be used instead of special-purpose metrics or fields.
25
+
- `result` allows the Toolkits team to monitor all features for potential regressions.
26
+
- `reason` gives insight into the cause of a `result=Failed` metric.
27
+
- `telemetry.record()` called during a `telemetry.foo.run(…)` context will automatically annotate the current `foo` metric.
28
+
- For example, the cloudwatch logs feature adds `hasTimeFilter` info its metrics by [calling telemetry.record()](https://github.com/aws/aws-toolkit-vscode/blob/06661f84530c6b5331579871d685515700b7767e/src/cloudWatchLogs/cloudWatchLogsUtils.ts#L21-L24).
17
29
18
-
In certain scenarios, you may have some code that has multiple stages/steps in its execution.
30
+
## Incrementally Building a Metric
31
+
32
+
User actions or other features may have multiple stages/steps, called a "workflow" or just "flow". A telemetry ["trace"](https://opentelemetry.io/docs/concepts/signals/traces/) captures a flow as tree of ["spans"](https://opentelemetry.io/docs/concepts/signals/traces/#spans).
19
33
20
34
For example, `setupThing()` has multiple steps until it is completed, ending with `lastSetupStep()`.
21
35
@@ -49,12 +63,24 @@ Here we emitted a final metric based on the failure or success of the entire exe
49
63
50
64
<br>
51
65
52
-
But usually code is not flat and there are many nested calls. If something goes wrong during the execution it would be useful to have more specific information at the area of failure. So what we can do is use `run()` along with `record()`.
66
+
But usually code is not flat and there are many nested calls. If something goes wrong during the execution it would be useful to have more specific information at the area of failure. For that we can use `run()` along with `telemetry.record()`.
67
+
68
+
`run()` accepts a callback, and when the callback is executed, any uses of `telemetry.record()` at _any nesting level_ during execution of that callback, will update the
69
+
attributes of the ["current metric"](https://github.com/aws/aws-toolkit-vscode/blob/13cb98d5315092ddc9eb5ba898e5f26810dada25/src/shared/telemetry/spans.ts#L233).
70
+
And at the end (that is, when `run()` returns) we will emit a single metric with the last updated attributes.
When an exception is thrown from a `run()` context, `run()` will [automatically set](https://github.com/aws/aws-toolkit-vscode/blob/a583825bec6cb68c4942fa60d185644833528532/src/shared/errors.ts#L273-L289)
74
+
the `reason` field based on the Error `code` field. You can explicitly set `code` when throwing
75
+
a `ToolkitError`, for [example](https://github.com/aws/aws-toolkit-vscode/blob/d08e59952a6c75a5c6c00fdc464e26750c0e85f5/src/auth/auth.ts#L530):
76
+
77
+
throw new ToolkitError('No sso-session name found in ~/.aws/config', { code: 'NoSsoSessionName' })
78
+
79
+
Note: prefer reason codes with a format similar to existing codes (not sentences). You can find existing codes by searching the codebase:
53
80
54
-
`run()` takes in a callable, and when the callable is executed, any uses of `record()` within that callable will update the
55
-
attributes of the specific metric. And at the end we will emit a single metric with the last updated attributes.
0 commit comments