CLRIE Profiler Design Doc

Overview

The CLR Instrumentation Engine (CLRIE) MSI/MSM installs the dlls into a versioned folder under Program Files. Since COR_PROFILER environment variables require the dll’s full path, the version must be known upfront. Conflicts can occur when different products deploy different versions of the CLRIE.

Goals

• Profilers can cooperatively run on the latest version of CLRIE.
• Security updates are provided with newer CLRIE versions and automatically used on next process restart.
• Easy cleanup due to filelocking proxy and CLRIE being used
• Proxy can be updated separately from CLRIE
• (SnapshotDebugger) Design should work with Azure VM/VMSS (WAD extension) and Azure App Service

Proxy Benefits

From a profiler author’s standpoint, having a proxy pointing to the latest version removes the burden of determining whether CLRIE is already installed and which version of CLRIE is the latest. Profiler authors can ship with a compatible CLRIE version, point their environment variables to the CLRIE proxy, and run with the guarantee that the version of CLRIE being used is at least the version they ship with (an invariant of CLRIE is that it’s backwards compatible).

Since the proxy points to the latest version, security updates and bugfixes are easily deployed out-of-band by installing newer MSIs. When the process eventually restarts, the proxy logic will automatically pick up a newer CLRIE if it exists.

From a CLRIE developer’s perspective, the proxy simplifies maintainability by mirroring the behavior used by the App Service preinstalled site extension where configuring the application settings using tilda semantics ~X automatically enables the latest major version X of the site extension (eg. ~1 ensures the latest version 1.x.x is used). The proxy will not be used by the App Service preinstalled site extension since it points to the latest CLRIE version already.

Background

CLRIE Installation Design

The CLRIE builds an x86 and x64 platform MSI and MSM. The x64 installers contain both x86 and x64 bits while the x86 installers contain only x86 bits.

The installers do not modify registry keys nor environment variables; they are designed to simply drop files into a versioned folder. The x64 and x86 binaries are located in %ProgramFiles% (64bit) and %ProgramFiles(x86)% (32bit) as described below:

%ProgramFiles%|%ProgramFiles(x86)%
    Microsoft Instrumentation Engine 
        <CLRIE Version> 
            Instrumentation64|32 
                <dlls> 

This allows side-by-side versions of the CLRIE to coexist and respects the installer component rules between the CLRIE MSI and external profiler MSIs that consume CLRIE MSM modules.

CLRIE Versions

CLRIE is built with both Debug and Release configuration as well as supports the notion of preview and public-release versions.
The build context modifies the version as follows:

• The base version is defined with three numbers separated by periods (eg. 1.0.0).
• Preview builds append –build##### to the base version; public-release builds do not.
• Debug builds append _debug to the version; Release builds do not.

Different configurations (debug and release) still represent the same functional code and have “equal” versions. However, preview builds only contain a subset of features or functionality that will be available in the public-release (ie. public release builds are “newer” than preview builds with the same version). This becomes relevant in version comparisons.

To summarize, there are 4 variations of the CLRIE version:

Version Comparisons

Preview versions are considered previews of the base version they’re associated with. This means 1.0.0-build1 is a preview of 1.0.0. By design, preview versions are “older” than the public-release version. Here is an example of version comparison:

1.0.0-build1 < 1.0.0-build2 < 1.0.0 < 1.0.1-build1 < 1.0.1

Since debug and release configurations of a specific version represent the same code and share the same functionality, they are considered separate but equal versions. The default proxy behavior is to ignore debug versions but can be configured by the environment variable to only use debug versions.

InstrumentationEngineProxy_UseDebug = 1

If no debug builds are available when the UseDebug flag is set, or if no release builds are available and UseDebug flag is not set, the proxy will crash and return an error code. This is to avoid production environments accidentally pick up a debug version of CLRIE.

Users can also set UsePreview. Like UseDebug except includes preview versions. This is an optional flag for test environments to pick up preview versions of CLRIE. Production would by default not use preview bits.

Another flag to configure would be UseSpecificVersion to allow the proxy to pick a single version available to it. If this version doesn’t exist, the proxy will error out. The goal of this flag would be for testing and flexibility, although it does encourage anti-cooperation model. The better workaround to this is to just forward COR_PROFILER to the specific CLRIE version.

Proxy Architecture and Design

The proxy itself should be supported on all OS platforms, however its implementation is platform dependent due to its dependency on a “common folder” location. For the first iteration and scope of this design document, only Windows OS is discussed.

The folder structure of the proxy is described below:

%ProgramFiles%|%ProgramFiles(x86)% 
    Microsoft Instrumentation Engine 
        <CLRIE Version> 
            Instrumentation64|32 
                <dlls> 
        Proxy 
            <Proxy Version> 
                proxy.dll 

The profiler proxy will be implemented as a standalone dll and hosts an IClassFactory implementation that will forward the DllGetClassObject call to the latest version of CLRIE as previously discussed.

The Proxy Version

The proxy is meant to be a simple and shallow implementation that determines the latest CLRIE version. This means updates to the proxy should be infrequent and small. In addition, we want to mirror the behavior of Azure App Service preinstalled site extension. The proposed proxy versioning scheme is simple:

• Version 1 proxy will point to the latest major version 1 of CLRIE. This means all major version 1 CLRIE will carry the version 1 proxy.
• The proxy.dll file version can be changed to ensure MSI file versioning rules allow patching proxies from newer builds.

Using the Proxy

The COR_PROFILER environment variables should point to the proxy rather than the CLRIE dll. This enables the proxy to conduct its versioning checks. However, the CLRIE dll should still be its own profiler and can also be pointed to by COR_PROFILER for testing purposes. This also maintains the current behavior of the App Service preinstalled site extension where specific versions can be configured rather than “latest”.

Considerations

Since the CLRIE proxy only updates to new versions on process restart, multi-instance environments may run the risk of having conflicting CLRIE versions running at the same time. This may not be an issue since new profilers would update the environment variables and restart the process to get picked up.

Linux could use /urs/lib/ as its “common location” folder like %ProgramFiles% on Windows. For Snapshot Debugger AKS scenarios (on Linux docker containers), CLRIE is in /diag/Instrumentation64 and is currently not versioned.

The “Bring your own profiler scenario” is where users can deploy a profiler alongside their app. This scenario usually implies one profiler is running, however with CLRIE it may be possible to deploy multiple profilers that run on CLRIE. One solution would be to expose nuget packages of the dlls and provide guidance to both profiler authors and users on how to enable CLRIE in a cooperative way.

WAD is our Azure VM/VMSS extension that hosts CLRIE inside c:/packages/plugins//InstrumentationEngine. How should we cooperate with MSI?

• If WAD looks at self and then program files, this is broken for product B that looks at self and may not know WAD has a newer version. We need a full cooperation model.
• Solution 1: WAD uses MSI
  • Currently setting up a meeting with the WAD engineering team.
• Solution 2: Use Registry solution and copy files program files
  • This can break if the same version MSI gets installed. The component ref count rules only know about MSI, not WAD so uninstalling MSI may break WAD. Fix this by creating a version only release for WAD.

from clrinstrumentationengine.

#68

from clrinstrumentationengine.