AppMap-dotnet records the execution of .NET code. Note currently only Linux is supported.
A launcher, provided as a dotnet tool, is provided for ease of use;
it automatically configures the runtime environment as explained below.
See details below or just dive in:
$ dotnet tool install -g appland.appmap
$ cd ~/projects/myproject
$ echo "packages: [ class: MyProject ]" > appmap.yml
$ APPMAP_OUTPUT_PATH=/dev/stdout dotnet appmap exec bin/myproject.dll
$ dotnet appmap testNote it currently requires libxml2 and libunwind8, you might need to install these two. If libraries are missing it will silently fail to work.
You need CLR Instrumentation Engine
binary, config/ProductionBreakpoints_x64.config and the built binary from this project.
Put all three files, libInstrumentationEngine.so, ProductionBreakpoints_x64.config and libappmap-instrumentation.so in the same
directory. Set the environment variables (replace opt/appmap-dotnet with the path to the files):
CORECLR_PROFILER={324F817A-7420-4E6D-B3C1-143FBED6D855}
CORECLR_PROFILER_PATH_64=opt/appmap-dotnet/libInstrumentationEngine.so
CORECLR_PROFILER_PATH=opt/appmap-dotnet/libInstrumentationEngine.so
MicrosoftInstrumentationEngine_LogLevel=Error
CORECLR_ENABLE_PROFILING=1
MicrosoftInstrumentationEngine_DisableCodeSignatureValidation=1
MicrosoftInstrumentationEngine_FileLogPath=/dev/stderr
MicrosoftInstrumentationEngine_ConfigPath64_TestMethod=opt/appmap-dotnet/ProductionBreakpoints_x64.config
For convenience a launcher is provided that sets it all up.
When the instrumentation is loaded, VSTest tests are automatically detected and
the runs recorded. The appmaps are written to $APPMAP_OUTPUT_DIR.
When using XUnit, test parallelization is disabled; otherwise the test code interleaves and the appmap make no sense.
Appmap-dotnet instruments only specific code packages; which are these can be configured by
creating an appmap.yml file in the project root directory, for example:
name: my-project
packages:
- class: MyProject.UtilityClass
exclude: Helper # this excludes MyProject.UtilityClass.Helper
- module: MyProject.Business.dll
- path: /usr/lib/utilThe path to the file can be explicitly set in APPMAP_CONFIG environment variable. Otherwise, appmap-dotnet
searches current directory (or APPMAP_BASEPATH if set) and all its ancestors for appmap.yml.
Relative path entries are resolved in APPMAP_BASEPATH or the directory where appmap.yml was found.
Base path; this is where the search for the config file begins and where relative path packages are resolved.
Defaults to where the config file was found, or the current directory.
File path. Allows using a specific config file. By default, appmap.yml is searched in the current
directory and its ancestors.
File path. If set, the list of all module names seen is printed there on shutdown.
On Linux, you can use /dev/stdout or /dev/stderr to dump it to console.
When instrumenting unit tests, appmaps are written to this directory. Defaults to
$APPMAP_BASEPATH/tmp/appmap.
File path. If set, an appmap encompassing the whole execution is saved there on shutdown.
Log level, one of trace, debug, info, warning, error, critical, off.
Defaults to info.
Used by the launcher; directory containing libappmap-instrumentation.so
and libInstrumentationEngine.so. When installed as a tool, the launcher automatically
finds the packaged binaries. This variable is convenient when developing, so
that the launcher picks up the locally compiled libraries.
The repository is pretty self-contained and should build on any Linux with modern cmake and C++ compiler.
You can use scripts/docker-build.sh to build both CLRIE and this instrumentation method in Docker.
On success, out directory will contain all the files needed to use this instrumentation method.
launcher requires dotnet SDK to build; dotnet pack in that directory will build the nuget package,
including the native binaries placed in bin/linux-x64.