Create a metric class - Crosswork Network Controller 7.1 APIs

{"type":"api","title":"Create a metric class","meta":{"id":"/apps/pubhub/media/crosswork-network-controller-7-1/f445c17e25a1120e8fbde4bd413083d0fd88b2b3/42552ab7-d679-37b0-afe0-7313ad2e8c01","info":{"title":"Service Health Heuristic Packages APIs","description":"APIs for requesting rule and metric data stored by the Crosswork Service Health application.","termsOfService":"terms-of-service","contact":{"name":"Crosswork Team, Cisco","email":"support@cisco.com"},"license":{"name":"Cisco Software License Agreement","url":"http://www.cisco.com/public/sw-license-agreement.html"},"version":"7.1.0"},"security":[{"bearerAuth":[]}],"x-parser-conf":{"overview":{"markdownPath":"reference/ServiceHealth/sh_heuristic_packages_overview.md"}},"openapi":"3.0.1","servers":[{"url":"/crosswork/aa/hpmgr"}],"securitySchemes":{"bearerAuth":{"type":"apiKey","description":"Security token for authorizing requests for these APIs.","name":"Authorization","in":"header"}}},"spec":{"tags":["AaHeuristicPackage"],"summary":"Create a metric class.","operationId":"AaHeuristicPackage_CreateMetricClass","requestBody":{"description":"The MetricClass parameter.","content":{"application/json":{"schema":{"type":"object","description":"MetricClass","properties":{"id":{"description":"ID of the MetricClass","type":"string"},"name":{"description":"Name of the MetricClass","type":"string"},"namespace":{"description":"Namespace to which MetricClass belongs","type":"string"},"description":{"type":"string","description":"Description of the MetricClass"},"display_label":{"description":"This display label shall be used as the 24hr Metric Chart label","type":"string"},"parameters":{"description":"Parameter defines the param and the corresponding description.","type":"object","additionalProperties":{"type":"object","description":"Metric class param","properties":{"description":{"type":"string","description":"Description of Metric class param"}},"$$ref":"#/components/schemas/MetricClassParam"}},"m_type":{"type":"object","properties":{"string_t":{"type":"object","properties":{"if_empty":{"type":"string","description":"if_empty: optional. The value to be associated to the metric if it returns an empty value. It is useful when no value is interesting information by itself, but it doesn't make sense for all metrics. If not empty then the value of this field shall be assigned as the default value for this metric."},"output_values":{"type":"array","description":"If the device feed is of the enum type, then they are converted to corresponding string values.\nThe expression enum { init, start, end } ==\u003e translates to string literals: 'init', 'start', 'end'. This field can be left empty, which makes it optional. If it is empty, the Service Health application will take all the values from the mapping field at face value and perform no validations. If this field is not empty, Service Health will check and validate whether all the values specified in the mapping are a subset of this list.","items":{"type":"string"}}},"description":"output_values: What values does this metric return? In case of list type: The possible values for each list element.","$$ref":"#/components/schemas/MetricClassStringType"},"bool_t":{"type":"object","description":"Metric calls Bool type","properties":{"if_empty":{"type":"string","description":"if_empty: optional. The value to be associated to the metric if it returns an empty value. It is useful when no value is interesting information by itself, but it doesn't make sense for all metrics. If the value is not empty, then the boolean equivalent value of this field shall be assigned as the default value for this metric. This field is intentionally not defined as of bool type, in order to distinguish it from the cases where the absence of a value is expected to be reported as a monitoring failure. Valid values to assign to this field are 'true' or 'false' only. Any other value will be treated as invalid."}},"$$ref":"#/components/schemas/MetricClassBoolType"},"int_t":{"type":"object","description":"Metric calls Int type","properties":{"if_empty":{"type":"string","description":"if_empty: optional. The value to be associated to the metric if it returns an empty value. It is useful when no value is interesting information by itself but it doesn't make sense for all metrics. If the value is not empty then the value of this field shall be assigned as the default value for this metric."},"output_values":{"type":"array","description":"Use this only when there are small number of discrete integer values. If the full range is needed or the set is too large to specify in the metric definition, then leave it as zero.","items":{"type":"string","format":"int64"}}},"$$ref":"#/components/schemas/MetricClassIntType"},"float_t":{"description":"Float types are used by counters. Hence they don't require constructs like 'if_empty' and 'output_values'.","type":"number","format":"float"}},"description":"The given metric can be of list (or non-list) of type bool, string, integer or float.","$$ref":"#/components/schemas/MetricClassMType"},"m_list":{"type":"boolean","description":"MList for MetricClass."},"cadence":{"description":"Polling frequency (in seconds) for this metric. The default cadence is 30sec. Any value less than or equal to 30 shall be defaulted to 30sec.","type":"integer","format":"int64"},"implementations":{"description":"The metric mplementation can be CLI, SNMP or MDT, along with their precedence.","type":"object","additionalProperties":{"type":"object","description":"Metric Class instance","properties":{"MDTMetric":{"type":"object","properties":{"sensor_path_exact":{"description":"Exact YANG path of the subtree to get the current metric.\n Examples:\n * `openconfig-interfaces:interfaces/interface[name=GigabitEthernet0/0/0/2]/\n subinterfaces/subinterface[index=600]/state/admin-status`\n (subtree of one node) the administrative status of subinterface 600 of interface GigabitEthernet0/0/0/2\n * `openconfig-interfaces:interfaces/interface[name=tunnel-ip13]/state/counters`\n (subtree of height one) all counters of interface tunne-ip13\n * `openconfig-interfaces:interfaces/interface[name=tunnel-ip13]/state/counters/in-errors`\n (subtree of one node) the number of input errors on ineterface tunnel-ip13","type":"string"},"sensor_path_config":{"description":"Longest prefix for which the target router will actually return some value when configured.\n Example: configuring the sensor path on a IOS-XRV router\n `openconfig-interfaces:interfaces/interface[name=tunnel-ip13]/state/counters/in-errors`\n will not work (not resolved). However, configuring the sensor path\n `openconfig-interfaces:interfaces/interface[name=tunnel-ip13]/state/counters`\n will return a bag contaning the wanted value. The pipeline would then retrieve the specific leaf under this subtree (in this case, the value of `in-errors`) and assign it to the metric.\nIn Crosswork, there is a limitation on the number of collection jobs that can be supported. Currently, the limit is about 1000 jobs. Because of this, Service Health needs to subscribe at the gather path level and perform filtering on the resultant metric bag to get to the desired leaf that corresponds to the given metric.\nHence, for all deployment purposes, this field should be set to a valid gather path. In the current example, that would be `openconfig-interfaces:interfaces/interface`.","type":"string"}},"description":"Metric collected using telemetry plugin.","$$ref":"#/components/schemas/MetricImplMdtMetric"},"SNMPMetric":{"type":"object","description":"Metric Impl SNMP metric","properties":{"oid_path_config":{"type":"string","description":"OID path config"},"oid_path_exact":{"type":"string","description":"OID path exact"}},"$$ref":"#/components/schemas/MetricImplSnmpMetric"},"GNMIMetric":{"type":"object","description":"Metric Impl gNMI metric","properties":{"sensor_path_exact":{"description":"MDT corresponding comments apply to below gNMI fields","type":"string"},"sensor_path_config":{"type":"string","description":"Sensor path config"},"origin":{"description":"Specifies the metric origin if it is different from the YANG module. For IOS-XE, the origin needs to be specified as \"rfc7951\".\nFor XR, this field can be left empty.\nWhen this field is left empty, Service Health will attempt to extract the YANG module name from the sensor path and use the module name as the value for the origin.","type":"string"}},"$$ref":"#/components/schemas/MetricImplGnmiMetric"},"GNMITemplateMetric":{"type":"object","properties":{"sensor_path_exact":{"type":"string","description":"Sensor path exact"},"sensor_path_config":{"type":"string","description":"Sensor path config"},"sensor_path_device_feed":{"type":"string","description":"Sensor path device feed"},"origin":{"description":"Specifies the metric origin if it is different from the YANG module. For IOS-XE, the origin needs to be specified as \"rfc7951\".\nFor XR, this field can be left empty.\nWhen this field is left empty, Service Health will attempt to extract the YANG module name from the sensor path and use the module name as the value for the origin.","type":"string"}},"description":"\"GNMITemplateMetric\": {\n \"sensor_path_exact\": \"Cisco-IOS-XR-ipv4-bgp-oper:bgp/instances/instance/instance-active/vrfs/vrf[vrf-name={vrf}]/sessions/session[neighbor-address={neighbor-ip}]/connection-state\",\n \"sensor_path_config\" : \"Cisco-IOS-XR-ipv4-bgp-oper:bgp/instances/instance/instance-active/vrfs/vrf[vrf-name={vrf}]/sessions/session[neighbor-address={neighbor-ip}]/connection-state\"\n \"sensor_path_device_feed\": \"Cisco-IOS-XR-ipv4-bgp-oper:bgp/instances/instance/instance-active/vrfs/vrf[vrf-name={vrf}]/sessions/session\"\n }","$$ref":"#/components/schemas/MetricImplGnmiTemplateMetric"},"CLITemplateMetric":{"type":"object","properties":{"sensor_path_config":{"type":"string","description":"Sensor path config"},"sensor_path_exact":{"type":"string","description":"Sensor path exact"},"device_package_name":{"type":"string","description":"Device package name"},"function_name":{"type":"string","description":"Function name"}},"description":"\"CLITemplateMetric\": {\n \"sensor_path_config\": \"show cef {prefix}\",\n \"sensor_path_exact\": \"route/next-hop\".\n \"device_package_name\": \"showcefprefix\",\n \"function_name\": \"getCefPrefixInfo\"\n }","$$ref":"#/components/schemas/MetricImplCliTemplateMetric"},"CLIMetric":{"type":"object","properties":{"sensor_path_config":{"type":"string","description":"Sensor path config"},"sensor_path_exact":{"type":"string","description":"Sensor path exact"},"device_package_name":{"type":"string","description":"Device package name"},"function_name":{"type":"string","description":"Function name"}},"description":"The non-parameterized CLI metric.","$$ref":"#/components/schemas/MetricImplCliMetric"},"precedence":{"description":"The higher the value, the higher the precedence","type":"integer","format":"int64"},"convert_args":{"type":"object","description":"Convert arguments","additionalProperties":{"type":"object","properties":{"arg_substitutes":{"type":"array","description":"Argument substitutes","items":{"type":"object","properties":{"from":{"type":"string","description":"Pattern to be replaced"},"to":{"type":"string","description":"Value to be replaced with"}},"description":"The arg_substitutes object identifies each pattern (map key) and the value it is to be replaced with (map value). It performs substitutions in the order in which it identifies the patterns.","$$ref":"#/components/schemas/ArgConversionsArgSubstitutes"}}},"description":"Convert the input argument to this Metric Class instance before substituting its value in the sensor paths and OIDs. These conversions are handy in scenarios like the following. \nLet's assume that the ServiceConfig uses ifName as the argument and its value as 'GigabitEthernet0/0/5 612', but the ifName value in the incoming SNMP feed is 'Gi0/0/5.SI.612'. If the pipeline attempts to find a match using the incoming ifName argument value as is, then the pipeline will not find a matching interface. This is where conversions come into play. The incoming argument value needs to go through some conversions before the resultant value can be used to filter the interface entry of interest from the incoming SNMP feed. \nIn this example scenario, the conversions of interest are:\n - Substitute 'GigabitEthernet' with 'Gi'\n - Substitute ' ' with '.SI.'\nThese conversions effectively transform 'GigabitEthernet0/0/5 612' into 'Gi0/0/5.SI.612'.","$$ref":"#/components/schemas/MetricImplArgConversions"}},"val_mapping":{"type":"object","properties":{"values":{"type":"object","description":"Properties","additionalProperties":{"type":"string","description":"Additional properties"}}},"description":"Maps the result of the metric to a normalized output value. This allows for consistent interpretation across devices\nExample:\n\"value_mapping\": {\n \"values\": {\n \"dest-active\": \"active\",\n \"dest-not-active\": \"not-active\"\n \"1\": \"active\",\n \"2\": \"not-active\"\n \"true\": \"active\"\n \"false\": \"not-active\"\n },\n \"default\": null\n}","$$ref":"#/components/schemas/MetricImplValueMapping"},"device_output_labels":{"type":"array","description":"Device output labels","items":{"type":"string","description":"Items of Device output labels"}},"post_processing_expr":{"type":"string","description":"Post processing expression"},"only_when":{"description":"The only_when condition expresses the condition that needs to be satisfied in order to select a given implementation.\nThe given implementation can have the highest precedence value but if the only_when condition is not satisfied then the respective implementation will not be selected.\nCurrently only below 2 conditions are supported:\n \"AddressFamily({\u003cmetric-param\u003e}) == 'ipv4'\"\n \"AddressFamily({\u003cmetric-param\u003e}) == 'ipv6'\"\nExample, say metric param name is 'peer-ip-addr', then valid only_when expressions are:\n \"AddressFamily({peer-ip-addr}) == 'ipv4'\"\n \"AddressFamily({peer-ip-addr}) == 'ipv6'\". The only_when condition helps abstract out ipv4 vs ipv6 implementation-specific differences, such as the MIB OID or YANG module, and so on.","type":"string"}},"$$ref":"#/components/schemas/MetricImpl"}},"matcher":{"description":"Matcher defines different implementation conditions.","type":"array","items":{"type":"object","description":"Metric class matcher","properties":{"implementation":{"type":"string","description":"Implementation of Metric class matcher"},"not_supported":{"description":"Set this flag to true when a given model/version is not supported for this metric. All unsupported metrics will be treated as a no-op equivalent value in their participating eval expressions.","type":"boolean"},"conditions":{"description":"Map key can be os_model, os_version","type":"object","additionalProperties":{"type":"object","description":"Metric class OS match","properties":{"type":{"description":"Type of match. Can be \"exact_match\" for os_model or \"version_range\" for os_version.","type":"string"},"match":{"description":"List of os_model or os_version to be matched","type":"array","items":{"type":"string","description":"Items of the os_mdoel list"}},"start":{"description":"Example:\na) If a path is valid for all versions starting from \"7.4.1.28I\" and above, then the version_range can be specified as:\n\"os_version\": {\n\"type\": \"version_range\",\n\"start\": \"7.4.1.28I\"\n}\nThe start version specified here is \"inclusive\"\nb) If a path is valid for all versions only up to \"7.4.1.27I\" and below then version_range can be\nspecified as:\n\"os_version\": {\n\"type\": \"version_range\",\n\"end\": \"7.4.1.27I\"\n}\nThe end version specified here is \"inclusive\"\nc) If a path is valid from version \"1.1.1\" to \"1.4.4\" and all in-between versions, then the range can be specified as:\n\"os_version\": {\n\"type\": \"version_range\",\n\"start\": \"1.1.1\"\n\"end\": \"1.4.4\"\n}\nBoth start and end version are \"inclusive\" i.e. start version \u003c= x \u003c= end version\nd) For \"os_version\", if the device version matches any version provided in the list of \"match\", OR if it satisfies the \"start\" and \"end\" version range requirement, then the device version is\nconsidered as a match. Both \"start\" and \"end\" versions are inclusive.\n\"os_version\": {\n\"type\": \"version_range\",\n\"match\": [\n\"6.6\",\n\"6.3\",\n\"6.5\"\n],\n\"start\": \"1.1.1\",\n\"end\": \"2.2.2\"\n}","type":"string"},"end":{"description":"Defines the end of os_version range","type":"string"}},"$$ref":"#/components/schemas/MetricClassOsMatch"}},"address_family":{"description":"Address family will indicate if the IP address is ipv4 or ipv6. If absent, the IP address should be considered ipv4.\n\"address_family\": \"AddressFamily(ipAddress) == ipv4\"\n\"address_family\": \"AddressFamily(ipAddress) == ipv6\".","type":"string"}},"$$ref":"#/components/schemas/MetricClassMatcher"}},"create_timestamp":{"description":"Create timestamp for MetricClass.","type":"string","format":"int64"},"update_timestamp":{"description":"Update timestamp for MetricClass.","type":"string","format":"int64"},"version":{"description":"Current version of the metricClass.","type":"string"}},"$$ref":"#/components/schemas/MetricClass"},"example":{"name":"metric.sr.te.pcc.ipv4.peerstate.all","namespace":"custom","description":"Performance measurements of SR-policy","parameters":{"device":{"description":"Device of interest"}},"m_list":true,"m_type":{"string_t":{"if_empty":"abc","output_values":[]}},"enum_values":["active"],"implementations":{"generic IOS XR":{"GNMIMetric":{"sensor_path_config":"Cisco-IOS-XR-infra-xtc-agent-oper:pcc/peers/peer","sensor_path_exact":"Cisco-IOS-XR-infra-xtc-agent-oper:pcc/peers/peer/state-str"},"precedence":20}},"matcher":[{"implementation":"generic IOS XR","conditions":{"os_model":{"type":"exact_match","match":["CISCO IOS XR"]}}}]}}},"required":true},"responses":{"200":{"description":"OK. The request was successful. The result is contained in the response body.","content":{"application/json":{"schema":{"type":"object","description":"Response for the Heuristic Package Element CRUD.","properties":{"status":{"type":"string","description":"Response status for the Heuristic Package Element CRUD.","default":"RESP_STATUS_UNKNOWN","enum":["RESP_STATUS_UNKNOWN","RESP_STATUS_SUCCESS","RESP_STATUS_ERROR"],"$$ref":"#/components/schemas/HpCrudResponseStatus"},"error_description":{"description":"The reason for the error.","type":"string"},"name":{"description":"The name of the Heuristic Package Element.","type":"string"},"namespace":{"description":"The namespace of the Heuristic Package Element.","type":"string"}},"$$ref":"#/components/schemas/HpCrudResponse"},"example":{"data":[{"status":"RESP_STATUS_SUCCESS","name":"metric.sample","namespace":"custom"}]}}}},"default":{"description":"An empty response.","content":{"application/json":{"schema":{"type":"object","description":"Runtime error","properties":{"error":{"type":"string","description":"Error of Runtime error"},"code":{"type":"integer","description":"Code of Runtime error","format":"int32"},"message":{"type":"string","description":"Message of Runtime error"},"details":{"type":"array","description":"Details of Runtime error","items":{"type":"object","description":"ProtobufAny","properties":{"type_url":{"type":"string","description":"Type-url of ProtobufAny"},"value":{"pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string","description":"Value of ProtobufAny","format":"byte"}},"$$ref":"#/components/schemas/protobufAny"}}},"$$ref":"#/components/schemas/runtimeError"},"example":{"data":[{"status":"RESP_STATUS_SUCCESS"}]}}}}},"x-codegen-request-body-name":"body","__originalOperationId":"AaHeuristicPackage_CreateMetricClass","security":[{"bearerAuth":[]}],"method":"post","path":"/createMetricClass"}}