Summary

The Metricly Windows Agent is a Microsoft Windows service that collects, aggregates, and publishes windows performance counters and attributes.

Installation is as easy as executing an MSI installer and configuring the service. The agent is pre-configured to send the most important performance metrics, windows events, and system attributes to Metricly. It can also be configured to send additional or different data if required. See Windows Plugins for more information.

Microsoft SQL Server, IIS, and .NET metrics are native to our Windows Agent. Only one Windows integration in your account is necessary to receive all Windows-related metrics. View the list of metrics here. You can also add custom metrics if the default metrics are not enough.

Troubleshooting & Other Topics

See our Windows Additional Information article for other content on topics.

Installation

We’re constantly improving our Windows agent, so it’s important you upgrade to the latest version whenever possible. Why upgrade? Check out the project page.

To upgrade the Windows agent, repeat the steps in the following sections using the most recent agent version. Make sure to back up all configuration files before upgrading; Existing configuration files are overwritten when the agent is upgraded.


1. Copy the API key 
  1. In Metricly, click Integrations on the top-nav bar.
  2. Search for and click the Windows Server card. The name should be already populated, and Data Collection should be enabled. A unique API key for your account has already been generated.
  3. Copy the API key.

2. Install the Windows Agent

If you install our Windows agent on an AWS EC2 or Azure VM, the EC2’s / VM’s power state (it will come in as the attribute hostRunningwith a value of true or false) and tags are copied over to the corresponding Windows WINSRV element. You can then use this information to create policies.

  1. Download the latest Windows agent from our repo at https://repos.app.netuitive.com/windows-agent/index.html. Ensure you download the correct version for your environment.
  2. Open a command line interface and change to the directory you downloaded the Windows agent to.
  3. Run the following command:
    
    msiexec /quiet /package CollectdWin-x64.msi NETUITIVE_API_KEY=my_api_key

    … where my_api_key is the unique API key generated for your account that you copied in step 1. Windows will install the agent and set the API key in the WriteNetuitive.config file.

If you’d prefer to manually install the agent, see Manually Installing the Windows Agent.


3. Set up a proxy (Optional)

Optionally, if you have a web proxy in your environment, you may need to configure the agent to use it. See Proxy Configuration for more information. You can also optionally update the hostname. Check out the Manually Updating a Hostname section.


4. Start the agent
  1. Open the Windows Service Control Manager.
  2. Select the CollectdWinService.
  3. Start the service.

If the service is already running, you’ll need to restart it for any configuration changes to take effect.

This integration’s package is automatically enabled and provisioned to your account as soon as Metricly receives data from the integration. The PACKAGES button on the integration setup page also becomes active once data is received. You can disable or re-enable this package at will. 

Additional Configuration Options


Windows Plugins

There are two types of Windows plugins: Read (which allow our Windows agent to read data) and Write (which allow our Windows agent to write data). The following plugins are enabled by default:

  • ReadWindowsPerfCounters
  • ReadWindowsAttributes
  • ReadWindowsEvents
  • WriteMetricly

This configuration is recommended for monitoring a Windows server with Metricly. Other Read/Write plugins are available as documented below (note that the Write Console plugin has no configuration settings). To change which plugins are enabled, edit the CollectdWin.config file (located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment).


  • Read Windows Performance Metrics plugin

    This plugin uses the Windows Performance Count component to collect configured metrics. Each performance counter can be mapped to its Collectd equivalent metadata via configuration.

    1. Navigate to the ReadWindowsPerfCounters.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Add as many entries as you desire using the table below.
      Value Required/Optional Description
      ReloadInterval Required The period in seconds before rescanning for new/changed instances (defaults to 3600). This is configured once in the ReadWindowsPerfCounters element.
      Category Required The name of the performance counter category.
      Name Required Comma-separated performance counter names.
      Instance Required This can be set to a specific instance or a regular expression to filter the instances. Some counter categories do not have instances; in this case, this field should be left blank.
      CollectdPlugin Required Collectd plugin name.
      CollectdPluginInstance Required Where the configuration is for a single instance, this value can be used to override the instance name. Where there are multiple instances, this value is automatically set for each instance.
      CollectdType Required Metric type and units. This must be a value in types.db, which can be found in the deployment folder.
      CollectdTypeInstance Required Name for the metric instance.
      Multiplier Optional Float scale factor to be applied to the value.
      DecimalPlaces Optional Integer number of decimal places for rounding.

    Here’s a default entry in the ReadWindowsPerfCounters.config file:

    <Counter Category="Network Interface" 
    Name="Packets Received/Sec,Packets 
    Sent/Sec" Instance="*" 
    CollectdPlugin="interface" 
    CollectdType="if_packets" 
    CollectdTypeInstance="" />
  • Save the file.

Read Windows Event plugin

This plugin reads from the Windows event logs on the server the agent is installed. The Writemetricly plugin will process the values it collects, but no other write plugins are able to do so.

  1. Navigate to the ReadWindowsEvents.config file.
    The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
  2. Add as many entries as you desire using the table below.
    Value Required/Optional Description
    Title Required A descriptive title for the events captured by this configuration entry. This is shown as the event title in Metricly.
    Log Required The windows log (e.g., Application, System, Security).
    Source Required The source of the event (this is the source field in the event viewer). This value can be left blank for any source.
    MinLevel Optional The minimum log level to collect. Defaults to 1. Possible values (in order): 1 = critical, 2 = error, 3 = warning (warn), 4 = information, and 5 = verbose.
    MaxLevel Required The maximum log level to collect. Offers the same levels as the MinLevel setting. Set to the same value as MinLevel to restrict to just one level.
    MinEventId Optional The minimum event ID to collect between 0 and 65535. Defaults to 0.
    MaxEventId Optional The maximum event ID to collect between 0 and 65535. Defaults to 65535. Set to the same as MinEventId to restrict collection to a single event.
    FilterExp Optional A regular expression applied to the log message. Messages that do not match are disregarded.

    Here’s a default entry in the ReadWindowsEvents.config file:

    <Event Title="Error 99 occurred in MyApp" 
    Log="Application" Source="MyApp" 
    MinLevel="2" MaxLevel="2" MinEventId="99" 
    MaxEventId="99" />
  3. Save the file.

  • Read Windows Attribute plugin

    This plugin reads non-numeric attributes of the server. The WriteMetricly plugin will process the values it collects, but no other write plugins are able to do so. Three attributes are available by default:

    Name Description
    os The operating system version.
    cpus The number of CPUs.
    ram bytes Total system RAM.

    If the server is hosted on an AWS EC2 and the ReadEC2InstanceMetadata attribute on the ReadWindowsAttributes element is set to “true”, the plugin will read metadata from the host EC2 instance as attributes (e.g., instanceId, instanceType, etc.) and also record the relationship between the two elements in Metricly.

    Any environment variable can be read as an attribute by adding it to the configuration section:

    1. Navigate to the ReadWindowsAttributes.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Following the format of the other available attributes, add as many attributes as you desire.

      Name is the attribute’s name and Valueis the environment variable name. Here’s a default entry in the ReadWindowsAttributes.config file:

      <EnvironmentVariable Name="architecture" 
      Value="PROCESSOR_ARCHITECTURE"/>
    3. Save the file.

  • Read StatsD Plugin

    The Read StatsD plugin implements the StatsD Network Protocol. It listens on
    a UDP port and receives metrics from applications. The plugin supports four
    event types:

    • Gauges
      • A gauge is an instantaneous measurement of a value. It differs from
        a counter by being calculated at the client rather than the server.

        <metric name>:<value>|g
        

        Counters

        • A counter is a gauge calculated at the server. Metrics sent by the
          client increment or decrement the value of a gauge rather than
          giving its current value. Counters may also have an associated
          sample rate given as a decimal of the number of samples per event
          counter.

          A sample rate of 1/10 would exported as 0.1. Valid counter values
          are in the range (-263, 263).
          <metric name>:<value>|c[|@<sample rate>]
          
    • Timers
      • A timer is a measure of the number of milliseconds elapsed between a
        start and end time.

        <metric name>:<value>|ms
        
    • Sets
      • Unique occurrences of events within an interval.
        uniques:765|s

    Several properties are available by default:

    Name Description
    Statsd.Host Host name for StatsD UDP listener.
    Statsd.Port Port number for StatsD UDP listener.
    DeleteCache.Counters, DeleteCache.Timers, DeleteCache.Gauges,
    DeleteCache.Sets
    This option controls the behavior when metrics are not updated in an
    interval. If set to false, metrics are dispatched unchanged. If set
    to true, metrics are not dispatched and removed from the internal
    cache.
    Timer.Lower, Timer.Upper, Timer.Sum, Timer.Count This option is to enable aggregate functions for timer metrics. If
    enabled for each timer metric, its equivalent aggregate metric is
    also dispatched with appropriate extensions (“-lower”, “-upper”,
    “-sum”, “-count”).
    Percentiles.Percentile Calculate and dispatch the configured percentile, i.e. compute the
    latency so that Percent of all reported timers are smaller than or
    equal to the computed latency. If enabled for each time metric, its
    equivalent percentile metric is also dispatched with appropriate
    extensions (“-percentile-90”, “-percentile-95”). If not configured,
    no percentile is calculated or dispatched.

    To configure the plugin

    1. Navigate to the ReadStatsD.config file.
      The file will be located in 
      C:\Program Files\CollectdWin\config
       or C:\Program Files (x86)\CollectdWin\config depending on
      your environment.
    2. Following the format of the default configuration, manipulate the
      properties as desired.
    3. Save the file.

  • Write Metricly plugin

    This plugin is already configured to send all data gathered by the read plugins to Metricly via its REST API in step 2 of the installation instructions. The following are additional, advanced settings that should only be changed in discussion with Metricly support.

    Name Description
    Url Metricly ingest API URL.
    PayloadSize (Optional) The number of metrics that are batched into a single POST. Set to -1 to send all metrics at once; the default is 25.
    Location (Optional) Sets element location attribute.
    Type (Optional) Overrides the element type in Metricly; the default is WINSRV.

    To configure the file:

    1. Navigate to the WriteMetricly.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Add any of the optional configuration attributes to the line in the file.

      The below example shows a correctly set URL with the API key:

      <WriteMetricly
       Url="https://api.app.metricly.com/ingest/windows/de2b497468d863accb9c402dfff22689"/>
    3. Save the file.

  • Write StatsD plugin

    The Write StatsD plugin posts metrics as UDP datagrams to a StatsD server. The metric buckets follow the naming convention:

    [Prefix].[Hostname].[CollectdPlugin].[CollectdPluginInstance].[
      CollectdTypeInstance]

    Three attributes are available by default:

    Name Description
    Host Statsd hostname.
    Port UDP Port number.
    Prefix (Optional) Optional bucket name prefix.

    To configure the file:

    1. Navigate to the WriteStatsd.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Add any of the optional configuration attributes to the line in the file.
    3. Save the file.

  • Write HTTP plugin

    The Write HTTP plugin works similarly to the collectd Write HTTP plugin. It posts metrics to the target URL in the following JSON format.

    [
          {
            "values": [197141504, 175136768],
        	"dstypes": ["counter", "counter"],
        	"dsnames": ["read", "write"],
        	"time": 1251533299,
        	"interval": 10,
        	"host": "leeloo.lan.home.verplant.org",
        	"plugin": "disk",
        	"plugin_instance": "sda",
        	"type": "disk_octets",
        	"type_instance": ""
          },
          ...
        ]

    To configure the file:

    1. Navigate to the WriteHTTP.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Update the Url attribute to the target URL.
    3. Save the file.

  • Write AMQP plugin

    The Advanced Messaging Queuing Protocol (AMQP) is an open standard application layer protocol for message-oriented middleware. The Write AMQP plugin publishes metrics to the configured message broker in JSON format. Several attributes are available by default:

    Name Description
    Name Name of the AMQP publisher.
    Host Message broker’s host name.
    Port Message broker’s AMQP listening port.
    VirtualHost The name of the “virtual host” (or vhost) that specifies the namespace for entities (exchanges and queues) referred to by the protocol. Virtual hosts provide a way to segregate applications using the same message broker instance.
    User User name for authentication.
    Password Password for authentication.
    Exhange Exchanges are AMQP entities where messages are sent. Exchanges take a message and route it into zero or more queues.
    RoutingKeyPrefix A message sent to a message broker contains a routing key and message body. Routing key contains six fields separated by a period:

    RoutingKeyPrefix.Host.CollectdPlugin.CollectdPluginInstance.CollectdType.CollectdTypeInstance

    To configure the file:

    1. Navigate to the WriteAMQP.config file.
      The file will be located in C:\Program Files\CollectdWin\config or C:\Program Files (x86)\CollectdWin\config depending on your environment.
    2. Add any of the optional configuration attributes to the Publishline in the file.
    3. Save the file.

