Besides Events and Log Entries, Metrics play an essential part as the basis to complete the ITOM AIOps story https://www.servicenow.com/products/it-operations-management/what-is-aiops.html. Metrics ingestion is a process where Operational Intelligence in ServiceNow collects and processes Metrics from various monitored systems to provide actionable insights. You can push metrics to ServiceNow, which is particularly useful when the tool measuring the Metrics offers the option to send them directly. If pushing Metrics is not possible, you can also pull them directly from ServiceNow.
This blog article outlines the steps required to set up and develop a Metric Intelligence Custom Metric Pull Connector. This connector enables the addition of Metrics for CIs into MetricBase. For demonstration, temperature and humidity data for Berlin and Zurich are retrieved from the free weather API https://open-meteo.com.
The first section outlines the prerequisites needed to prepare your instance for pulling metrics from a source via the MID Server. This source could be an API, a database, or any system the MID Server can connect to.
The second section will display the Architecture of the Solution.
The subsequent sections guide you through the steps, from defining the source to visualizing the collected metrics, and provide troubleshooting tips in case the metrics are not loaded correctly.
Prerequisites
- Check on your ServiceNow Instance in the stats.do Module if MetricBase is available.
Activation of MetricBase needs to be done by ServiceNow Support https://www.servicenow.com/docs/bundle/xanadu-servicenow-platform/page/administer/metricbase/concept...
Be aware that MetricBase is not available for personal Developer Instances. - Install the following 2 Plugins to be able to set up a Metric Pull Connector.
- The Installation Status of these Plugins can be checked in the Application Manager on your ServiceNow Instance
- A MID Server is required https://www.servicenow.com/docs/bundle/xanadu-servicenow-platform/page/product/mid-server/concept/mi... which must have Metrics capability enabled.
To activate this capability navigate to the MID Server and select Setup Metric IntelligenceThe Setup is successful if you can see Metrics under Capabilities
Architecture
The architecture of the Custom Metric Pull Connector consists of several key components, which can be categorized into data sources, integration components, data storage, and data consumption layers.
In this example, the OpenMeteo API serves as the data source, providing real-time temperature and humidity readings for two locations in a JSON format. This data is retrieved by the MID Server, which acts as the integration layer, parsing the raw JSON data. After processing, the parsed metrics are sent to the ServiceNow instance for further handling.
Once in ServiceNow, the metrics are stored as time-series data in MetricBase, which functions as the data storage layer. This ensures that the metrics are preserved over time and can be analyzed for trends, historical comparisons, and thresholds.
Finally, the data is consumed in various ways:
- Dashboards: Displaying the metrics in a user-friendly, visual format for monitoring.
- Processes: Leveraging the metrics to trigger automated actions based on predefined thresholds for alerting or monitoring.
This architecture enables seamless integration, efficient data storage, and flexible consumption of metric data to drive both proactive monitoring and reporting.
Another valuable application of Metrics is Metric Intelligence which analyzes past metric data to create statistical models. These models predict expected values with upper and lower limits. It then detects unusual patterns and assigns anomaly scores from 0 to 10. A high score may indicate a risk of service outage for a CI.
The architecture diagram below showcases all the components necessary for Metric Intelligence and their locations within the system. The components within the highlighted square are specifically responsible for calculating the model and detecting anomalies.
Configuration Steps
1 Connector Definition
The Connector Definition is the first step to create a Metric Pull Connector. Define the name of the Collector, the Script the collects Events and Metrics, default Schedules and if the Metrics should be collected or not.
Furthermore you can define the set of parameters that are used for a particular Source. In our example we defined the name of the city, geolocations, debug mode, and connection parameters port and protocol. The values of these parameters are not defined at the Collector Definition level but will be set for every Instance of this Connector separately.
2 SA Metric Type Registration
When creating a Connector Definition a SA Metric Type Registration is created for this Source with the default settings Inactive and false. Not changing these Values can be a reason if Metrics are shipped properly but not appear on the platform.
Set Registration Mode and Type default mode to active if the Source should be able to register new metrics and add them to the MetricBase.
Set Generate Missing CIs to true if new CIs should be generated from incoming metrics.
All these settings can be used to generate the initial set of metrics and CIs and then limit an uncontrolled creation of new metrics and CIs.
3 Connector Instance
Every Instance of a Connector has its own set of Parameter Values. In the example there is an Instance for Berlin and Zurich.
Both Instances use the same HOST IP, Credential, Collection Schedules and are only differing in City Name and geolocations. Additionally, you also need to define which Mid Server is used to establish the connection to the Metric Source.
4 MID Server Script Include
The MID Server Script Include referenced in the Connector Definition is the piece of code that is executed to collect Events or Metrics.
This script has three main functions:
- testConnection: function() { … }
This function is executed when you click on Test Connector in the Connector Instance. This could be a request to a health Endpoint of the API to test if connection in general does work - execute: function() { … }
This function is called when the connector is scheduled to collect Events from a Source. This example solely focuses on Metrics collection. - retrieveKpi: function() { … }
This function is called when the connector is scheduled to collect Metrics. There are helper functions which take care of the Ingestion of the Metrics.
The goal is to get Metrics from the Source, create a Raw Metrics Object from every Metric and let the Metric Handler deal with the Raw Matric.var METRIC_SOURCE_NAME = “OpenMeteo”; var MetricFactory = Packages.com.service_now.metric.MetricFactory; var RawMetric = Packages.com.service_now.metric.model.RawMetric; var metricHandler = MetricFactory.getMetricHandler(); […] retrieveKpi: function() { […] var ciIdentifier = new Packages.java.util.HashMap(); ciIdentifier.put(“node”, “Berlin”); ciIdentifier.put(“entityType”, “EnvironmentalSensor”); var temperatureRawMetric = new RawMetric(“Temperature”, “Berlin”, 4.2, new Date().getTime(), ciIdentifier, METRIC_SOURCE_NAME, “°C”); metricHandler.handleMetric(temperatureRawMetric); […] }For simplification, the request to the API and the parsing of the response is ignored in this code snippet.
The complete JavaScript is attached as a txt File.
Additional important functions
- this.probe.getParameter("host");
This function returns parameters that are define in the Connector Instance. This example returns the Host IP - this.probe.getAdditionalParameter("protocol")
Additional Parameters that were defined can be return with this function. In the example the protocol value is returned
5 Visualization
Once the Metrics are ingested there are different possibilities to display them
- Insight Explorer
This is the easiest way to verify the Metrics. Add a list of CIs, then you can select all Metrics that were loaded for theses CIs with drag and drop. -
Platform Analytics
For nicer dashboards use Platform Analytics.
The first step is to create the Data VisualizationsWhen all Data Visualizations are created add them to a Dashboard
Troubleshooting
In case Metrics are not getting ingested properly there are several places to check
Metric To CI Mappings
All incoming metrics will be visible in the Metric to CI Mappings table.
This list shows which Source delivered which Metric and to which CI it was mapped. You can also elaborate which Event led to the creation of the Metric and CI.
Events
The Events List shows these same Metrics from an Event perspective.
When drilling into a specific Event you see all details that led to the creation of the metric. Especially the Processing Notes section clearly indicates which rule was used to map the metric to a particular CI.
Configuration Items
The Configuration Items List shows all CIs that exist in your ServiceNow Instance. You will find the CIs that were created from the Metrics in this list. If you cannot find your Metrics in MetricBase, this list can be an indication which step of the metric Ingestion could have failed.
Monitoring System Metric Types
Every Metric that was created for all Sources will be enlisted in this list. If you cannot find your Metrics in MetricBase, this list is a further indication which step of the Metric Ingestion might have failed.
3 Comments
