Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

sstore.json (5)

Name

sstore.json - sstore JSON export format

Description

sstore(1) export subcommand and the sstore_iter_export(3SSTORE) functions can both return results in a common sstore JSON (JavaScript Object Notation) format.

sstore(1) export specifically allows you to select the output as a single line (JSON) or as formatted for readability (JSON-formatted).

Format

The format of the output is as follows:

    {
        "__version": <export format version>,

        "data": [
            {
                "ssid": <ssid of stat/event>
                "records": [
                    {
                        "start-time":
                            <time stamp or start of a time range>,
                        "end-time": <end of a time range>,
                        "value": <value>,
                        "value-error": <reason for no data>
                    },

                    ...
                ]
            },

            ...
        ],

        "warnings": [
            {
                "ssid": <ssid or stat/event>,
                "code": <warning code>,
                "description": <human readable warning description>
            },

            ...
        ],

        "__digest": {
            "<name of algorithm>": <hash_value>
        }
    }

The following sections describe the output in further detail.

Fields

__version (integer)

Contains the JSON format version.

data (array of hashes)

Contains the result for all the requests in the form of an array of hashes, each of which contains the requested data for an ssid in the request.

If there is any error while processing the request, or if the request is a list request, then the data field is not present.

Each hash in the array contains the following fields:

ssid (string)

Contains the ssid of the stat or event for which the data was requested

records (array of hashes)

Contains the stat or event or metadata records, and is an array of hashes, each of which represents a data record.

This field is optional and should be present only if the result of the request has some stat or event or metadata records. See example 6 for more info.

Each hash in this array contains the following fields:

start-time (string)

Contains the time stamp of the record or the start of a time range for the record.

end-time (string)

Contains the end of a time range for the record.

value (integer, double, string, array, or hash)

Contains the value of the record. It is optional and should be present only if there is some data for that timestamp.

value-error (string)

Contains the reason for the absence of any value in the data record. This field is present only if the data record does not contain any value. See the second example in the "Examples" section for more information.


Note -  If the request is not a list request, then either one of the two fields, value or value-error, should be present.
errors (associative array)

See the description of warnings below.

warnings (associative array)

Contains all the errors or warnings for the request. These fields are present only if there are errors or warnings for the given request. See example 5 for more info.

Each element of the warnings array contains the following fields:

ssid (string)

Contains the ssid of the stat or event for which the warning is generated

type (integer)

Contains the warning code for the warning

description (string)

Contains the human-readable description for the warning

__digest (hash)

Contains a digest hash of the returned JSON, excluding the digest field. This field is optional. However, if it is present, it is used for validation. This field, in turn, contains the following field:

<algorithm name> (string)

The hash value calculated using the given algorithm.

Examples

Example 1 Export Stats in JSON Format
sstore export -t 2014-07-01T13:12:32-2014-07-01T13:12:34 -F JSON //:class.cpu//:res.id/0//:stat.sw_usage//:part.mode

{
    "__version": 1,

    "data": [
        {
            "ssid": "//:class.cpu//:res.id/0//:stat.sw_usage//:part.mode"
            "records": [
                {
                    "start-time": "2014-07-01T13:12:32",
                    "value": {
                        "kernel": 5425163662629,
                        "idle": 1009251339623473,
                        "stolen": 0,
                        "user": 175512010446,
                        "intr": 1218505588337
                    },
                },
                {
                    "start-time": "2014-07-01T13:12:33",
                    "value": {
                        "kernel": 5425165101484,
                        "idle": 1009252339338400,
                        "stolen": 0,
                        "user": 175512010446,
                        "intr": 1218507065626
                    }
                },
                {
                    "start-time": "2014-07-01T13:12:34",
                    "value": {
                        "kernel": 5425173693828,
                        "idle": 1009253331859203,
                        "stolen": 0,
                        "user": 175512010446,
                        "intr": 1218508393875
                    }
                }
            ]
        }
    ],

    "__digest": {
        "SHA-256": <hashed value>
    }
}
Example 2 Export Stats With NO_DATA for Some Data Records
sstore export -t 2014-07-01T13:12:32-2014-07-01T13:12:34 -F JSON //:class.foo//:res.//:s.[bar_1,bar_2]//:stat.baz

{
    "__version": 1,

    "data": [
        {
            "ssid": "//:class.foo//:res.bar_1//:stat.baz"
            "records": [
                {
                    "start-time": "2014-07-01T13:12:32",
                    "value-error": "Not captured"
                },
                {
                    "start-time": "2014-07-01T13:12:33",
                    "value": 1
                },
                {
                    "start-time": "2014-07-01T13:12:34",
                    "value": 2
                }
            ]
        },

        {
            "ssid": "//:class.cpu//:res.bar_2//:stat.baz"
            "records": [
                {
                    "start-time": "2014-07-01T13:12:32",
                    "value-error": "Not authorized to read"
                },
                {
                    "start-time": "2014-07-01T13:12:33",
                    "value-error": "Not authorized to read"
                },
                {
                    "start-time": "2014-07-01T13:12:34",
                    "value-error": "Not authorized to read"
                }
            ]
        }
    ],

    "__digest": {
        "SHA-256": <hashed value>
    }
}
Example 3 Export Metadata in JSON Format
sstore info -F JSON -t 2014-07-01T13:30:01-2014-07-01T16:15:31 //:class.cpu//:res.id///:s.[0,1]//:stat.sw_usage

{
    "__version": 1,

    "data": [
        {
            "ssid": "//:class.cpu//:res.id/0//:stat.sw_usage"
            "records": [
                {
                    "start-time": "2014-07-01T13:30:01",
                    "end-time": "2014-07-01T16:15:31",
                    "value": {
                        "units": "ns",
                        "part1": "mode",
                        "type": "counter",
                        "description": "system time per cpu",
                        "multiplier": 1000000000
                    }
                }
            ]
        },

        {
            "ssid": "//:class.cpu//:res.id/1//:stat.sw_usage"
            "records": [
                {
                    "start-time": "2014-07-01T13:30:01",
                    "end-time": "2014-07-01T14:15:31",
                    "value": {
                        "units": "ns",
                        "part1": "mode",
                        "type": "counter",
                        "description": "system time per cpu",
                        "multiplier": 1000000000
                    }
                },

                {
                    "start-time": "2014-07-01T14:30:01",
                    "end-time": "2014-07-01T16:15:31"
                    "value": {
                        "units": "ns",
                        "part1": "mode",
                        "type": "counter",
                        "description": "system time per cpu",
                        "multiplier": 1000000000
                    }
                }
            ]
        }
    ],

    "__digest": {
        "SHA-256": <hash value>
    }
}