Create a custom pull metric connector

A custom pull metric connector requires a script, connector definition, and connector instance to retrieve raw metric information from an external source.

Before you begin

Role required: evt_mgmt_admin

Ensure that the ITOM Metric Management plugin is activated.

About this task

The custom metric connector makes remote API calls to an external source to get raw metric data and then write/send that data to the instance (using the handleMetric() function).
Process flow to collect raw metric information from a custom metric connector instance:
  • 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:
Note: You can use the MetricCollector MID Server script include that is provided in the base instance as an example for these items.
  • 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 MetricCollector:

    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.
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.

Procedure

  1. Create a custom MID Server script include. As an example, use the MetricCollector script that is provided with the base instance.
  2. Navigate to MID Server > Script Includes and click New.
  3. In the Name field, specify the name.
  4. Select Active.
  5. In the Script field, enter the custom metric collector script. Use JavaScript to compose this script.
  6. Complete the form as appropriate, and then click Submit.
  7. Configure a dedicated MID Server. For more information, see Configure a MID Server for Operational Metrics.
  8. Navigate to Event Management > Event Connectors (Pull) > Connector Definitions and click New.
    1. In the Name field, specify the name.
    2. Select the Collect metrics option.
    3. Right-click the form header and select Save.
    4. In the JavaScript to run field, select the newly created custom MID Server script file.
  9. In the Connector Parameters area, specify the parameters for all additional information needed for the connector, for example, topics that you want to subscribe to.
  10. In the Connector Definition to MID Server Capabilities area, specify the details of the MID Server. Use a dedicated MID Server with ServiceAnalytics as a supported application, and with the ITOA Metrics capability. For more information, see Configure a MID Server for Operational Metrics.
  11. Complete the form as required, then click Submit.
  12. Navigate to Event Management > Event Connectors (Pull) > Connector Instances and click New.
    Note: Remember to specify values for parameters that you defined.
    1. In the Name field, specify the name.
    2. In the Connector definition field, select the newly created custom metric connector definition.
    3. Select the Metrics collection option.
    4. In the Metrics collection schedule field, specify the number of seconds for the metrics collection schedule job to wait before it repeats.
    5. Right-click the form header and select Save.
    6. Complete the form as required, then click Save.
  13. Click Test Connector to verify the connection between the MID Server and the custom metric connector.
  14. Click Update.

What to do next

  • To confirm or debug the custom metric connector script, use debug printouts to the MID Server log.
  • To monitor incoming events using the custom metric connector instance, navigate to ECC > Queue and filter on ConnectorProbe.