Collect raw metric information from a custom metric connector instance

You can customize a pull metric connector to collect raw metric information from an external source.

The process of collecting raw metric information from a custom metric connector instance is:
  • Create a custom metric connector script to collect raw metric information.
  • Add the custom metric connector script to a new Event Management connector definition in the JavaScript to run field. The connector definition uses the script to enable the MID Server to connect to the external server to obtain metric raw data.
  • Define a custom metric connector instance. The custom connector definition is specified in this connector instance.
  • The Event Management - Connector execution job job executes all connectors in “running mode” and sends a message to the MID Server on the ECC queue.
  • The MID Server executes the custom metric connector script.
  • The custom metric connector script collects raw metric information that it adds to be processed on the MID Server.
  • The custom metric connector script returns results to the instance.
  • The Event Management – Connector business rule on the ecc_queue table updates the custom metric connector instance with the results, such as, status, error, and signature.

The custom metric connector script must:

  • Be written in JavaScript.
  • In the connector definition, be specified in the JavaScript to run field.
  • Include the retrieveKpi() method. The connector framework uses the retrieveKpi() method to collect metrics. In this method, include the logic for reading data from the external source system and transform to the RawMetric object (in ServiceNow format).
  • Read the required connector instance parameters defined in the probe object.
  • Collect raw metric data from the metric source.
  • Prepare a RawMetric record. The RawMetric object can be created by passing these attributes in the constructor:
    Table 1. RawMetric record description
    Element Description
    metricType Name of the metric.
    metricTypeId SysId of the metric, if available. Otherwise pass the value null
    resource Information about the resource for which metric data is being collected.
    node IP, FQDN, name of the CI, or host. For example, the name of the Linux server where the disks are installed.
    ci SysId of the CI if available. Otherwise use the provided information as part of ciIdentifier for the binding.
    value Value of the metric.
    timestamp Epoch timestamp of the metric in milliseconds.
    ciIdentifier List of key-value pairs to identify the CI.
    source Data source that is monitoring the metric type.
    sourceInstance Source instance.
    monitoredObjType Monitored Object Type
  • Use the handleMetric function to add the raw metric information from the RawMetric record to be processed in the MID Server. To get access to the MetricHandle object, make the following call to the MetricFactory:

    var metricHandler = MetricFactory.getMetricHandler()

    Then for each RawMetric object execute:

    metricHandler.handleMetric(rawMetric)

  • Write error logs to the MID Server log using ms.log. You can use the debugLog() function in the MetricCollector script as an example to write debug messages.
    Note: You can use the MetricCollector MID Server script include that is provided in the base instance as an example for these items.
The custom script should return this data:
Element Description
Status Success or Failure
error_message

(This element displays only if the status is Failure)

Error Message
last_kpi_signature last metric time in milliseconds

This instruction is used for the next query to start from this time. Use any signature that you want to save to retrieve the next metric. This value is updated according to the metric collector Last signature field.

metric_source Your source
metric_count Count of retrieved metrics
metric_duration Duration time of the retrieve metrics process in milliseconds

Test connector requirements - Implement the testConnection() function. The function returns either Success or Failure. If Failure, check the writeError() function for a failure message. You can also check the sa_performance_statistics table to see that metrics are being received. For an example of test connector script, see the SolarWindsJS Mid Server script include.

Metric types that the connector collects:
  • Use set active: true/false to define the types you want to collect.
  • In the metric collector script use HandleTypes.getActiveTypesForSql("Your Source"): for a comma-separated list of supported types. If the type is not active, the type is not returned. If the metric source is in registration mode, not type is retrieved. In registration mode, all types are collected to be able to add any missing types.
  • You can collect all metrics types. The metricHandler.handleMetric() function filters the types that are collected. However, using only active types in the query commands should improve performance.