Metric aggregation configuration reference

  • Release version: Australia
  • Updated July 20, 2026
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Metric aggregation configuration reference

    This reference details the configuration object used in ServiceNow's metric aggregation scripted extension point. It enables customers to define how metrics are aggregated from source Configuration Items (CIs), the aggregation methods applied, and where the resulting calculated metrics are published. This configuration is essential for tailoring metric aggregation jobs to specific CMDB classes and metrics, supporting efficient performance monitoring and resource analysis.

    Show full answer Show less

    Key Features

    • Aggregation Modes: Two modes are supported—hierarchy and flat. The mode determines how source resources are selected and where the aggregated metric is published.
    • Configuration Parameters: Customers specify parameters including:
      • mode: Required; selects aggregation mode.
      • targetCIClass: Required in hierarchy mode; identifies the CMDB class of the parent CI to receive the calculated metric.
      • sourceCIClass: Required; defines the CMDB class of source CIs from which raw metrics are aggregated.
      • sourceMetric: Required; specifies the name of the raw metric collected on source CIs.
      • aggregate: Required; aggregation function such as avg, sum, max, min, count, or p95 applied to source metric values.
      • calculatedMetricName: Required; name of the metric produced and published.
      • unit: Optional; unit label for the calculated metric.
      • level: Optional in hierarchy mode; limits the depth of CMDB relationship traversal to control aggregation scope.
      • rangeStart and rangeEnd: Optional in flat mode; define a contiguous range of source resources by name.
      • filters: Optional in flat mode; array of filter objects to restrict source CIs by field conditions.
      • anchorCiSysId: Required in flat mode; sysid of the anchor CI to which the calculated metric is attached.
    • Filter Object: Defines individual field-based conditions to narrow source CIs. Each filter includes:
      • field: Source CI field name.
      • operator: Comparison operator (e.g., =).
      • value: Value to compare against.

    Practical Application

    ServiceNow customers can use this configuration reference to set up metric aggregation jobs that accurately reflect their CMDB structure and monitoring needs. By selecting the appropriate mode and parameters, customers control how data is collected, aggregated, and reported—facilitating insightful performance metrics for parent or anchor CIs. The inclusion of filters and range selections helps target specific subsets of CIs, ensuring relevant and precise metric calculations.

    The configuration object passed to the metric aggregation scripted extension point defines what to aggregate, how to aggregate it, and where to publish the result. The parameters that apply depend on the aggregation mode.

    Configuration parameters

    Table 1. Metric aggregation configuration parameters
    Parameter Type Applies to mode Required Description
    mode String Both Required Aggregation mode. One of hierarchy or flat. The mode determines how source resources are selected and where the calculated metric is published. See Metric aggregation modes.
    targetCIClass String Hierarchy Required (hierarchy) CMDB class of the parent or target CI that receives the calculated metric, for example cmdb_ci_baseband_unit. The aggregation traverses CMDB relationships downward from each target CI to collect the matching source CIs.
    sourceCIClass String Both Required CMDB class of the source CIs whose raw metric is aggregated, for example cmdb_ci_mobile_cell.
    sourceMetric String Both Required Name of the raw metric collected on the source CIs that is read as input to the aggregation.
    aggregate String Both Required Aggregate function applied to the source metric values. One of avg, sum, max, min, count, or p95.
    calculatedMetricName String Both Required Name of the calculated metric that the aggregation produces and publishes.
    unit String Both Optional Unit label applied to the calculated metric, for example Mbps.
    level Integer Hierarchy Optional Depth limit that bounds how far the CMDB traversal descends from each target CI. Prevents the traversal from following relationships beyond the resources you intend to aggregate.
    rangeStart String Flat Optional Start of a contiguous range of source resources identified by name, for example SIM010. Use with rangeEnd to select source CIs by range.
    rangeEnd String Flat Optional End of the contiguous range of source resources identified by name, for example SIM050.
    filters Array Flat Optional Field filters that restrict the source CIs to those meeting a condition. Each element is an object with field, operator, and value. See Filter object.
    anchorCiSysId String Flat Required (flat) The sys_id of the anchor CI that holds the calculated metric. In flat mode the result is not tied to an existing parent CI, so you specify an anchor CI to hold it.

    Filter object

    Each element of the filters array selects source CIs that meet a single field condition.

    Table 2. Filter object properties
    Property Type Description
    field String Name of the field on the source CI to evaluate, for example operational_status.
    operator String Comparison operator applied to the field, for example =.
    value String Value the field is compared against, for example 1.