Proxy Configuration

The Windows agent does not use a proxy by default, but you may need to configure one if you have a proxy enabled in your browser.

Determining if you have a proxy enabled
  1. Open Internet Explorer.
  2. Click the Tools icon, and then click Internet Options.
  3. On the Connections tab, click LAN settings.
    If any of the checkboxes are selected and the appropriate information is filled out, you may need to configure proxy settings to enable data being posted by the agent on your server.

Configuring the proxy
  1. Add the following to the end of the CollectdWinService.exe.configconfiguration file after the <startup> section and before the closing </configuration> tag:
    <system.net>
    <defaultProxy enabled="true" useDefaultCredentials="true">
    <proxy/>
    </defaultProxy>
    </system.net>
    The file will be located in C:\Program Files\CollectdWin or C:\Program Files (x86)\CollectdWindepending on your environment.
  2. Replace the <proxy /> element with one of the options below (corresponding to which option was selected in Internet Explorer).


Proxy Options Examples

More information about proxy settings can be found in the MSDN.


No Proxy
  • Nothing Enabled

    No proxy configured.

Automatically Detect Settings
  • If the Automatically detect settings checkbox was selected, use the following proxy element:

     <system.net>
      <defaultProxy enabled="true" useDefaultCredentials="true">
        <proxy autoDetect="true" />
      </defaultProxy>
    </system.net>

