Application Insights tokenization for Visual Studio Team Services extensions

  • Article

To apply DevOps to a Software Development Project we implement a continuous integration (CI) / continuous deployment (CD) pipeline. Next we add Application Insights telemetry to be in a position to monitor the extension, as outlined in Monitor Team Services web extensions with Visual Studio Application Insights and Application Insights and TypeScript. When we decide to open source our solution, we realise that we will share the instrumentation key publically. It’s not a show-stopper, but something we recommend to avoid. By protecting your instrumentation key, you know where the telemetry data is coming from, making it trustworthy.

One solution is to replace to replace the instrumentation key in your instrumentation code with a token, which is dynamically exchanged with your instrumentation key during the CI/CD pipeline. Let’s walk through these two common scenarios:

  • Application Insights instrumentation key that needs to be injected during the build. The instrumentation key is the same for all your environments.
  • Application Insights instrumentation key that needs to be injected for each release environment. The instrumentation key is different for some or all of your environments.

Replace sensitive information with a token

Our extensions contain a script file, TelemetryClient.ts, that contains our telemetry instrumentation code. See https://github.com/ALM-Rangers for examples.

  • In your telemetry script, for example TelemetryClient.ts, replace the value of the instrumentation key with __INSTRUMENTATIONKEY__ .
    image
  • Push the change to your public repo.
  • Optionally squash all history to clean things up and remove your instrumentation key from the history. We’ll cover this step in a future post.

Replacing a token

Scenario 1 - Hide the Application Insights instrumentation key in your OSS code and inject it during the build

  • Install the Colin's ALM Corner Build & Release Tools from the Visual Studio marketplace.
  • Edit your build definition.
  • Click on Variables [1], add a new variable  called INSTRUMENTATIONKEY [2], and set its value [3] to your Application Insights instrumentation key.
    SNAGHTMLbd8fbc9
  • Add a new task called Replace Token task to your build definition. Ensure to place it before the compilation step, which generates JavaScript from the TypeScript files.
    SNAGHTMLc48e785
  • Set the Source Path [1] to your scripts folder, and the Target File Pattern [2] to the TelemetryClient.ts file. The Token Regex parameter  defaults to __(\w+)__ [3]. This will match tokens that have double-underscore __ prefix and postfix, for example __INSTRUMENTATIONKEY__.
     SNAGHTML14ef8fba
  • Save the build.
  • Check-in the updated TelemetryClient.ts, which will trigger a build, if you have a CI/CD pipeline.
  • Verify that the Replace Token task successful. It uses regex to find our __INSTRUMENTATIONKEY__ token, it searches for the corresponding INSTRUMENTATIONKEY variables, and then replaces the token with the variable value.
    SNAGHTMLdc22697
    Running the build with system.debug set to true, will give you a more detailed trace.
    SNAGHTMLf75afc9

 

Scenario 2 - Hide the Application Insights instrumentation key in your OSS code and inject it for each release environment

For this scenario we unzip the extension VSIX package, replace the token in the TelemetryClient.js file, and zip the extension VSIX package for each environment defined by the release.

Let’s get started.

Create instrumentation key token variable

  • Click on the context … [1] for an environment and click on Configure Variable [2].
    SNAGHTML10035794
  • Add a new variable  called INSTRUMENTATIONKEY [1], set its value [2] to your Application Insights instrumentation key, and optionally click on Secret [3] to hide the value.
    SNAGHTML1005fa14
  • Use the same Application Insights instrumentation key for all environments to collect metrics for all environments in one bucket. Alternatively use different keys for the environments to collect metrics for specific environments.

Create VsixPath variable

  • Click on release Variables [1], add a new variable  called VsixPath [2], and set its value [3] to the extension VSIX package generated by your build.
    SNAGHTML101db630

Extract files from VSIX package

  • Add a new task called Extract files [1] task to your environment definition. Set the Archive file [1] to the $(VsixPath) we just created, and define a Destination folder [3].
    SNAGHTML10230ca5

Replace token

  • Add a new task called Replace Token task [1] to your environment definition, placing it after the Extract files task.
    SNAGHTML10297cc7
  • Add a new task called Source Path [1] to the folder containing the extracted files, and the Target File Pattern [2] to the TelemetryClient.js file [3].

Re-create VSIX package

  • Add the Archive files task [1] to your environment definition, placing it after the Replace Tokens task.
    SNAGHTML102cc470
  • Set the Root folder to the folder containing the extracted files, and the Archive file to create to the $(VsixPath) variable [3].

Group Tasks

To simplify the previous three steps, we can create a Task Group and encapsulate all three in one re-usable task.

  • Select the three tasks we just created [1]. Right click and select Create task group [2].
    SNAGHTML1033038f
  • Define a unique Name [1], select the Utility category [2], and set the VsixPath to *.vsix [3].
    SNAGHTML10353265
  • Once validated, the 3 tasks are automatically replaced with the new Extension Tokenize Task Group.
    SNAGHTML103c483d

That’s it.

We look forward to hearing from you

We would love your feedback. Here are some ways to connect with us: