1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. Analytics Services
  3. Analytics Datasets

Analytics Datasets

Analytics datasets use the following properties. All properties except for suspended are immutable.

Property Description

name

Name of the underlying statistic for this dataset

grouping

Group to which this statistic belongs

explanation

Explanation of underlying statistic

incore

Bytes of dataset data in-core

size

Bytes of dataset data on-disk

suspended

Boolean indicating whether dataset is currently suspended

activity

Pending dataset activity flag

Available datasets:

  • ad.avglatency

  • ad.avglatency[op]

  • ad.avglatency[result]

  • ad.binds

  • ad.binds[hostname]

  • ad.binds[result]

  • ad.ops

  • ad.ops[op]

  • ad.ops[result]

  • arc.accesses[hit/miss]

  • arc.l2_accesses[hit/miss]

  • arc.l2_size

  • arc.size

  • arc.size[component]

  • cpu.utilization

  • cpu.utilization[mode]

  • dnlc.accesses[hit/miss]

  • fc.bytes

  • fc.ops

  • ftp.kilobytes

  • http.reqs

  • io.bytes

  • io.bytes[op]

  • io.disks[utilization=95][disk]

  • io.ops

  • io.ops[disk]

  • io.ops[op]

  • iscsi.bytes

  • iscsi.ops

  • metacap.bytesused

  • metacap.percentused

  • ndmp.diskkb

  • nfs2.ops

  • nfs2.ops[op]

  • nfs3.ops

  • nfs3.ops[op]

  • nfs4.ops

  • nfs4.ops[op]

  • nfs4-1.ops

  • nfs4-1.bytes

  • nic.kilobytes

  • nic.kilobytes[device]

  • nic.kilobytes[direction]

  • sftp.kilobytes

  • smb.ops

  • smb.ops[op]

List Datasets

Lists all configured analytic datasets.

Example Request:

GET /api/analytics/v1/datasets HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 237
X-Zfssa-Analytics-Api: 1.0

{
    "datasets": [{
        "dataset": "dataset-000",
        "href": "/api/analytics/v1/datasets/arc.accesses[hit/miss]",
        "name": "arc.accesses[hit/miss]"
    }, {
        "dataset": "dataset-001",
        "href": "/api/analytics/v1/datasets/arc.l2_accesses[hit/miss]",
        "name": "arc.l2_accesses[hit/miss]",
    }, {
        "dataset": "dataset-002",
        "href": "/api/analytics/v1/datasets/arc.l2_size",
        "name": "arc.l2_size",
    }, {
        "dataset": "dataset-003",
        "href": "/api/analytics/v1/datasets/arc.size",
        "name": "arc.size",
    }, {
        "dataset": "dataset-004",
        "href": "/api/analytics/v1/datasets/arc.size[component]",
        "name": "arc.size[component]",
    }, {
        ...
    }]
}

Get Dataset

Gets properties from the specified dataset.

Example Request:

GET /api/analytics/v1/datasets/nfs4.ops HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 237
X-Zfssa-Analytics-Api: 1.0

{
    "dataset": {
        "activity": "none",
        "dataset": "dataset-030",
        "explanation": "NFSv4 operations per second",
        "grouping": "Protocol",
        "href": "/api/analytics/v1/datasets/nfs4.ops",
        "incore": 296128,
        "name": "nfs4.ops",
        "size": 53211540,
        "suspended": false
    }
}

Create Datasets

Creates a new dataset.

Example Request:

POST /api/analytics/v1/datasets HTTP/1.1
X-Auth-User: root
X-Auth-Key: password
Content-Type: application/json
Content-Length: 26

{"statistic": "test.sine"}

Example Result:

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 200
Location: /api/analytics/v1/datasets/test.sine

{
    "dataset":{
        "href": "/api/analytics/v1/datasets",
        "name": "test.sine",
        "grouping": "Test",
        "explanation": "sine per second",
        "incore": 34752,
        "size": 31912,
        "suspended": false,
        "activity": "none"
    }
}

Modify Dataset

The modify dataset command is used to suspend or resume data collection of a single dataset.

Example Suspend Request:

POST /api/analytics/v1/datasets/nfs4.ops

{"suspended":true}

Example Resume Request:

POST /api/analytics/v1/datasets/nfs4.ops
        {"suspended":false}

Example Result:

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 228
X-Zfssa-Analytics-Api: 1.0

{
    "dataset" {
        ...
        "suspended": false
    }
}

Destroy Datasets

Destroys a dataset.

Example Request:

DELETE /api/analytics/v1/datasets/test.sine HTTP/1.1

Example Result:

HTTP/1.1 204 No Content
X-Zfssa-Analytics-Api: 1.0

Save Dataset

Saves a dataset.

Example Request:

PUT /api/analytics/v1/datasets/nfs4.ops/data

Example Result:

HTTP/1.1 202 Accepted

Prune Dataset Data

The following table shows query parameters that are used in pruning datasets.

Parameter Description

granularity

Prune granularity. The data within a dataset can be pruned at a granularity value of second, minute, or hour.

endtime

Prune data collected prior to the given endtime. For the format of this time value, see Query Parameter: start.

Example Request:

The following example deletes all per-second, per-minute, and per-hour data in the nfs4.ops dataset. Data that was collected daily, weekly, monthly, or annually remains in the dataset. 

DELETE /api/analytics/v1/datasets/nfs4.ops/data?granularity=hour

Example Result:

HTTP/1.1 204 No Content

Example Request:

The following example deletes all per-second, per-minute, and per-hour data in the nfs4.ops dataset that was collected prior to the specified endtime. 

DELETE /api/analytics/v1/datasets/nfs4.ops/data?granularity=hour&endtime=20130910T00:00:00

Get Dataset Data

Returns data from an active analytic dataset. Both per-second and granular data retrieval are supported.

The following table shows time-based query parameters for getting dataset data.

Parameter Description

start

The time to begin collecting sample data or the sample index at which to start collecting data. The start time value can be a specific time or can be the keyword now. For the format of a specific time value, see Query Parameter: start. The default start time is the current time minus the value of seconds.

seconds

Number of seconds to collect sample data. The default value is 1. The seconds parameter is ignored if the span and granularity parameters are specified.

span

Duration of time to collect sample data: minute, hour, day, week, month, or year.

granularity

The granularity within a given span from which the average of data points is given: minute, hour, day, week, month, or year.

The start time cannot be in the future. If the number of seconds to collect data goes beyond the current time, the server waits for each sample before returning the data.

To retrieve granular data, use a combination of parameters span and granularity. When span and granularity are used, the seconds parameter is ignored. If either span or granularity is entered incorrectly, the request is ignored and the seconds parameter is used instead. An incorrect or unsupported request displays the error message "Input span and granularity are not supported."

The span and granularity parameters can be combined in the following ways:

  • If span is minute, granularity can only be minute.

  • If span is hour, granularity can be minute or hour.

  • If span is day, granularity can be minute, hour, or day.

  • If span is week, granularity can be hour, day, or week.

  • If span is month, granularity can be day, week, or month.

  • If span is year, granularity can be week, month, or year.

The following table shows the dataset data properties that are returned.

Property Description

data

Array of sample data

sample

Index number of the sample data

startTime

The time that sample was returned

min

The minimum value per second within the specified granularity

max

The maximum value per second within the specified granularity

Example request to collect two seconds of live data:

GET /api/analytics/v1/datasets/io.ops[op]/data?start=now&seconds=2 HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: text/x-yaml

Example Result:

HTTP/1.1 200 OK
Content-Type: text/x-yaml
X-Zfssa-Analytics-Api: 1.0
Transfer-Encoding: chunked

{
  "data": [
    {
      "sample": 457642682,
      "data": {
        "data": [
          {
            "key": "write",
            "value": 199
          }
        ],
        "value": 199
      },
      "startTime": "20200818T18:43:47",
      "samples": 457642683
    },
    {
      "sample": 457642683,
      "data": {
        "data": [
          {
            "key": "write",
            "value": 289
          }
        ],
        "value": 289
      },
      "startTime": "20200818T18:43:48",
      "samples": 457642684
    }
  ]
}

Example request to collect seven days of data within the span of one week:

GET /api/analytics/v1/datasets/io.ops[op]/data?start=20200811T15:00:00&granularity=day&span=week
    HTTP/1.1 
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: text/x-yaml

The following request reports that the io.ops[op] dataset is "I/O operations per second broken down by type of operation" (read or write): 

GET /api/analytics/v1/datasets/io.ops[op]

Example Result. Five of the seven output samples are omitted for brevity:

HTTP/1.1 200 OK
Content-Type: text/x-yaml
X-Zfssa-Analytics-Api: 1.0
Transfer-Encoding: chunked

{
  "data": [
    {
      "sample": 457197423,
      "data": {
        "max": 3156,
        "data": [
          {
            "max": 588,
            "key": "read",
            "value": 6,
            "min": 0
          },
          {
            "max": 3156,
            "key": "write",
            "value": 45,
            "min": 0
          }
        ],
        "value": 52,
        "min": 0
      },
      "startTime": "20200811T15:00:00",
      "samples": 457644011
    },
    {
      "sample": 457283823,
      "data": {
        "max": 3675,
        "data": [
          {
            "max": 588,
            "key": "read",
            "value": 6,
            "min": 0
          },
          {
            "max": 3675,
            "key": "write",
            "value": 45,
            "min": 0
          }
        ],
        "value": 52,
        "min": 0
      },
      "startTime": "20200812T15:00:23",
      "samples": 457644011
    }
  ]
}

You can also use a sample value as the start value. The result of the following request is the data from the specified one-second sample: 

GET /api/analytics/v1/datasets/io.ops[op]/data?start=457642682 HTTP/1.1