Cooperative Distribution Model Requirements

[WilliamXieMSFT]

Overview

The CLR Instrumentation Engine's main purpose is to provide cooperation among profilers running in the same environment. This requires various users to cooperatively ensure that the latest version of the Engine can be detected and loaded into the process.

To achieve this goal, we are asking each partner team to participate and provide their needs and requirements for their scenarios. Once we have enough information, we can discuss distribution solutions that can hopefully meet everyone's needs.

Distribution Steps

The distribution story for the Engine can be described through a series of steps.

1. Detect if the Instrumentation Engine is installed.
2. Detect if the Instrumentation Engine is configured.
3. Install the Instrumentation Engine.
4. Configure/activate the Instrumentation Engine.

Requirements

These are the currently identified requirements we expect for the Engine distribution. Please let us know if you have feedback or conflicts with these requirements and reply with your responses to these questions about your product.

• Support single well-known installation folder to easily detect if installed.
• Support updating the Engine via side-by-side versions to avoid file locks on older versions.
• Support determining latest version so profiler clients can detect if it meets their minimum requirements. The Engine is required to be forward compatible
• Setting Environment Variables in a consistent and well-known manner.
• Support ASP.NET Desktop apps on Windows and ASP.NET Core apps on both Windows and Linux.
• Don't require clean-up of older versions. The feasibility of this is dependent on the installation technologies and techniques.
• Have a validation mechanism against the installation

Questions

• What are the installation technologies you are currently using (eg. MSI, Exe bundles, xcopy, scripts)? Please differentiate between different platforms.
• What are the minimum requirements on your target platform?
  • Windows versions & skus
  • Linux distros & versions
  • Framework requirements (.Net Framework/Core versions)
  • Supported application types (ASP.NET on IIS, WPF, etc.)
• Is installation expected or allowed to run with admin privileges (ie. be able to install into %programfiles%)? Do you require installing to a non-admin accessible folder?

Possible Solutions

There may be multiple solutions, but the two options we have considered internally are:

1. MSI and/or a MergedModule for Windows platform

Each partner team has mentioned using an MSI for Windows to install their product. MSI has the benefit of supporting the above requirements.

If we go this route, there are several implementation details to consider:

• Share at the component level or chain in our MSI
• Custom actions for detection
• Per-user versus per-machine installation
• 1 MSI per version

2. Installation Scripts

There are several options for scripting languages, including Python, Bash, and PowerShell which allow for cross platform support and customizable control over installation. This also allows for use of various packaging frameworks such as NuGet or distro-specific options like apk, deb files. Several concerns about this option:

• Ability for MSIs or existing distribution technologies to incorporate this into their installation.
• Introducing new requirements (eg. dotnet core 2.1 for PS Core)

[WilliamXieMSFT]

Visual Studio Snapshot Debugger

We target ASP.NET (Desktop & Core) applications across several Azure platforms.

Windows

• Supported on Azure platforms: AppService, VM, VM ScaleSet
• Supported OS: Windows Server 2012 R2 or Windows Client 8.1
• Installation Technologies: We provide the InstrumentationEngine and SnapshotDebugger directly on the platform.
• Installation Folder:
  • VM/SS: %SystemDrive%\Packages\Microsoft.Azure.Diagnostics.IaaSDiagnostics\
  • AppService: %ProgramFiles(x86)%\SiteExtensions\
• Activation:
  • VM/SS: Update registry to apply environment variables for the WAS and W3SVC services
  • AppService: Application Settings enabled the preinstalled site extension's applicationHost.xdt file
• Minimum Requirements: .NET Framework 4.6.1 & .NET Core 2.0

Linux

