View on GitHub

nrconfig

Tool to automate generation of New Relic custom instrumentation XML files for .NET projects

Download this project as a .zip file Download this project as a tar.gz file

Overview

nrconfig is a command-line tool intended to support creating and maintaining custom instrumentation files for use by New Relic.

Note I'm not affiliated with New Relic, Inc beyond being a happy customer of theirs and this tool is in no way endorsed or sanctioned by them. If there are issues with the tool or questions about the source, come to me and not their (lovely) support team as they'll not know what you're talking about.

Availability

Quickstart from NuGet

Generating automatically, via an MSBuild task

Grab the NRConfig.MSBuild NuGet package for each of the projects you wish to instrument and the project that you intend to deploy.

PM> install-package NRConfig.MSBuild

This adds a custom MSBuild task that will generate custom instrumentation configuration files for each project it's added to, before merging the outputs of other projects leaving you with a single CustomInstrumentation.xml file in your project's output folder.

The MSBuild package also includes the NRConfig.Tool package, so you can run the tool manually on any other projects or assemblies you wish (like framework assemblies or dependencies for which you don't have source).

Mark up types that you want to be instrumented with the [Instrument] attribute (more information below), or whole assemblies by applying the attribute at the assembly level.

Manually, using the nrconfig.exe tool

Instead of using MSBuild, you can also just grab the NRConfig.Tool NuGet package:

PM> install-package NRConfig.Tool

This will make the nrconfig.exe command available to your post-build steps for all projects in your solution. Next step's up to you - if you want fine-grained control of which methods get instrumented, also grab the NRConfig.Library NuGet package for each project you want to instrument:

PM> install-package NRConfig.Library

Then mark up your classes or methods with [NRConfig.Instrument] attributes before adding a post-build step for your project:

$(SolutionDir)packages\NRConfig.Tool.1.3.0.0\tools\nrconfig.exe /f all /i $(TargetPath) /o $(TargetDir)$(TargetName).NewRelic.xml

Don't need fine-grained control?

If you don't need method-level specificity, you can use the /f flag in the post-build step (flags are described below).

For example, you can request that all public methods be instrumented:

$(SolutionDir)packages\NRConfig.Tool.1.3.0.0\tools\nrconfig.exe /f methods+ /i $(TargetPath) /o $(TargetDir)$(TargetName).NewRelic.xml

Usage

Mark up your methods for fine-grained control

If you want to instrument specific methods or all of the methods within specific classes then the best approach is to mark them up with Instrument attributes.

Note See the Limitations section at the end for important caveats about this approach.

nrconfig /i *.dll

Generate instrumentation files for unadorned assemblies

If you can't or don't want to change your code, or want to quickly get a baseline instrumentation configuration file that you can then tweak manually then you can use the /f flag.

nrconfig /i *.dll /f [filters]

where [filters] is one or more of:

separated by spaces, and where each of those can be followed immediately by a + or - to limit processing to public or non-public targets only. So, to instrument all public methods and properties in any class in an assembly:

nrconfig /i MyAssembly.dll /f methods+ properties+

while to instrument all methods, whether public or private:

nrconfig /i MyAssembly.dll /f methods+-

Instrumentation file generation can be slow, especially on large assemblies, so it's recommended that you manually run nrconfig.exe on dependencies as required rather than have instrumentation for them generated on each build.

Merge multiple configuration files

The filter format is pretty basic, and you might want to use different filters for different assemblies. You can do that by running nrconfig multiple times with different output files specified, then merge them with the /m flag:

REM Instrument all methods in FirstAssembly, 
REM and public ones in SecondAssembly
nrconfig /i FirstAssembly.dll /f methods+- /o FirstAssembly.NewRelic.xml
nrconfig /i SecondAssembly.dll /f methods+ /o SecondAssembly.NewRelic.xml

REM Merge the two files
nrconfig /m /i *.NewRelic.xml /o MergedInstrumentation.xml

Options

/i <file_1> [file_2] ... [file_n]

Specifies the input files to be processed. These can either be specific paths, include wildcard strings in the filename portion or include environment variables.

If used in conjunction with the /m switch the files specified by /i must be XML documents previously generated by nrconfig.

/o <outputpath>

Specifies the output filename. If /o isn't specified, a file called CustomInstrumentation.xml will be generated in the current directory.

/f <filter1> [filter2]

Specifies that all methods, constructors and properties matched by the filters should be instrumented even if they haven't been annotated by [Instrument] attributes. Each filter must be from the set:

and each can be immediately followed by + or - (or both) signifying public or non-public respectively. If neither + nor - is specified, + is assumed.

/w <typename_1> ... [typename_n]

Specifies that only types whose full names match those specified should be included - only used in conjunction with /f flag. Supports wildcards, for example:

/m

Merges input instrumentation files into a single output file.

/v

Verbose mode, shows a little more diagnostic information during the run.

/debug

Extra-verbose mode, generates a lot of console output but useful if you're about to report a bug.

Limitations

There are a few quirks of the output to deal with issues around New Relic's profiler and its handling of generics:

Licence

nrconfig is licensed under the BSD 3-Clause Licence:

Copyright (c) 2013, Paul O'Neill, pablissimo.com All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.