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.
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.
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.22.214.171.124\tools\nrconfig.exe /f all /i $(TargetPath) /o $(TargetDir)$(TargetName).NewRelic.xml
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.126.96.36.199\tools\nrconfig.exe /f methods+ /i $(TargetPath) /o $(TargetDir)$(TargetName).NewRelic.xml
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.
- Install the NRConfig.Library or NRConfig.MSBuild NuGet packages into the projects you wish to instrument
- Annotate at the assembly, class or method level with the [Instrument] attribute
- If you're not using the MSBuild package, install the NRConfig.Tool NuGet package and run nrconfig.exe against the assemblies in question
Note See the Limitations section at the end for important caveats about this approach.
nrconfig /i *.dll
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.
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
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.
Specifies the output filename. If /o isn't specified, a file called CustomInstrumentation.xml will be generated in the current directory.
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.
Specifies that only types whose full names match those specified should be included - only used in conjunction with /f flag. Supports wildcards, for example:
- *Repository would match all types whose full name ends with 'Repository'
- System.Web.* would match all types in the System.Web namespace
Merges input instrumentation files into a single output file.
Verbose mode, shows a little more diagnostic information during the run.
Extra-verbose mode, generates a lot of console output but useful if you're about to report a bug.
There are a few quirks of the output to deal with issues around New Relic's profiler and its handling of generics:
- Generic classes aren't supported
- If a method that takes a generic type as a parameter, which itself has more than one type parameter (like Dictionary<string, int>, rather than IEnumerable<string>) then all overloads of that method will be instrumented too even if they aren't configured to be - this works around an issue where methods of this type can't be expressed in the configuration file in a way the profiler will use
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:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of pablissimo.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission
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.