search

newrelic / nri-perfmon

Windows Perfmon / WMI On-Host Integration for New Relic Infrastructure
Other
14 stars 18 forks source link
infrastructure newrelic nrlabs nrlabs-odp perfmon windows windows-perfmon windows-wmi wmi wmi-query

readme

New Relic Experimental header

nri-perfmon - Windows Perfmon/WMI On-Host Integration for New Relic Infrastructure

This integration is capable of...

Links

Installation

NOTE: If you are installing this integration (not building it from scratch), Download The Latest Release HERE instead of cloning this repo!

Requirements

Option 1: Installer

  1. Unzip nri-perfmon to a temporary location on the host
  2. Run Powershell in "Run As Administrator" mode
  3. In Powershell, change to the directory where you unzipped nri-perfmon.
  4. Run install-windows.ps1, which will place the files in their proper locations and restart the Infra Agent.

Option 2: Manual

  1. Unzip nri-perfmon to a temporary location on the host
  2. Create nri-perfmon under C:\Program Files\New Relic\newrelic-infra\custom-integrations.
  3. Place the following files in C:\Program Files\New Relic\newrelic-infra\custom-integrations\nri-perfmon:
    • nri-perfmon.exe
    • nri-perfmon.exe.config
    • config.json
    • Newtonsoft.Json.dll
    • FluentCommandLineParser.dll
  4. Place nri-perfmon-definition.yml in C:\Program Files\New Relic\newrelic-infra\custom-integrations (ALONGSIDE but NOT IN the nri-perfmon folder)
  5. Place nri-perfmon-config.yml in C:\Program Files\New Relic\newrelic-infra\integrations.d\
  6. Restart the Infra Agent

Usage

Upon installation, nri-perfmon should start reporting to your New Relic account with the default counters defined in config.json. The following configurations are to suit advanced usage patterns, i.e. remote polling and custom counters.

Command-line Arguments

If run at command line without anything, the executable should report JSON results from WMI queries specified in config.json to stdout, and any error messages to stderr. This is useful for testing and debugging your counter/query configuration.

Verbose Logging Mode

Verbose Logging Mode is meant for testing your Counters and seeing if and how they will appear in NRDB. With Verbose Logging Mode enabled, the following occurs:

Because stderr messages arent picked up by the NRI Agent in Windows, it is best to use this mode at command line, like so:

C:\Program Files\New Relic\newrelic-infra\custom-integrations> nri-perfmon\nri-perfmon.exe -v -c C:\path\to\custom_config.json

Configuration Within Infrastructure Agent

To use any of the Command-Line Arguments listed above, edit nri-perfmon-definition.yml and add them as argument lines, like so:

#
# New Relic Infrastructure Perfmon Integration
#
name: com.newrelic.perfmon
description: Perfmon On-Host Integration
protocol_version: 1
os: windows
commands:
  metrics:
    command:
      - .\nri-perfmon\nri-perfmon.exe
      - -i
      - 60000
      - -c
      - custom_config.json
      - -n
      - MyCompName
    prefix: integration/nri-perfmon
    interval: 15

Note: The interval: field at the bottom does need to be there with a number, but it does not change the polling interval. To do that, add -i and <interval_(ms)> as consecutive lines to your command arguments.

Counters

config.json Format

{
  "counterlist": [{
      "provider": "provider_name|PerfCounter",
      "category": "category_name",
      "instance": "(optional) instance_name",
      "counters": [{
          "counter": "*|counter_name"
        },
        {
          "counter": "another_counter_name"
        }
      ]
    },
    {
      "eventname": "(optional, default: 'WMIQueryResult') insights_event_name",
      "query": "the_whole_WMI_Query",
      "querynamespace": "(optional, default: 'root//cimv2') query_namespace",
      "querytype": "(optional, default: 'wmi_query') wmi_query|wmi_eventlistener",
      "counters": [{
          "counter": "counter_name|counter_class.counter_name",
          "attrname": "(optional) attribute_name_in_insights_event",
          "parser": "regex_to_parse_attribute_value"
        },
        {
          "counter": "another_counter_name"
        }
      ]
    }
  ]
}

Simple Queries

For a walkthrough of creating a Simple Query, please see TIPS.md.

Example of usage:

{
  "provider": "ASPNET",
  "category": "ASPNETApplications",
  "counters": [
    {
      "counter": "RequestsTotal"
    }
  ]
}

Performance Counters

If you specify the provider as PerfCounter, it will retrieve the Windows Performance Counter instead of running a WMI query. This can be useful if WMI is returning "all 0's" in a query or the appropriate Performance Counter is easier to find Click here for a good how-to on using Performance Monitor.

Example of usage:

{
  "provider": "PerfCounter",
  "category": "ASP.NET Apps v4.0.30319",
  "counters": [
    {
      "counter": "Requests Total"
    }
  ]
}

Complex Queries & Event Listeners

Example of usage:

{
    "eventname": "HyperV_GuestNetworkAdapter",
    "query": "SELECT InstanceId, DHCPEnabled, DNSServers, IPAddresses FROM Msvm_GuestNetworkAdapterConfiguration",
    "querynamespace": "ROOT\\virtualization\\v2",
    "counters": [{
            "counter": "InstanceId",
            "attrname": "Name",
            "parser": "Microsoft:GuestNetwork\\\\([0-9A-F-]+)\\\\[0-9A-F-]+"
        },
        {
            "counter": "InstanceId",
            "attrname": "AdapterId",
            "parser": "Microsoft:GuestNetwork\\\\[0-9A-F-]+\\\\([0-9A-F-]+)"
        },
        { "counter": "DHCPEnabled" },
        { "counter": "DNSServers" },
        {
            "counter": "IPAddresses",
            "attrName": "IPAddress",
            "parser": "([0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3})"
        },
        { "counter": "IPAddresses" }
    ]
},

Notes:

Release Steps

  1. Build your project for the selected platform:

    • In Visual Studio, under the Build menu, select Configuration Manager.

    • Use Build > Build Solution to build the project for x86/x64.

  2. Create a zip file of the build output:

    • After building the project, open File Explorer and navigate to your project folder.

    • Go to the bin/Release folder (actual directory may differ based on your .NET version).

    • You should see separate output folders for each target platform.

Support

New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub. We encourage you to bring your experiences and questions to the Explorers Hub where our community members collaborate on solutions and new ideas.

Contributing

We encourage your contributions to improve nri-perfmon! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at opensource@newrelic.com.

A note about vulnerabilities

As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.

If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.

License

nri-perfmon is licensed under the Apache 2.0 License.