Use automatic configuration script
  • If the Use automatic configuration script checkbox was selected, use the following proxy element:

    <system.net>
          <defaultProxy enabled="true" useDefaultCredentials="true">
            <proxy scriptLocation="http://www.test.com:1234/sampleScript" />
          </defaultProxy>
        </system.net>

    Replace SCRIPT_URI with the content of the Address text box in the LAN settings window.


Use a proxy server for your LAN
  • If the Use a proxy server for your LAN checkbox was selected and the address and port are specified, use the following proxy element:

    <system.net>
        <defaultProxy enabled="true" useDefaultCredentials="true">
          <proxy proxyAddress="http://proxyhost:8088" />
        </defaultProxy>
      </system.net>

    Replace URI_STRING with the address and port settings used (e.g., http://proxyhost:8088). If the address and port are not specified, then the proxy is manually configured on the Advanced screen. Enter the proxy element as above but using the address and port given for the HTTPS protocol.

Dependencies

OS
All editions of Windows 7, 8, 8.1, 10, Windows Server 2012, and Windows Server 2012 R2
The versions of Windows/Windows Server listed above have the required .NET Framework installed. In some cases, the required version of the .NET Framework may be installed but not enabled by default. Other older versions of Windows or Windows Server may work if you can install .NET Framework v. 4.5 or later.
Miscellaneous
Microsoft .NET Framework v. 4.5 or later