telemetry contains code generators and definitions files to generate telemetry calls for the various
AWS IDE Extensions.
For prototyping telemetry, modify the src/shared/telemetry/vscodeTelemetry.json inside the toolkit repository.
Make changes in that file, then from the AWS Toolkit repo root run:
npm run generateTelemetry
To update the generated output. When you are satisfied with generated telemetry, move
the definitions you just added to the appropriate file in definitions in this repo.
Edits to the generator files are made in this repo located in telemetry/vscode/src/.
You can manually run your changes by first building npm run prepack and then modifying the dev dependency inside the AWS Toolkit repo package.json file:
"@aws-toolkits/telemetry": "file:/path/to/built/dependency"
To generate telemetry run npm run generateTelemetry from the AWS Toolkit repo.
By using Gradle composite builds, we can prototype telemetry for the JetBrains toolkit directly in this repository.
Make changes to the appropriate file in definitions in this repository, then from the toolkit directory run:
./gradlew generateTelemetry --include-build <path/to/aws-toolkit-common>/telemetry/jetbrains
Your changes should then be reflected in the generated output.
For prototyping telemetry, and to define product-specific metrics, modify toolkitcore\AWSToolkit.Util\Telemetry\vs-telemetry-definitions.json inside the toolkit repository. These are known as Supplemental Telemetry definitions, and you can read more about this here.
After changing the file, you'll need to build the generator from this repo. Then you'll use the generator as follows to update the generated supplemental telemetry code:
Amazon.AwsToolkit.Telemetry.Events.Generator.exe -s <VS_TOOLKIT_REPO_ROOT>\toolkitcore\AWSToolkit.Util\Telemetry\vs-telemetry-definitions.json -o <VS_TOOLKIT_REPO_ROOT>\toolkitcore\AWSToolkit.Util\Telemetry -f ToolkitTelemetryEvents.generated.cs
Commit the json and cs files to the VS Toolkit repo as needed.
The easiest way to edit telemetry is to copy existing telemetry and change the values. For example, to add a piece of metadata that is best represented by a string based enum, take an existing type:
{
"name": "schemaLanguage",
"type": "string",
"allowedValues": ["Java8", "Python36", "TypeScript3"],
"description": "Languages targeted by the schemas service"
}and change name, description, and the values in allowedValues
{
"name": "veryImportantInformation",
"type": "string",
"allowedValues": ["yes", "no", "maybe"],
"description": "This description is generated into doc comments so make it count"
}Then rerun the generator. This example will generate a new type that can be imported or used in telemetry calls.
CI jobs run validation checks on the telemetry definitions file. For example, entries are expected to exist in alphabetical order. You may want to check this yourself before creating a PR, by switching to the telemetry/validation folder, and running:
npm install
npm run validate
You can also run npm run fix to apply simple fixes to the file (like re-ordering).
In VSCode and JetBrains, extra telemetry files will take precedence over existing definitions. For example, if you have a metric for lambda_update, adding another lambda_update in the repo's extra telemetry files will override all of the values of it.
Types work similarly, and will also be overwritten by extra telemetry files.
The telemetry format comes with a json schema document here that can be loaded into the IDE while editing the documents. This will give you feedback as you edit.
See the telemetry format document for complete format specification, or the json schema
For specifics on how to consume the generators, see each IDE specific doc: