https://github.com/getappmap/appmap-dotnet
Records the execution of .NET programs, to create scenarios in AppMap files
https://github.com/getappmap/appmap-dotnet
Last synced: 12 months ago
JSON representation
Records the execution of .NET programs, to create scenarios in AppMap files
- Host: GitHub
- URL: https://github.com/getappmap/appmap-dotnet
- Owner: getappmap
- License: other
- Created: 2021-02-03T18:34:40.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-07-25T12:40:47.000Z (almost 2 years ago)
- Last Synced: 2025-06-11T14:18:18.162Z (about 1 year ago)
- Language: C++
- Size: 492 KB
- Stars: 11
- Watchers: 3
- Forks: 3
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# AppMap-dotnet
AppMap-dotnet records the execution of .NET code. Note currently only Linux is supported.
## Usage
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:
```sh-session
$ 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 test
```
Note it currently requires libxml2 and libunwind8, you might need to install these two. If libraries are missing it will silently fail to work.
### Details
You need [CLR Instrumentation Engine](https://github.com/microsoft/CLRInstrumentationEngine/)
binary, [config/ProductionBreakpoints_x64.config](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.
## VSTest integration
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.
## Configuration
### Configuration file
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:
```yaml
name: my-project
packages:
- class: MyProject.UtilityClass
exclude: Helper # this excludes MyProject.UtilityClass.Helper
- module: MyProject.Business.dll
- path: /usr/lib/util
```
The 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.
### Environment variables
#### `APPMAP_BASEPATH`
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.
#### `APPMAP_CONFIG`
File path. Allows using a specific config file. By default, `appmap.yml` is searched in the current
directory and its ancestors.
#### `APPMAP_LIST_MODULES`
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.
#### `APPMAP_OUTPUT_DIR`
When instrumenting unit tests, appmaps are written to this directory. Defaults to
`$APPMAP_BASEPATH/tmp/appmap`.
#### `APPMAP_OUTPUT_PATH`
File path. If set, an appmap encompassing the whole execution is saved there on shutdown.
#### `APPMAP_LOG_LEVEL`
Log level, one of `trace`, `debug`, `info`, `warning`, `error`, `critical`, `off`.
Defaults to `info`.
### `APPMAP_RUNTIME_DIR`
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.
## Building
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`.