Configuring Sonar

Last Updated On October 15, 2018
You are here:

Prerequisites

Sonar v0.2.3 or higher

Overview

Sonar configuration represents the following key abstractions:

  • Input adapters – components for gathering metrics from targets
  • Output adapters – components for sending telemetry to designated metric system.
  • Queries – configuration of request to gather telemetry.
  • Schedules – configuration for executing query for a given input adapter at specified intervals.
  • Arrays – similar to schedule, with exception of specifying reusable set of queries specified in external configuration file.

For increasing reusability, using arrays is preferred method of specifying which metrics should be gathered by input adapters and when. The main benefit of using arrays is easy reuse: one can publish an array on GitHub or other code repository that can be used with standard or custom built adapters. Below sections describe how to configure these abstractions in detail.

Configuration Files

Sonar monitoring agent uses two configuration files: one for application configuration with reference to second file, which is used for telemetry configuration.  The application configuration file Sonard.dll.config – contains application configuration, log settings and path to telemetry configuration as shown below:

Sonard.dll.config
<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="Sonar" type="Infragravity.Sonar.SonarConfigurationSection, Sonar"/>
  </configSections>
  <appSettings>
    <add key="ConfigPath" value="C:/Share/Sonar.config"/>
    <add key="RuntimeType" value="Service"/>
    <add key="LogLevel" value="Information"/>
    <add key="LogPath" value="C:/Share/Sonard.log"/>
    <add key="ExporterPort" value="5000"/>
    <add key="ExporterCacheMilliseconds" value="60000"/>
    <add key="ExporterEnabled" value="true"/>
  </appSettings>
</configuration>

The above settings are described as follows:

  • ConfigPath – path to the metric collection configuration file.
  • RuntimeType – should be set to “Service” to run as windows service or any other value to run as console application.
  • LogLevel – sets logging level.
  • LogPath – specifies path for log file for Sonar daemon running as windows service.
  • ExporterPort – specifies port number to use for exposing metrics to Prometheus.
  • ExporterCacheMilliseconds – specifies how long metric should remain in cache before being removed.
  • ExporterEnabled – indicates that Prometheus exporter endpoint should be hosted by Sonar using port and cache settings described above.
Sonar.config

The below is structure of telemetry configuration file:

<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="Sonar" type="Infragravity.Sonar.SonarConfigurationSection, Sonar"/>
  </configSections>
  <connectionStrings>
    <add name="perfmon" providerName="mspdh" connectionString="." />
    <add name="local" providerName="wsman" connectionString="Server=sonar;" />
    <add name="input-diag" providerName="diagnostics" connectionString="." />
    <add name="influxdb-udp" providerName="output-influxdb-udp" connectionString="Data Source = udp://host:8092;Initial Catalog=sonar;User Id =; Password =; Application Name = default;Max Pool Size=100;Packet Size=1200;Connection Timeout=10;Flush Timeout=10;"/>
  </connectionStrings>
  <Sonar>
    <Runtime scrapeIntervalSeconds="5" skipSSLCheck="true" threads="1"/>
    <InputAdapters>
      <add provider="akumuli-http-receive" type="Infragravity.Sonar.Adapters.Akumuli.Http.InputAdapterFactory,Infragravity.Sonar.Adapters.Akumuli.Http" />
      <add provider="diagnostics" type="Infragravity.Sonar.Adapters.Diagnostics.InputAdapterFactory,Sonar" />    
      <add provider="mssql" type="Infragravity.Sonar.Adapters.SqlServer.SqlServerAdapterFactory,Infragravity.Sonar.Adapters.SqlServer" />        
      <add provider="wsman" type="Infragravity.Sonar.Adapters.WsMan.WsmanAdapterFactory,Sonar" />
      <add provider="mspdh" type="Infragravity.Sonar.Adapters.PerformanceCounter.PerfCounterAdapterFactory,Infragravity.Sonar.Adapters.PerformanceCounter" />
    </InputAdapters>
    <OutputAdapters>
        <add provider="output-akumuli-udp" type="Infragravity.Sonar.Adapters.Akumuli.OutputAdapterFactory,Infragravity.Sonar.Adapters.Akumuli" />
        <add provider="output-influxdb-udp" type="Infragravity.Sonar.Adapters.InfluxDb.Udp.OutputAdapterFactory,Infragravity.Sonar.Adapters.InfluxDb" />
    </OutputAdapters>
    <Arrays>
      <add name="btswin_local" array="mswin-basic.sonar.config" input="perfmon" intervalSeconds="1"/>
      <add name="btswin_evlog" array="mslog-basic.sonar.config" input="local" intervalSeconds="15" output="influxdb-udp" />
    </Arrays>
    <Schedules>
    </Schedules>
    <Servers>
        <add name="sonar" url="http://localhost:5985/wsman" username="" password="" timeoutMilliseconds="1000" authType="Negotiate"/>  
    </Servers>  
    <Queries>
    </Queries>
  </Sonar>
 </configuration>

Arrays

The configuration of array represents combination of queries, adapters for collecting or sending telemetry and schedule interval to execute on periodic basis. Below is configuration of monitoring windows logs with InfluxDb:

mslog-basic.sonar.config
<?xml version="1.0"?>
<configuration>
  <configSections>
    <section name="Sonar" type="Infragravity.Sonar.SonarConfigurationSection, Sonar"/>
  </configSections>
  <Sonar>
     <Schedules/>        
    <Servers/>
    <Queries>
        <add name="ApplicationLog"
            filter="select TimeGenerated,Message,EventCode,ComputerName,SourceName,EventType from Win32_NTLogEvent where TimeGenerated > timeshift(20s) and LogFile='Application' and EventType>0"
            resource="http://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/*" namespace="root\cimv2" timestamp="TimeGenerated">
            <Tags>
                <add name="ComputerName" value="ComputerName"/>
                <add name="SourceName" value="SourceName"/>
            </Tags>
            <Values>
                <add name="EventCode" value="CimType.UInt16" />
                <add name="EventType" value="CimType.UInt8" />
            </Values>
        </add>                          
    </Queries>
  </Sonar>
 </configuration>

In this example, WMI query gathers data from Windows OS Application event log within 20s time window. Note that timestamp attribute specifies explicit value of time from event log record and not being generated automatically. This allows to avoid de-duplication when it is supported in the destination metric system.
Specification of array may contain one or more queries, associated with the same adapter. Thus, all queries related to collecting telemetry from WMI can be combined in one or more arrays.

Input Adapters

All input adapters are defined in dedicated configuration section in InputAdapters section as shown in the above Sonar.config file. The following adapters are supported out of the box:

Details for configuring each input adapter above in Sonar.config telemetry configuration file are included in this documentation. Please note that any input adapter can be added via dependency injection. The examples for Oracle and MySQL with building Docker container are published in our GitLab repository.

Output Adapters

All input adapters are defined in dedicated configuration section in InputAdapters section as shown in the above Sonar.config file. The following adapters are supported out of the box:

  • InfluxDB adapter
  • Akumuli adapter
  • Prometheus adapter

Details for configuring each output adapter above in Sonar.config telemetry configuration file are included in this documentation.

Queries

Sonar monitoring agent supports two query dialects: WQL and Raw. The WQL dialect can be used only when a query or array of queries are configured to use WS-Management input adapter. In contrast, raw query dialect can be used for any input adapter.