LogicMonitor acquires Catchpoint, adding Internet and digital experience insight to LM Envision.

Read more
Platform
Solution
Industry
Role
There is no result.

REST API Advanced Filters

Last updated - 13 December, 2022

LogicMonitor REST API advanced filters are applied to key-value pairs where values are in JSON format. For example, in /device/devices APIs you can apply advanced filters for the keys – autoProperties, inheritedProperties, systemProperties, and customProperties.

This article uses REST API /alert/alerts and /device/devices as examples to explain how you can use advanced filters. 

Note:

  • The advanced filter structure used for /device/devices/ API will not work for /alert/alerts/ API.
  • The json_key_parameter and escaped json_value_parameter will not work for /alert/alerts/ API.
  • The examples used in this support article are samples only and must be modified to suit your business requirements.

    • Structure of Advanced Filters

    The following examples show the structure of advanced filters.

    • Normal query
    {{url}}/<api>?filter=<json_key_parameter>:"{<escaped json_value_parameter>}"&fields=<if any separated by ,>
    • Operator not equal (!:) filter query
    {{url}}/<api>?filter=<json_key_parameter>!:"{<escaped json_value_parameter>}"
    • Operator contains (~) filter query
    {{url}}<api>?filter=<json_key_parameter>~"{<escaped json_value_parameter>}"
    • Operator not contains (!~) filter query
    {{url}}<api>?filter=<json_key_parameter>!~"{<escaped json_value_parameter>}"
    • Operator special_eq (:::) filter query where it checks both null and empty values
    {{url}}<api>?filter=<json_key_parameter>:::empty
    • Operator special_ne (!::) filter query where it checks if the value is not empty or null
    {{url}}<api>?filter=<json_key_parameter>!::empty
    • Operator special_ne (!::) filter query where it checks if the value is not null
    {{url}}<api>?filter=<json_key_parameter>!::null
    • Operator logical OR (||) filter query
    {{url}}<api>?filter=<json_key_parameter_1>:"{<escaped json_value_parameter_1>}" || <json_key_parameter_2>:"{<escaped json_value_parameter_2>}"
    • Single and advanced filter query
    {{url}}<api>?filter=<json_key_parameter>:"{<escaped json_value_parameter>}",<non-json_key_parameter>:<non-json_value_paramter>

    Components of Advanced Filters

    The components of the advanced filter queries are as follows:

    ComponentsDescription with Examples
    {{url}}https://<company>.logicmonitor.com/santaba/rest
    <api>APIs, for example, /device/devices and /device/groups
    <json_key_parameter>In case of /device/devices, values can be autoProperties, inheritedProperties, systemProperties, and customProperties
    {<unescaped json_value_paramter>}For example, {"name":"testPROPERTY","value":"service"}
    {<escaped json_value_parameter>}For example, {\"name\":\"testPROPERTY\",\"value\":\"service\"}
    <non-json_key_parameter>Key whose value is not JSON. For example, id, name, displayName, and so on.
    <non-json_value_paramter>Single values for example, id: 100, “name”: “Instance”
    Here, the non JSON value for id is 100 and for name it is Instance

    Use Case

    You can use advanced filters to get key-value pairs for any property with JSON as the value parameter.

    Device 1 (“id”: 3793) has the following systemProperties.

    { "id": 3793, "name": "sfsf", "systemProperties": [ { "name": "system.enablenetflow", "value": "false" }, { "name": "system.collectorplatform", "value": "n/a" }, { "name": "system.description", "value": "dummy" }, { "name": "system.collectorid", "value": "-4" }, { "name": "system.deviceId", "value": "3793" }, { "name": "system.prefcollectordesc", "value": "Service Data Aggregator" }, { "name": "system.collectordesc", "value": "Service Data Aggregator" }, { "name": "system.deviceGroupId", "value": "1" }, { "name": "system.resourceCreatedOn", "value": "1556854294" }, { "name": "system.devicetype", "value": "6" }, { "name": "system.collectorversion", "value": "0" }, { "name": "system.prefcollectorid", "value": "-4" }, { "name": "system.displayname", "value": "sfsf" }, { "name": "system.hostname", "value": "sfsf" } ] }

    Device 2 (“id”: 3792) has the following systemProperties.

    { "id": 3792, "name": "cc", "systemProperties": [ { "name": "system.enablenetflow", "value": "false" }, { "name": "system.collectorplatform", "value": "n/a" }, { "name": "system.description", "value": "sfsf" }, { "name": "system.collectorid", "value": "-4" }, { "name": "system.deviceId", "value": "3792" }, { "name": "system.prefcollectordesc", "value": "Service Data Aggregator" }, { "name": "system.collectordesc", "value": "Service Data Aggregator" }, { "name": "system.deviceGroupId", "value": "1" }, { "name": "system.resourceCreatedOn", "value": "1556852762" }, { "name": "system.devicetype", "value": "6" }, { "name": "system.collectorversion", "value": "0" }, { "name": "system.prefcollectorid", "value": "-4" }, { "name": "system.displayname", "value": "cc" }, { "name": "system.hostname", "value": "cc" } ] }

    When you run the following basic filter query

    {{url}}/device/devices?filter=systemProperties.name:"system.description",systemProperties.value:"sfsf"

    In the response body this query lists all devices (device 1 and 2) with systemProperties name “system.description” and devices with systemProperties value “sfsf“.

    When you run the following advanced filter query

    {{url}}/device/devices?filter=systemProperties:"{\"name\":\"system.description\",\"value\":\"sfsf\"}"

    In the response body this query lists devices (only device 2) with key-value pair i.e. systemProperties system.description:”sfsf“.

    /device/devices Filter Examples

    The following sections provide examples of the /device/devices filter.

    /device/devices API

    Filter structure:

    {{url}}/device/devices?filter=systemProperties:"{\"name\":\"system.description\",\"value\":\"sfsf\"}"&fields=systemProperties,name,id

    Example:

    https://localdev.logicmonitor.com/santaba/rest/device/devices?filter=systemProperties:"{\"name\":\"system.description\",\"value\":\"sfsf\"}"&fields=systemProperties,name,id

    /device/groups API

    Filter structure:

    {{url}}/device/groups?filter=customProperties:"{\"name\":\"test11\",\"value\":\"test11\"}"

    Example:

    https://localdev.logicmonitor.com/santaba/rest/device/groups?filter=customProperties:"{\"name\":\"test11\",\"value\":\"test11\"}"

    Query Examples

    The following sections provide examples of filter queries.

    systemProperties

    Operator equals (:) filter queries:

    {{url}}/device/devices?filter=systemProperties:"{\"name\":\"system.description\",\"value\":\"sfsf\"}"&fields=systemProperties,name,id

    The response body returns all devices with systemProperties that contain name:system.description AND value:sfsf

    { "total":1, "items":[ { "id":770544, "name":"10.241.242.102", "systemProperties":[ { "name":"system.enablenetflow", "value":"false" }, { "name":"system.collectorplatform", "value":"linux" }, { "name":"system.description", "value":"sfsf" }, { "name":"system.collectorid", "value":"11934" }, { "name":"system.deviceId", "value":"770544" }, { "name":"system.prefcollectordesc", "value":"centos-systemd-1" }, { "name":"system.collectordesc", "value":"centos-systemd-1" }, { "name":"system.groups", "value":"Synthetics_Resource_Group,demo:/dasdas,152_SJ_dy,DeadDeviceGrp,175_SJ_2" }, { "name":"system.deviceGroupId", "value":"56255,103904,23105,21122,142395" }, { "name":"system.resourceCreatedOn", "value":"1652188809" }, { "name":"system.devicetype", "value":"0" }, { "name":"system.collectorversion", "value":"29107" }, { "name":"system.staticgroups", "value":"Synthetics_Resource_Group" }, { "name":"system.prefcollectorid", "value":"11934" }, { "name":"system.displayname", "value":"my test vm" }, { "name":"system.hoststatus", "value":"dead-collector" }, { "name":"system.hostname", "value":"10.241.242.102" } ] } ], "searchId":null, "isMin":false }

    customProperties

    Run the query filter: 

    {{url}}/device/devices?filter=customProperties:"{\"name\":\"testPROPERTY\",\"value\":\"service\"}"&fields=customProperties,name,id

    The response body returns all devices with customProperties that contain name:testPROPERTY AND value:service

    { "total":1, "items":[ { "id":44, "name":"Instance", "customProperties":[ { "name":"testPROPERTY", "value":"service" }, { "name":"same case", "value":"service" }, { "name":"snmp.test", "value":"test" }, { "name":"predef.bizservice.evalMembersInterval", "value":"30" }, { "name":"predef.bizservice.members", "value":"{\"device\":[],\"instance\":[{\"deviceGroupFullPath\":\"jenny/jenny1*\",\"deviceDisplayName\":\"10.131.1.17\",\"deviceProperties\":[],\"dataSourceFullName\":\"jenny_script_time\",\"dataSourceId\":2001791,\"instanceName\":\"*\"}]}" }, { "name":"system.categories", "value":"" } ] } ], "searchId":null, "isMin":false }

    autoProperties

    Run the query filter: 

    {{url}}/device/devices?filter=autoProperties:"{\"name\":\"predef.externalResourceID\",\"value\":\"service_63\"}"&fields=autoProperties,name,id

    The response body returns all devices with autoProperties that contain name:predef.externalResourceID AND value:service_63

    { "total":1, "items":[ { "id":63, "name":"gcp", "autoProperties":[ { "name":"predef.externalResourceID", "value":"service_63" }, { "name":"predef.externalResourceType", "value":"Service" } ] } ], "searchId":null, "isMin":false }

    systemProperties and inheritedProperties

    Run the query filter:

    {{url}}/device/devices?filter=systemProperties:"{\"name\":\"system.displayname\",\"value\":\"qqq1\"}",inheritedProperties:"{\"name\":\"fdfdf\",\"value\":\"121212\"}"

    The response body returns all devices with systemProperties that contain name:system.displayname AND value:qqq1 AND inheritedProperties name:fdfdf AND value:121212

    { "total": 1, "items": [ { "id": 770544, "name": "10.241.242.102", "displayName": "my test vm", "deviceType": 0, "relatedDeviceId": -1, "currentCollectorId": 11934, "preferredCollectorId": 11934, "autoBalancedCollectorGroupId": 0, "preferredCollectorGroupId": 581, "preferredCollectorGroupName": "Netflow", "description": "sfsf", "createdOn": 1652188809, "updatedOn": 1652188809, "disableAlerting": false, "autoPropsAssignedOn": 0, "autoPropsUpdatedOn": 0, "scanConfigId": 0, "link": "", "enableNetflow": false, "netflowCollectorId": 0, "netflowCollectorGroupId": 0, "netflowCollectorGroupName": null, "isPreferredLogCollectorConfigured": false, "currentLogCollectorId": 0, "logCollectorId": 0, "logCollectorDescription": null, "logCollectorGroupId": 0, "logCollectorGroupName": null, "lastDataTime": 0, "lastRawdataTime": 0, "hostGroupIds": "56255,103904,23105,21122,142395", "sdtStatus": "none-none-none", "userPermission": "write", "rolePrivileges": [], "hostStatus": "dead-collector", "alertStatus": "unconfirmed-critical-none", "alertStatusPriority": 1, "awsState": 1, "azureState": 1, "gcpState": 1, "alertDisableStatus": "none-none-none", "alertingDisabledOn": null, "collectorDescription": "centos-systemd-1", "netflowCollectorDescription": null, "customProperties": [ { "name": "sn.cmdb_url", "value": "https://ven02915.service-now.com/nav_to.do?uri=cmdb_ci.do?sys_id=a1750a00db11d110afef285b13961906" }, { "name": "sn.sys_id", "value": "a1750a00db11d110afef285b13961906" }, { "name": "system.categories", "value": "" } ], "resourceIds": null, "upTimeInSeconds": 0, "deletedTimeInMs": 0, "toDeleteTimeInMs": 0, "hasDisabledSubResource": false, "ancestorHasDisabledLogicModule": false, "systemProperties": [ { "name": "system.enablenetflow", "value": "false" }, { "name": "system.collectorplatform", "value": "linux" }, { "name": "system.description", "value": "sfsf" }, { "name": "system.collectorid", "value": "11934" }, { "name": "system.deviceId", "value": "770544" }, { "name": "system.prefcollectordesc", "value": "centos-systemd-1" }, { "name": "system.collectordesc", "value": "centos-systemd-1" }, { "name": "system.groups", "value": "Synthetics_Resource_Group,demo:/dasdas,152_SJ_dy,DeadDeviceGrp,175_SJ_2" }, { "name": "system.deviceGroupId", "value": "56255,103904,23105,21122,142395" }, { "name": "system.resourceCreatedOn", "value": "1652188809" }, { "name": "system.devicetype", "value": "0" }, { "name": "system.collectorversion", "value": "29107" }, { "name": "system.staticgroups", "value": "Synthetics_Resource_Group" }, { "name": "system.prefcollectorid", "value": "11934" }, { "name": "system.displayname", "value": "my test vm" }, { "name": "system.hoststatus", "value": "dead-collector" }, { "name": "system.hostname", "value": "10.241.242.102" } ], "autoProperties": [], "inheritedProperties": [ { "name": "test11", "value": "test11" }, { "name": "testPropertyTel", "value": "tel:18618198654" }, { "name": "testPropertyHttps", "value": "https://test.com" }, { "name": "mayank.pass", "value": "********" }, { "name": "test.pass", "value": "********" }, { "name": "test", "value": "test" }, { "name": "fdfdf", "value": "121212" }, { "name": "jnj", "value": "jnj" }, { "name": "snmp.community", "value": "********" }, { "name": "xen.user", "value": "root" }, { "name": "esx.pass", "value": "********" }, { "name": "tomcat.jmxports", "value": "9003" }, { "name": "netapp.user", "value": "abhi9999" }, { "name": "testPropertyHttp", "value": "http://test.com" }, { "name": "xen.url", "value": "" }, { "name": "becca", "value": "something" }, { "name": "testPropertySkype", "value": "skype:21268822" }, { "name": "testPropertyMailto", "value": "mailto:[email protected]" }, { "name": "mayank", "value": "test" }, { "name": "fang_wan", "value": "192.192.178.1" }, { "name": "SS", "value": "wwww" }, { "name": "test22", "value": "test22" }, { "name": "esx.user", "value": "adsf" }, { "name": "test.ipsi", "value": " " }, { "name": "rootProp", "value": "test" }, { "name": "xen.pass", "value": "********" }, { "name": "today.date", "value": "8June" }, { "name": "Test_prop1", "value": "test1" }, { "name": "test2", "value": "test2" }, { "name": "api-property1553839486", "value": "value" }, { "name": "ssh.pass", "value": "********" } ], "syntheticsCollectorIds": [] } ], "searchId": null, "isMin": false }

    Operator Usage in Advanced Filters for /device/devices API 

    • Operator not equal (!:) filter query
    {{url}}/device/devices?filter=customProperties!:"{\"name\":\"predef.bizservice.evalMembersInterval\",\"value\":\"*\"}"
    • Operator contains (~) filter query
    {{url}}/device/devices?filter=customProperties~"{\"name\":\"predef.bizservice.evalMembersInterval\",\"value\":\"*\"}"
    • Operator not contains (!~) filter query
    {{url}}/device/devices?filter=customProperties!~"{\"name\":\"predef.bizservice.evalMembersInterval\",\"value\":\"*\"}"

    Note: You will not get all possible values by merely using the contains (~) and not contains (!~) filter. Instead, these filter will give an exact match. To get all possible values, add an asterisk (*)to the filter. For example, you can write “ATT*” or “*ATT” in

    • Contains:
      url/device/devices/?filter=customProperties~”{\”name\”:\”FilterTest\”,\”value\”:\”ATT*\”}”&fields=id,name,customProperties
    • Not contains:
      url/device/devices/?filter=customProperties!~”{\”name\”:\”FilterTest\”,\”value\”:\”ATT*\”}”&fields=id,name,customProperties
    • Operator special_eq (:::) filter query
    {{url}}/device/devices?filter=inheritedProperties:::empty

    The response body returns all devices that do no have inheritedProperties. Empty checks for both null and empty.

    • Operator special_ne (!::) filter query
    {{url}}/device/devices?filter=netflowCollectorDescription!::empty

    The response body returns all devices where netflowCollectorDescription is not empty or null.

    • Operator special_ne (!::) filter query
    {{url}}/device/devices?filter=netflowCollectorDescription!::null

    In the response body this query gives all the devices where netflowCollectorDescription is not null.

    • Operator logical OR (||) filter query
    {{url}}/device/devices?filter=customProperties:"{\"name\":\"testPROPERTY\",\"value\":\"service\"}" || customProperties:"{\"name\":\"system.categories\",\"value\":\"KubernetesLogicalService\"}"
    • Single and advanced filter query
    {{url}}/device/devices?fields=systemProperties,name,id&filter=systemProperties:"{\"name\":\"system.description\",\"value\":\"sfsf\"}",id>100

    Example: 
    Run the query

    {{url}}/device/devices?filter=systemProperties:"{\"name\":\"system.hostname\",\"value\":\"ay_service1_*\"}",id>1528&fields=systemProperties,id

    In the response body this query gives the following result:

    { "total": 1, "items": [ { "id": 1530, "systemProperties": [ { "name": "system.enablenetflow", "value": "false" }, { "name": "system.collectorplatform", "value": "n/a" }, { "name": "system.collectorid", "value": "-4" }, { "name": "system.deviceId", "value": "1530" }, { "name": "system.prefcollectordesc", "value": "Service Data Aggregator" }, { "name": "system.collectordesc", "value": "Service Data Aggregator" }, { "name": "system.groups", "value": "Ay_service_group" }, { "name": "system.deviceGroupId", "value": "478" }, { "name": "system.resourceCreatedOn", "value": "1552015277" }, { "name": "system.devicetype", "value": "6" }, { "name": "system.collectorversion", "value": "0" }, { "name": "system.staticgroups", "value": "Ay_service_group" }, { "name": "system.prefcollectorid", "value": "-4" }, { "name": "system.displayname", "value": "ay_service1_CLONE1" }, { "name": "system.hostname", "value": "ay_service1_CLONE1" } ] } ], "searchId": null, "isMin": false }

    Operator Usage in Advanced Filters for /alert/alerts API

    Note: Alert filters for monitorObjectGroups are supported only for fullpath property. Currently, only 2 operators – Equal (:) and Contain (~) are supported.

    Equal (:) and Contain (~) Operators

    • Filter alerts that have Resource Group or monitorObjectGroups’s fullpath=”Devices by Type/Collectors”
    {{url}}/alert/alerts?filter=monitorObjectGroups:"Devices by Type/Collectors"

    Example

    https://localdev.logicmonitor.com/santaba/rest/alert/alerts?filter=monitorObjectGroups:"Devices by Type/Collectors"
    • Filter alerts that have Resource Group (“Devices by Type”) or its subgroups. “*” at the end indicates that it also includes the subgroups. For example, a Resource Group (“Devices by Type”) has 2 subgroups: Collectors (“Devices by Type/Collectors”) and Linux Servers (“Devices by Type/Linux Servers”). Here, the result will include alerts having Resource Groups either (fullpath=”Devices by Type”) or (fullpath=”Devices by Type/Collectors”) or (fullpath=”Devices by Type/Linux Servers”)
    {{url}}/alert/alerts?filter=monitorObjectGroups:"Devices by Type*"
    • Filter alerts based on multiple Resource Group values (multiple fullpath values should be separated by “|”)
      Filter alerts that have (fullpath=”Devices by Type/Collectors”) or (fullpath=”Kubernetes Cluster: k8-test/Nodes/All”)
    {{url}}/alert/alerts?filter=monitorObjectGroups:"Devices by Type/Collectors|Kubernetes Cluster: k8-test/Nodes/All"
    • Filter alerts of root Group. If the fullpath of the root group is empty, then the company name (for example, qauat01) should be provided.
    {{url}}/alert/alerts?filter=monitorObjectGroups:"qauat01"
    • Filter alerts that match with “Collectors” in the Resource Group fullpath. If there are 2 groups with fullpath as “Devices by Type/Collectors” and “Collectors_Backup” then the result will contain alerts from both the groups.
    {{url}}/alert/alerts?filter=monitorObjectGroups~"Collectors"
    • Single and advanced filter query
    {{url}}/alert/alerts?filter=monitorObjectGroups:"Devices by Type/Collectors",startEpoch>:1653295431
    {{url}}/alert/alerts?filter=monitorObjectGroups:"Devices by Type/Collectors",type:"batchJobAlert"

    14-day access to the full LogicMonitor platform