• Supported on Azure platforms: Azure Kubernetes Service (AKS)
• Supported distros: Alpine, Ubuntu (Bionic Beaver), Debian (Stretch Slim)
• Installation Technologies: DockerFiles pull bits from tarball (examples at https://github.com/Microsoft/vssnapshotdebugger-docker)
• Installation folder: ~\diag\
• Activation: apply the environment variables with ENV statements
• Minimum Requirements: .NET Core 2.2

[SergeyKanzhelev]

Does this issue covers adding instrumentation methods? Let's say one identified that Instrumentation Engine installed - how to add and remove new action safely?

From Application Insights - the big requirement is to be able to detect that Instrumentation Engine was enabled and check it's version from inside the process by SDK. Currently it's implemented by replacing the body of any method called Microsoft.Diagnostics.Instrumentation.Extensions.Base.NativeMethods.IsAttached and Microsoft.Diagnostics.Instrumentation.Extensions.Base.NativeMethods.GetAgentVersion

https://github.com/Microsoft/CLRInstrumentationEngine/blob/0807cc84afec64f95b7fc5350331f1f8c7759efc/src/Extensions.BaseLib/HostExtensionBase.cpp#L108-L130

[DanFiedler]

Contrast Security .NET Agent

We primarily target ASP.NET web applications across several different hosting environments. We currently support:

• IIS
• IIS-Express
• Azure App Service
• ASP.NET Core

Windows (IIS and IIS-Express)

• Installation:
  • WiX x86/x64 MSIs bundled in a single bootstrap executable
  • Installer requires admin privileges
  • Installs to %ProgramFiles%\Contrast\dotnet\ but can also be configured at install time.
  • Uses %ProgramData%\Contrast\dotnet\ for configuration and logging
• Requirements:
  • .NET 4.5.1+ be installed but applications to be instrumented can target .NET 3.5 or .NET
  • OS: Windows Server 2008 R2+, Windows 7+
• Activation:
  • IIS:
  • Default: Background service updates registry to apply environment variables for the WAS and W3SVC services
  • Chaining: Adds a new IIS native module to manipulate environment before CLR profiler is initialized to allow chaining of one additional profiler.
  • IIS-Express: product offers a UI element to set environment variables for the current user

Azure App Service

• Installation:
  • Nuget Package: x86/x64 .dlls and managed assemblies. Installs to {ApplicationDirectory}\Contrast\dotnet\
  • Azure App Service Site Extension: Site Extension pulls down Nuget package to install. Installs to D:\home\SiteExtensions\
• Activation:
  • Nuget Package: user manually sets environment variables
  • Site Extension: enabled via the site extension's applicationHost.xdt file

.NET Core

• Installation: zip archive that can be unzipped anywhere on the target machine
• Requirements: Windows only at this time, .NET Core 2.1
• Activation user manually sets environment variables or edits launch settings

Future

In the next few months, we will be adding support for:

• Self-hosted WCF Applications
• Self-hosted Web API and OWIN Applications
• Desktop Applications
• ASP.NET Core on Linux

[lucaspimentel]

Datadog - .NET Tracer for APM (repo | docs)

Installation technologies:

• Windows: msi (separate x64 and x86)
• Linux: rpm, deb, and tar (x64 only)

Installation is expected to run with admin privileges (i.e. able to install into %ProgramFiles%). Installation into non-admin accessible folder is not required.

Minimum requirements are mostly the same as for .NET Core 2.1, minus Windows Server Nano.

Framework requirements:

• .NET Framework 4.5+
• .NET Core 2.1+

Supported application types:

• ASP.NET on IIS (Web Forms, MVC, Web API)
• ASP.NET Core
• Windows Services
• Command line

Activation:

• IIS on Windows: msi adds environment variables for WAS/W3SVC to registry
• manually added environment variables for all other scenarios (e.g. registry for Windows Services, scripts for command-line apps, ENV statements for containers)

Future:

• Azure App Services
• self-hosted WCF / Web API / OWIN

edit: links to repo and docs in header

[bobuva]

ShiftLeft .NET Microagent

Installation

• PowerShell script, requiring administrative privileges, installs the agent.
• A separate downloaded command-line program that performs many other functions, and is cross-platform, is used to download and execute the PowerShell script.
• We are in an early stage where only .NET Desktop (running on Windows) is supported. We will also be supporting .NET Core on Windows, Mac OS and Linux flavors. The PowerShell scripts are intended to be run in all environments.

Requirements

• .NET 4.5 or later
• .NET Core 2.1 or later

Application Environments

• ASP.NET on IIS
• ASP.NET Core
• Any other .NET processes, including Windows Services and command-line apps

Activation

• Environment variables for IIS-based applications (Windows registry)
• Environment variables can be set system-wide or on the command-line for non-IIS-based apps.

[WilliamXieMSFT]

Thank you everyone for providing your responses, and I apologize for the long delay; this month I was finally able to reprioritize my work on the Instrumentation Engine and provide some updates.

To aid in distribution on Windows, we plan to ship MSI and MSM packages of the engine. This should align with everyone's current distribution; you can either install the MSI directly via script or user instruction, incorporate the MSI in an MSI bundle with your existing installer, or consume the MSM module package into your MSI. The MSM and MSI share the same components so they will not conflict with each other.

In addition, I will be providing a roadmap and track our upcoming work on this repo to provide you transparency into this process. As always, feel free to provide feedback on here or reach out to us directly via email at clrieowners@microsoft.com.

Thanks! William

[bobuva]

Thanks William!

[WilliamXieMSFT]

Reopening issue to allow individuals to post new feedback/requirements