Monitoring Server Storage Cloud Database SAN LAN

Public API

XorMon NG provides a standard REST API for integration with other tools.
Public API is only available to customers with support subscription.

Features

get information about configured devices
remove a device
get device health status
export performance data stored in XorMon NG database

Planned features

add new device
disable/enable a configured device

This page does not contain complete documentation for Public REST API
REST API documentation is available in XorMon NG UI
Navigate to Settings (cogwheel) ➡ Public API

Authentication

API requests require API key header for authorization.

--header 'apiKey: <api-key>'

Obtain API key

API request example using the default user 'xormon'

curl --request POST \
  --url https://<xormon-ng_ip>/api/public/v1/auth \
  --header 'Content-Type: application/json' \
  --data '{"username": "xormon", "password": "xormon"}'

Example response

{
  "statusCode": 200,
  "data": {
    "apiKey": "0ac125069c6da17f7801c7ac70784efe",
    "expiration": "2024-08-03T09:29:19.896Z"
  }
}

Example authentication header for subsequent API calls

--header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Get device information

Device list
Get device IDs, names, device class and hardware type.

API request

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/architecture/devices \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "item_id": "vmware_8df25c4a-9e09-444a-999b-ead34a7d7e49_17",
      "label": "vCenter",
      "hw_type": "vmware",
      "class": "virtualization",
      "subsystem": "vcenter"
    },
    {
      "item_id": "d3a841b6-9af4-46e7-a931-03f9c293f9ec",
      "label": "Lenovo",
      "hw_type": "eseries",
      "class": "storage",
      "subsystem": "device"
    },
    {
      "item_id": "9c2d8d68-dbfa-4ee3-af10-9ea50f18333c",
      "label": "Cisco",
      "hw_type": "sancisco",
      "class": "san",
      "subsystem": "device"
    }
  ]
}

Device configuration
Get detaild device configuration data

API request

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/hostcfg \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "hostcfg_id": "2ec6db74-ff9f-48ce-894f-8e6e7b0fa2b3",
      "label": "vCenter",
      "hw_type": "vmware",
      "disabled": false,
      "target": false,
      "ignore_health_status": false,
      "ignore_health_status_reason": null,
      "data": {
        "host": "192.168.0.1",
        "port": 443,
        "created": 1717012589051,
        "updated": null,
        "password": null,
        "username": "lpar2rrd@xorux.local",
        "description": "vCenter",
        "managementUrl": "https://192.168.0.1/ui"
      },
      "createdAt": "2024-05-29T19:56:30.465Z",
      "updatedAt": "2024-05-29T19:56:30.465Z",
      "hw_type_label": "VMware",
      "limited": false
    },
    {
      "hostcfg_id": "d3a841b6-9af4-46e7-a931-03f9c293f9ec",
      "label": "Lenovo",
      "hw_type": "eseries",
      "disabled": false,
      "target": false,
      "ignore_health_status": false,
      "ignore_health_status_reason": null,
      "data": {
        "device": "LENOVO__TS_DE_SERIES",
        "apiHost": "192.168.0.2",
        "apiPort": 8443,
        "created": 1717012378784,
        "updated": null,
        "apiPassword": null,
        "apiUsername": "monitor",
        "description": "Lenovo DE 2000",
        "managementUrl": "https://192.168.0.2:8443/"
      },
      "createdAt": "2024-05-29T19:53:00.328Z",
      "updatedAt": "2024-05-29T19:53:00.328Z",
      "hw_type_label": "E-series",
      "limited": false
    },
    {
      "hostcfg_id": "9c2d8d68-dbfa-4ee3-af10-9ea50f18333c",
      "label": "Cisco",
      "hw_type": "sancisco",
      "disabled": false,
      "target": false,
      "ignore_health_status": false,
      "ignore_health_status_reason": null,
      "data": {
        "device": "CISCO__CISCO",
        "created": 1717012692179,
        "updated": 1717012722960,
        "snmpHost": "192.168.0.3",
        "snmpPort": 161,
        "description": "Cisco SAN switch Olomouc",
        "snmpVersion": "2c",
        "snmpSecLevel": "noAuthNoPriv",
        "snmpCommunity": "public",
        "snmpAuthProtocol": "SHA",
        "snmpPrivProtocol": "AES"
      },
      "createdAt": "2024-05-29T19:58:13.586Z",
      "updatedAt": "2024-05-29T19:58:44.244Z",
      "hw_type_label": "SAN Cisco",
      "limited": false
    }
  ]
}

Get device health status

API request

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/health_status \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "status": "OK",
      "count": 2,
      "devices": [
        {
          "class": "san",
          "hw_type": "sancisco",
          "hw_type_label": "SAN Cisco",
          "label": "Cisco",
          "item_id": "9c2d8d68-dbfa-4ee3-af10-9ea50f18333c",
          "updatedAt": 1720101659744,
          "note": "The operational status of the switch Cisco is Healthy/ok.",
          "status": "ok",
          "data": 0,
          "connection": 0,
          "ignored": false,
          "ignore_reason": null,
          "url": "/api/menu/v1/page/sancisco/health-status?item_id=9c2d8d68-dbfa-4ee3-af10-9ea50f18333c"
        },
        {
          "class": "storage",
          "hw_type": "eseries",
          "hw_type_label": "E-series",
          "label": "Lenovo",
          "item_id": "d3a841b6-9af4-46e7-a931-03f9c293f9ec",
          "updatedAt": 1720101604309,
          "note": "Storage array status is optimal.",
          "status": "ok",
          "data": 0,
          "connection": 0,
          "ignored": false,
          "ignore_reason": null,
          "url": "/api/menu/v1/page/eseries/health-status?item_id=d3a841b6-9af4-46e7-a931-03f9c293f9ec"
        },
      ]
    },
    {
      "status": "WARNING",
      "count": 0,
      "devices": []
    },
    {
      "status": "ERROR",
      "count": 0,
      "devices": []
    },
    {
      "status": "UNKNOWN",
      "count": 0,
      "devices": []
    },
    {
      "status": "IGNORED",
      "count": 0,
      "devices": []
    }
  ]
}

Browse XorMon NG architecture

Many APIs require some combination of Class, HW type, Sybsystem and Metric.
This information can be obtained from architecture API

Devices are identified by Class and Hardware type.
Devices consist of Subsystems.
Subsystems support specific set of performance metrics.

Device Class
Correspond to the XorMon NG top menu

Server
Storage
SAN
etc.

API request
Get list of classes

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/architecture/classes \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "label": "Server",
      "class": "virtualization",
      "active": true
    },
    {
      "label": "Storage",
      "class": "storage",
      "active": true
    },
    {
      "label": "SAN",
      "class": "san",
      "active": true
    },
    ...
  ]
}

HW Types
Specific device type within the Class

Virtualization: VMware, Nutanix, Proxmox, etc.
Storage: EMC PowerMAX, Lenovo E-Series, IBM Storwize, etc.
SAN: SAN Brocade, SAN CISCO, etc.
etc.

API request

GET https://<xormon-ng_ip>/api/public/v1/architecture/class/<class>/hw_types

Example: get list of storage HW types

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/architecture/class/storage/hw_types \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "class": "storage",
      "hw_type": "eseries",
      "label": "E-series"
    },
    {
      "class": "storage",
      "hw_type": "vmax",
      "label": "EMC VMAX/PowerMAX"
    },
    {
      "class": "storage",
      "hw_type": "swiz",
      "label": "Storwize"
    },
    ...
  ]
}

Subsystems
Each device type has a list of supported subsystems
Example:

Class: Storage
HW Type: E-series (Lenovo E-series)
Subsystems: Node, Pool, Volume, etc.

API request

GET https://<xormon-ng_ip>/api/public/v1/architecture/class/<class>/hw_type/<hw_type>/subsystems

Example: get list of Lenovo E-series subsystems

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/architecture/class/storage/hw_type/eseries/subsystems \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "label": "Node",
      "subsystem": "node"
    },
    {
      "label": "Pool",
      "subsystem": "pool"
    },
    {
      "label": "Volume",
      "subsystem": "volume"
    },
    ...
  ]
}

Performance metrics
Each device subsystem supports a specific set of performance metrics.
Example:

Class: Storage
HW Type: E-series (Lenovo E-series)
Subsystem: Pool
Metrics: IO rate, Data rate, Latency, etc.

API request

GET https://<xormon-ng_ip>/api/public/v1/architecture/class/<class>/hw_type/<hw_type>/subsystem/<subsystem>/metrics

Example: get list of Lenovo E-series pool metrics

curl --request GET \
  --url https://<xormon-ng_ip>/api/public/v1/architecture/class/storage/hw_type/eseries/subsystem/pool/metrics \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": [
    {
      "metric": "io_rate",
      "label": "IO",
      "shortcut": "IOPS",
      "unit": "IOPS"
    },
    {
      "metric": "data_rate",
      "label": "Data",
      "shortcut": "B/s",
      "unit": "bytes_per_second"
    },
    {
      "metric": "resp_t",
      "label": "Latency",
      "shortcut": "ms",
      "unit": "millisecond"
    },
    ...
  ]
}

Search for items

Search for specific items in the XorMon NG database and get their IDs.

API request

GET https://<xormon-ng_ip>/api/public/v1/architecture/search

Search parameters

class: string
hw_type: string
subsystem: string
parents: array of strings; one or more item IDs of parent devices
search: string; search for a string within item label (case insensitive)

Example

get list of volumes from a specific Lenovo E-series storage device
search only for volume containing "san" in the name

We already have necessary information from previous examples:

class: 'storage'
hw_type: 'eseries'
subsystem: 'volume'
parent id: 'd3a841b6-9af4-46e7-a931-03f9c293f9ec'
search: 'san'

Example request

curl --request GET \
  --url 'https://<xormon-ng_ip>/api/public/v1/architecture/search?subsystem=volume&hw_type=eseries&class=storage&parents=d3a841b6-9af4-46e7-a931-03f9c293f9ec&search=san' \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe'

Example response

{
  "statusCode": 200,
  "data": {
    "metadata": {
      "start": 0,
      "end": 49,
      "max": 3,
      "page": 0
    },
    "items": [
      {
        "label": "SAN-lenovo-ds01",
        "item_id": "020000006D039EA00010E81F0000020A5FCE1AAA",
        "hw_type": "eseries",
        "class": "storage",
        "subsystem": "volume"
      },
      {
        "label": "SAN-lenovo-ds02",
        "item_id": "020000006D039EA00010EEE3000002145FCE19E2",
        "hw_type": "eseries",
        "class": "storage",
        "subsystem": "volume"
      },
      {
        "label": "SAN-lenovo-ds03",
        "item_id": "020000006D039EA00010E81F0000029E6225BB82",
        "hw_type": "eseries",
        "class": "storage",
        "subsystem": "volume"
      },
      {
        "label": "SAN-lenovo-ssd01",
        "item_id": "020000006D039EA00010EEE30000030C630340E9",
        "hw_type": "eseries",
        "class": "storage",
        "subsystem": "volume"
      }
    ]
  }
}

Export performance data

Export a range of selected performance data from XorMon NG database for specific item IDs.

API

POST https://<xormon-ng_ip>/api/public/v1/exporter/timeseries

Request data (JSON format)

start: number; time in UNIX timestamp format (seconds)
end: integer; number; time in UNIX timestamp format (seconds)
metric: array of strings; list of metrics to be included in the response
uuids: array of strings; list of item IDs to be included in the response
format: string; one of: 'csv', 'xlsxs', 'json'

Example

get IOPS, Data and Latency
get data for specific volumes (see previous example)
get data between
- July 1, 2024 - 13:00 UTC
- July 1, 2024 - 13:30 UTC

We already have necessary information from previous examples:

metrics: io_rate, data_rate, resp_t
uuids: 020000006D039EA00010E81F0000020A5FCE1AAA, 020000006D039EA00010EEE3000002145FCE19E2, 020000006D039EA00010E81F0000029E6225BB82, 020000006D039EA00010EEE30000030C630340E9

Convert start/end time to UNIX timestamp

date -d "07/01/2024 13:00 UTC" +%s
1719838800

date -d "07/01/2024 13:30 UTC" +%s
1719840600

Example request

curl --request POST \
  --url https://<xormon-ng_ip>/api/public/v1/exporter/timeseries \
  --header 'Content-Type: application/json' \
  --header 'apiKey: 0ac125069c6da17f7801c7ac70784efe' \
  --data '{
      "start": 1719838800,
      "end": 1719840600,
      "metric": [ "io_rate", "data_rate", "resp_t" ],
      "uuids": [
        "020000006D039EA00010E81F0000020A5FCE1AAA",
        "020000006D039EA00010EEE3000002145FCE19E2",
        "020000006D039EA00010E81F0000029E6225BB82",
        "020000006D039EA00010EEE30000030C630340E9"
      ],
      "format": "json"
    }'

Example response

{
  "metadata": {
    "total": 4,
    "interval": 1
  },
  "items": [
    {
      "item_id": "020000006D039EA00010E81F0000029E6225BB82",
      "label": "SAN-lenovo-ds03",
      "metric": "io_rate [IOPS]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 232.38461303710938,
        "2024-07-01T13:05:00.000Z": 276.1600036621094,
        "2024-07-01T13:10:00.000Z": 214.57284545898438,
        "2024-07-01T13:15:00.000Z": 218.8657684326172,
        "2024-07-01T13:20:00.000Z": 214.93333435058594,
        "2024-07-01T13:25:00.000Z": 206.18272399902344
      }
    },
    {
      "item_id": "020000006D039EA00010E81F0000029E6225BB82",
      "label": "SAN-lenovo-ds03",
      "metric": "data_rate [B/s]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 2641139.5,
        "2024-07-01T13:05:00.000Z": 3351624.25,
        "2024-07-01T13:10:00.000Z": 3363234.25,
        "2024-07-01T13:15:00.000Z": 2864389,
        "2024-07-01T13:20:00.000Z": 2528645.75,
        "2024-07-01T13:25:00.000Z": 2779344
      }
    },
    {
      "item_id": "020000006D039EA00010E81F0000029E6225BB82",
      "label": "SAN-lenovo-ds03",
      "metric": "resp_t [ms]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 1.0149426460266113,
        "2024-07-01T13:05:00.000Z": 0.5939497351646423,
        "2024-07-01T13:10:00.000Z": 0.48667657375335693,
        "2024-07-01T13:15:00.000Z": 0.3136793076992035,
        "2024-07-01T13:20:00.000Z": 0.7482983469963074,
        "2024-07-01T13:25:00.000Z": 0.32446905970573425
      }
    },
    {
      "item_id": "020000006D039EA00010E81F0000020A5FCE1AAA",
      "label": "SAN-lenovo-ds01",
      "metric": "io_rate [IOPS]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 222.15049743652344,
        "2024-07-01T13:05:00.000Z": 226.49000549316406,
        "2024-07-01T13:10:00.000Z": 204.61920166015625,
        "2024-07-01T13:15:00.000Z": 201.6409454345703,
        "2024-07-01T13:20:00.000Z": 217.57333374023438,
        "2024-07-01T13:25:00.000Z": 200.1627960205078
      }
    },
    {
      "item_id": "020000006D039EA00010E81F0000020A5FCE1AAA",
      "label": "SAN-lenovo-ds01",
      "metric": "data_rate [B/s]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 6806658.5,
        "2024-07-01T13:05:00.000Z": 7034839,
        "2024-07-01T13:10:00.000Z": 6663482,
        "2024-07-01T13:15:00.000Z": 6613202.5,
        "2024-07-01T13:20:00.000Z": 6643795.5,
        "2024-07-01T13:25:00.000Z": 6535284.5
      }
    },
    {
      "item_id": "020000006D039EA00010E81F0000020A5FCE1AAA",
      "label": "SAN-lenovo-ds01",
      "metric": "resp_t [ms]",
      "timeseries": {
        "2024-07-01T13:00:00.000Z": 1.5638819932937622,
        "2024-07-01T13:05:00.000Z": 1.5805467367172241,
        "2024-07-01T13:10:00.000Z": 1.1813870668411255,
        "2024-07-01T13:15:00.000Z": 0.9557042121887207,
        "2024-07-01T13:20:00.000Z": 1.0944472551345825,
        "2024-07-01T13:25:00.000Z": 1.0231940746307373
      }
    },
    ...
  ]
}