Skip to content

Latest commit

 

History

History
101 lines (64 loc) · 4.02 KB

README.md

File metadata and controls

101 lines (64 loc) · 4.02 KB
Raw

Telemetry

telemetry contains code generators and definitions files to generate telemetry calls for the various AWS Toolkits.

Adding Telemetry

Where to Edit

VS Code

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.

JetBrains

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.

Visual Studio

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.

How to Edit

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.

Overriding existing telemetry

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.

Editing in IDE

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.

Format Specification

See the telemetry format document for complete format specification, or the json schema

Consuming Generators

For specifics on how to consume the generators, see each IDE specific doc: