From 771399ad48fb2dec67b2f78b5e627622dd3d99ad Mon Sep 17 00:00:00 2001 From: Piotr Debski Date: Tue, 2 Nov 2021 16:43:29 +0100 Subject: [PATCH] request formats changes and corrections Signed-off-by: Piotr Debski --- pages/open_cas_linux/guide_monitoring_json.md | 582 ++++++++++-------- 1 file changed, 337 insertions(+), 245 deletions(-) diff --git a/pages/open_cas_linux/guide_monitoring_json.md b/pages/open_cas_linux/guide_monitoring_json.md index 5d659a3..4f3cc82 100644 --- a/pages/open_cas_linux/guide_monitoring_json.md +++ b/pages/open_cas_linux/guide_monitoring_json.md @@ -8,43 +8,93 @@ permalink: guide_monitoring_json.html Monitoring Open CAS Linux - JSON API ===================== -Json API overview ---------------------- +# Overview -Json API provides two basic functionalities for inspecting CAS: retrieving CAS statistics and listing CAS devices. All requests, responses and errors are in json format. +Json API provides basic functionalities for inspecting CAS. Retrieving CAS statistics on various levels, listing CAS devices and providing cache, core or io class details. All requests, responses and errors are in json format. -**Statistics** +**Json request** + +Request consist of header with name of command and parameters with additional request detials as cache id, core id or io class id. Different parameters are required for various commands. -Statistics can be requested on different levels cache, core or io class. It is dependant on passing optional arguments in request as core id or io class. +**Json responses** -**List CAS devices** +Responses consists of all requested components or in case of trouble error also encoded in json format. -Lists all cache instances and their core devices. +# Statistics -**Json request** +Statistics can be requested on different levels cache, core or io class. There are four specyfic command with different parameters responsible for inspecting those statistics. + +**Statistics requests:** + +- core with specyfic io class statistics + +- Cache statistics + +- Core statistics -Request consist of header with name of command and additional request detials as cache info, core info and io class info. Info includes parameters passed to CAS monitoring tool from which depends statistics level. Cache id is obligatory while core id and io class are optional parameters. +- io class statistics + +# Example statistics requests + +**Request of statistics on specyfied cache** -**Example request:** ```json { "header": { - "command": "stats", - "subcommands": ["cache info", "core info", "io class info"] + "commands": "stats cache" }, - "info": { + "params": { "cache id": 1, - "core id": 0, - "io class": 0 } } ``` -**Json responses** +**Request of statistics on specyfied core** + +```json +{ + "header": { + "commands": "stats core" + }, + "params": { + "cache id": 1, + "core id": 1, + } +} +``` + +**Request of statistics with specyfied io class for aggregated cores** + +```json +{ + "header": { + "commands": "stats io class" + }, + "params": { + "cache id": 1, + "io class": 0 + } +} +``` + +**Request of statistics on specyfied core and io class** -Responses consists of all requested components or in case of trouble error response also encoded to json format. +```json +{ + "header": { + "commands": "stats" + }, + "params": { + "cache id": 1, + "core id": 1, + "io class": 0 + } +} +``` -**Example statistics response structure:** +# Example statistics response + +**statistics response structure:** Statistics details - Usage statistics @@ -57,235 +107,153 @@ Statistics details - Error statistics -Optional details - -- Cache info - -- Core info - -- IO class info - -**Example statistics response:** - ```json { - "Cache info": { - "Cache id": 1, - "Cache device": "/dev/disk/by-id/nvme-nvme.8086-50484b53373438323030335433373541474e-494e54454c20535344504544314b3337354741-00000001-part4", - "Core(s) id(s)": [ - 1, - 2 - ], - "Cache details": { - "Attached": true, - "Status": "stopping", - "Size [cache lines]": 5183520, - "Inactive cores": { - "Occupancy": { - "Page": 0, - "Fraction": 0 - }, - "Clean": { - "Page": 0, - "Fraction": 0 - }, - "Dirty": { - "Page": 0, - "Fraction": 0 - } - }, - "Occupancy [cache lines]": 518, - "Dirty [cache lines]": 0, - "Dirty for [s]": 0, - "Initially dirty [cache lines]": 0, - "Cache mode": "wt", - "Pass-Trough fallback statistics": { - "IO errors count": 0, - "Status": false - }, - "Cleaning policy": "alru", - "Promotion policy": "always", - "Cache line size [KiB]": 4096, - "Flushed blocks": 0, - "Core count": 2, - "Metadata footprint [B]": 262553896, - "Metadata end offset [4 KiB blocks]": 59296 + "Cache id": 1, + "Core id": 1, + "IO class": 0, + "Usage": { + "Occupancy": { + "Page": 259, + "Fraction": 0 + }, + "Free": { + "Page": 0, + "Fraction": 0 + }, + "Clean": { + "Page": 259, + "Fraction": 10000 + }, + "Dirty": { + "Page": 0, + "Fraction": 0 } }, - "Core info": { - "Core id": 1, - "Core path": "/dev/disk/by-id/nvme-nvme.8086-50484b45373331353030304c37353042474e-494e54454c20535344504532314b3735304741-00000001-part3", - "Core details": { - "Core size [line size]": 5242816, - "Core size [B]": 21474574336, - "Flushed blocks": 0, - "Dirty blocks": 0, - "Dirty for [s]": 0, - "Sequential cutoff threshold [B]": 1048576, - "Sequential cutoff policy [B]": "full" + "Requests": { + "Read hits": { + "Page": 0, + "Fraction": 0 }, - "State": "active" + "Read partial misses": { + "Page": 0, + "Fraction": 0 + }, + "Read full misses": { + "Page": 43, + "Fraction": 10000 + }, + "Read total": { + "Page": 43, + "Fraction": 10000 + }, + "Write hits": { + "Page": 0, + "Fraction": 0 + }, + "Write partial misses": { + "Page": 0, + "Fraction": 0 + }, + "Write full misses": { + "Page": 0, + "Fraction": 0 + }, + "Write total": { + "Page": 0, + "Fraction": 0 + }, + "Pass-Trough reads": { + "Page": 0, + "Fraction": 0 + }, + "Pass-Trough writes": { + "Page": 0, + "Fraction": 0 + }, + "Serviced requests": { + "Page": 43, + "Fraction": 10000 + }, + "Total requests": { + "Page": 43, + "Fraction": 10000 + } }, - "IO class": { - "Class id": 0, - "Info": { - "Name": "unclassified", - "Cache mode": "max", - "Priority": 255, - "Current size [cache line]": 518, - "Min size [%]": 0, - "Max size [%]": 100, - "Cleaning policy": "alru" + "Blocks": { + "Reads from core(s)": { + "Page": 259, + "Fraction": 10000 + }, + "Writes from core(s)": { + "Page": 0, + "Fraction": 0 + }, + "Total from/to core(s)": { + "Page": 259, + "Fraction": 10000 + }, + "Reads from cache(s)": { + "Page": 0, + "Fraction": 0 + }, + "Writes from cache(s)": { + "Page": 259, + "Fraction": 10000 + }, + "Total from/to cache(s)": { + "Page": 259, + "Fraction": 10000 + }, + "Reads from exported object(s)": { + "Page": 259, + "Fraction": 10000 + }, + "Writes from exported object(s)": { + "Page": 0, + "Fraction": 0 + }, + "Total from/to exported object(s)": { + "Page": 259, + "Fraction": 10000 } }, - "Statistics": { - "Cache id": 1, - "Core id": 1, - "IO class": 0, - "Usage": { - "Occupancy": { - "Page": 259, - "Fraction": 0 - }, - "Free": { - "Page": 0, - "Fraction": 0 - }, - "Clean": { - "Page": 259, - "Fraction": 10000 - }, - "Dirty": { - "Page": 0, - "Fraction": 0 - } + "Errors": { + "Core read errors": { + "Page": 0, + "Fraction": 0 }, - "Requests": { - "Read hits": { - "Page": 0, - "Fraction": 0 - }, - "Read partial misses": { - "Page": 0, - "Fraction": 0 - }, - "Read full misses": { - "Page": 43, - "Fraction": 10000 - }, - "Read total": { - "Page": 43, - "Fraction": 10000 - }, - "Write hits": { - "Page": 0, - "Fraction": 0 - }, - "Write partial misses": { - "Page": 0, - "Fraction": 0 - }, - "Write full misses": { - "Page": 0, - "Fraction": 0 - }, - "Write total": { - "Page": 0, - "Fraction": 0 - }, - "Pass-Trough reads": { - "Page": 0, - "Fraction": 0 - }, - "Pass-Trough writes": { - "Page": 0, - "Fraction": 0 - }, - "Serviced requests": { - "Page": 43, - "Fraction": 10000 - }, - "Total requests": { - "Page": 43, - "Fraction": 10000 - } + "Core write errors": { + "Page": 0, + "Fraction": 0 }, - "Blocks": { - "Reads from core(s)": { - "Page": 259, - "Fraction": 10000 - }, - "Writes from core(s)": { - "Page": 0, - "Fraction": 0 - }, - "Total from/to core(s)": { - "Page": 259, - "Fraction": 10000 - }, - "Reads from cache(s)": { - "Page": 0, - "Fraction": 0 - }, - "Writes from cache(s)": { - "Page": 259, - "Fraction": 10000 - }, - "Total from/to cache(s)": { - "Page": 259, - "Fraction": 10000 - }, - "Reads from exported object(s)": { - "Page": 259, - "Fraction": 10000 - }, - "Writes from exported object(s)": { - "Page": 0, - "Fraction": 0 - }, - "Total from/to exported object(s)": { - "Page": 259, - "Fraction": 10000 - } + "Core total errors": { + "Page": 0, + "Fraction": 0 }, - "Errors": { - "Core read errors": { - "Page": 0, - "Fraction": 0 - }, - "Core write errors": { - "Page": 0, - "Fraction": 0 - }, - "Core total errors": { - "Page": 0, - "Fraction": 0 - }, - "Cache read errors": { - "Page": 0, - "Fraction": 0 - }, - "Cache write errors": { - "Page": 0, - "Fraction": 0 - }, - "Cache total errors": { - "Page": 0, - "Fraction": 0 - }, - "Total errors": { - "Page": 0, - "Fraction": 0 - } + "Cache read errors": { + "Page": 0, + "Fraction": 0 + }, + "Cache write errors": { + "Page": 0, + "Fraction": 0 + }, + "Cache total errors": { + "Page": 0, + "Fraction": 0 + }, + "Total errors": { + "Page": 0, + "Fraction": 0 } } } - ``` -**List caches** +# List caches -Inspect CAS devices with casadm list caches mentioned in [**Monitoring CAS**](/guide_monitoring.html). +Checking CAS devices with casadm list caches mentioned in [**Monitoring CAS**](/guide_monitoring.html). ```console [root@localhost json]# casadm -L @@ -295,19 +263,26 @@ cache 1 /dev/nvme3n1p4 Running wt - â””core 2 /dev/nvme0n1p4 Active - /dev/cas1-2 ``` -Inspect the same CAS devices with json API - -**Example statistics response structure:** - -Statistics details -- Cache instance - - - Core devices +# Example list caches request +```json +{ + "header": { + "command": "list caches" + }, + "params": { + } +} +``` +# Example list caches response -**Example list caches response:** +**Example List caches response structure:** +- for each cache instance: + - Cache details + - for each core in cache: + - Core details ```json [ { @@ -386,20 +361,137 @@ Statistics details ] } ] +``` +# Example cache info request +```json +{ + "header": { + "commands": "cache info" + }, + "params": { + "cache id": 1, + } +} ``` -**Example error response:** +# Example cache info response ```json { - "error log": { - "cas_ctrl object access failed": "open /dev/cas_ctrl: permission denied", - "failed to retrive statistics": "open /dev/cas_ctrl: permission denied" + "Cache id": 1, + "Cache device": "/dev/disk/by-id/nvme-nvme.8086-50484b53373438323030335433373541474e-494e54454c20535344504544314b3337354741-00000001-part4", + "Core(s) id(s)": [ + 1, + 2 + ], + "Cache details": { + "Attached": true, + "Status": "stopping", + "Size [cache lines]": 5183520, + "Inactive cores": { + "Occupancy": { + "Page": 0, + "Fraction": 0 + }, + "Clean": { + "Page": 0, + "Fraction": 0 + }, + "Dirty": { + "Page": 0, + "Fraction": 0 + } + }, + "Occupancy [cache lines]": 518, + "Dirty [cache lines]": 0, + "Dirty for [s]": 0, + "Initially dirty [cache lines]": 0, + "Cache mode": "wt", + "Pass-Trough fallback statistics": { + "IO errors count": 0, + "Status": false + }, + "Cleaning policy": "alru", + "Promotion policy": "always", + "Cache line size [KiB]": 4096, + "Flushed blocks": 0, + "Core count": 2, + "Metadata footprint [B]": 262553896, + "Metadata end offset [4 KiB blocks]": 59296 } } ``` -**Summary** +# Example core info request -Json Api is good start and building block to RESTful API which can provide good integration CAS with other tools. For now it plays role of command line tool providing request and responses in json format. \ No newline at end of file +```json +{ + "header": { + "commands": "core info" + }, + "params": { + "cache id": 1, + "core id": 1, + } +} +``` + +# Example core info response + +```json +{ + "Core id": 1, + "Core path": "/dev/disk/by-id/nvme-nvme.8086-50484b45373331353030304c37353042474e-494e54454c20535344504532314b3735304741-00000001-part3", + "Core details": { + "Core size [line size]": 5242816, + "Core size [B]": 21474574336, + "Flushed blocks": 0, + "Dirty blocks": 0, + "Dirty for [s]": 0, + "Sequential cutoff threshold [B]": 1048576, + "Sequential cutoff policy [B]": "full" + }, + "State": "active" + } +``` + +# Example io class info reqest + +```json +{ + "header": { + "commands": "io class" + }, + "params": { + "cache id": 1, + "io class": 0 + } +} +``` + +# Example io class info response + +```json +{ + "Class id": 0, + "Info": { + "Name": "unclassified", + "Cache mode": "max", + "Priority": 255, + "Current size [cache line]": 518, + "Min size [%]": 0, + "Max size [%]": 100, + "Cleaning policy": "alru" + } +} +``` + +# Example error response + +```json +{ + "cas_ctrl object access failed": "open /dev/cas_ctrl: permission denied", + "failed to retrive statistics": "open /dev/cas_ctrl: permission denied" +} +```