Zones Monitoring Statistics API (libzonestat)

openapi: 3.1.0
info:
  title: Solaris Zones Monitoring Statistics API
  description: >-
    REST API for retrieving zone resource utilization statistics on Oracle
    Solaris 11.4 systems. Provides access to the libzonestat functionality
    through the RAD REST interface, enabling programmatic retrieval of per-zone
    resource consumption data including physical memory, virtual memory, CPU
    utilization, and network I/O with sorting and filtering capabilities.
  version: '1.0'
  contact:
    name: Oracle Solaris Support
    url: https://www.oracle.com/solaris/support/
    email: solaris-support@oracle.com
  license:
    name: Oracle Technology Network License
    url: https://www.oracle.com/legal/terms.html
externalDocs:
  description: Oracle Solaris Zone Monitoring Statistics
  url: https://docs.oracle.com/cd/E37838_01/html/E61043/
servers:
- url: https://{host}:{port}/api
  description: Oracle Solaris RAD REST endpoint
  variables:
    host:
      default: localhost
      description: Solaris host running RAD
    port:
      default: '6788'
      description: RAD REST API port
tags:
- name: CPU Statistics
  description: CPU utilization and allocation statistics
- name: Memory Statistics
  description: Memory and swap utilization statistics
- name: System Statistics
  description: System-wide resource statistics
- name: Zone Statistics
  description: Per-zone resource utilization statistics
security:
- cookieAuth: []
paths:
  /com.oracle.solaris.rad.kstat/2.0:
    get:
      operationId: listKstatInterfaces
      summary: Solaris Zones List All Kernel Statistics Interfaces
      description: >-
        Discover all available kernel statistics interfaces. Provides access
        to CPU, memory, network, and zone-specific resource utilization data.
      tags:
      - System Statistics
      parameters:
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: Available kstat interfaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    type: array
                    items:
                      type: object
                      properties:
                        href:
                          type: string
                        type:
                          type: string
              examples:
                Listkstatinterfaces200Example:
                  summary: Default listKstatInterfaces 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                    - href: example_value
                      type: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/zones,{zoneName},zone_caps,{zoneId}:
    get:
      operationId: getZoneCapStatistics
      summary: Solaris Zones Get Zone Resource Cap Statistics
      description: >-
        Retrieve resource cap statistics for a specific zone including CPU cap,
        memory cap, and swap cap utilization. Shows the configured limits and
        current usage.
      tags:
      - Zone Statistics
      parameters:
      - name: zoneName
        in: path
        required: true
        description: Zone name
        schema:
          type: string
        example: example_value
      - name: zoneId
        in: path
        required: true
        description: Numeric zone ID
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: Zone cap statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/ZoneCapStats'
              examples:
                Getzonecapstatistics200Example:
                  summary: Default getZoneCapStatistics 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      zonename: example_value
                      zone_id: '500123'
                      cpu_cap: 42.5
                      cpu_usage: 42.5
                      cpu_nwait: 10
                      memory_cap: 10
                      memory_usage: 10
                      swap_cap: 10
                      swap_usage: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/zones,{zoneName},zone_misc,{zoneId}:
    get:
      operationId: getZoneMiscStatistics
      summary: Solaris Zones Get Zone Miscellaneous Statistics
      description: >-
        Retrieve miscellaneous statistics for a specific zone including
        process counts, lightweight process counts, and other zone-level
        metrics.
      tags:
      - Zone Statistics
      parameters:
      - name: zoneName
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: zoneId
        in: path
        required: true
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: Zone miscellaneous statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/ZoneMiscStats'
              examples:
                Getzonemiscstatistics200Example:
                  summary: Default getZoneMiscStatistics 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      zonename: example_value
                      zone_id: '500123'
                      nprocs: 10
                      nlwps: 10
                      pr_size: 10
                      pr_rss: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/memory_cap,{zoneId},physcap,{zoneId}:
    get:
      operationId: getZonePhysicalMemoryCap
      summary: Solaris Zones Get Zone Physical Memory Cap Statistics
      description: >-
        Retrieve physical memory capping statistics for a zone including the
        configured cap, current RSS, number of page-outs due to capping, and
        time spent in page-out.
      tags:
      - Memory Statistics
      parameters:
      - name: zoneId
        in: path
        required: true
        description: Numeric zone ID
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: Physical memory cap statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/MemoryCapStats'
              examples:
                Getzonephysicalmemorycap200Example:
                  summary: Default getZonePhysicalMemoryCap 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      physcap: 10
                      rss: 10
                      nover: 10
                      pagedout: 10
                      pgpgin: 10
                      anonpgin: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/memory_cap,{zoneId},swapcap,{zoneId}:
    get:
      operationId: getZoneSwapCap
      summary: Solaris Zones Get Zone Swap Cap Statistics
      description: >-
        Retrieve swap space capping statistics for a zone including the
        configured swap cap and current swap usage.
      tags:
      - Memory Statistics
      parameters:
      - name: zoneId
        in: path
        required: true
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: Swap cap statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/SwapCapStats'
              examples:
                Getzoneswapcap200Example:
                  summary: Default getZoneSwapCap 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      swapcap: 10
                      usage: 10
                      nover: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/cpucaps,{zoneName},cpucaps_zone_{zoneId},{zoneId}:
    get:
      operationId: getZoneCpuCap
      summary: Solaris Zones Get Zone Cpu Cap Statistics
      description: >-
        Retrieve CPU capping statistics for a specific zone including the
        configured CPU cap value, current usage, and time spent being capped.
      tags:
      - CPU Statistics
      parameters:
      - name: zoneName
        in: path
        required: true
        schema:
          type: string
        example: example_value
      - name: zoneId
        in: path
        required: true
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: CPU cap statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/CpuCapStats'
              examples:
                Getzonecpucap200Example:
                  summary: Default getZoneCpuCap 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      value: 10
                      usage: 10
                      nwait: 10
                      below: 10
                      above: 10
                      maxusage: 10
                      zonename: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/misc,cpu_info0,cpu_info,{cpuId}:
    get:
      operationId: getCpuInfo
      summary: Solaris Zones Get Cpu Information
      description: >-
        Retrieve detailed information about a specific CPU including model,
        clock speed, vendor, and state. Useful for understanding the physical
        resources available to zones.
      tags:
      - CPU Statistics
      parameters:
      - name: cpuId
        in: path
        required: true
        description: CPU identifier number
        schema:
          type: integer
        example: '500123'
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: CPU information
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/CpuInfo'
              examples:
                Getcpuinfo200Example:
                  summary: Default getCpuInfo 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      brand: example_value
                      chip_id: '500123'
                      clock_MHz: 10
                      core_id: '500123'
                      cpu_type: example_value
                      implementation: example_value
                      ncore_per_chip: 10
                      state: on-line
                      vendor_id: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /com.oracle.solaris.rad.kstat/2.0/Kstat/unix,0,system_pages,0:
    get:
      operationId: getSystemMemoryPages
      summary: Solaris Zones Get System Memory Page Statistics
      description: >-
        Retrieve system-wide memory page statistics including total physical
        pages, free pages, and page sizes. Provides context for zone memory
        allocation.
      tags:
      - Memory Statistics
      parameters:
      - $ref: '#/components/parameters/radDetail'
      responses:
        '200':
          description: System memory statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  payload:
                    $ref: '#/components/schemas/SystemMemoryStats'
              examples:
                Getsystemmemorypages200Example:
                  summary: Default getSystemMemoryPages 200 response
                  x-microcks-default: true
                  value:
                    status: example_value
                    payload:
                      physmem: 10
                      freemem: 10
                      availrmem: 10
                      lotsfree: 10
                      desfree: 10
                      minfree: 10
                      pp_kernel: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: _rad_session
      description: RAD session cookie obtained via authentication
  parameters:
    radDetail:
      name: _rad_detail
      in: query
      required: false
      description: Include detailed property information
      schema:
        type: boolean
  responses:
    Unauthorized:
      description: Authentication required or session expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RadError'
    NotFound:
      description: Statistic or zone not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RadError'
  schemas:
    RadError:
      type: object
      properties:
        status:
          type: string
          example: failure
        payload:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
          example: example_value
    ZoneCapStats:
      type: object
      description: Zone resource cap utilization statistics
      properties:
        zonename:
          type: string
          description: Zone name
          example: example_value
        zone_id:
          type: integer
          description: Numeric zone ID
          example: '500123'
        cpu_cap:
          type: number
          description: CPU cap value (percentage of a CPU)
          example: 42.5
        cpu_usage:
          type: number
          description: Current CPU usage percentage
          example: 42.5
        cpu_nwait:
          type: integer
          format: int64
          description: Number of times zone waited due to CPU cap
          example: 10
        memory_cap:
          type: integer
          format: int64
          description: Physical memory cap in bytes
          example: 10
        memory_usage:
          type: integer
          format: int64
          description: Current physical memory usage in bytes
          example: 10
        swap_cap:
          type: integer
          format: int64
          description: Swap cap in bytes
          example: 10
        swap_usage:
          type: integer
          format: int64
          description: Current swap usage in bytes
          example: 10
    ZoneMiscStats:
      type: object
      description: Zone miscellaneous statistics
      properties:
        zonename:
          type: string
          example: example_value
        zone_id:
          type: integer
          example: '500123'
        nprocs:
          type: integer
          description: Number of processes in the zone
          example: 10
        nlwps:
          type: integer
          description: Number of lightweight processes in the zone
          example: 10
        pr_size:
          type: integer
          format: int64
          description: Total process size in bytes
          example: 10
        pr_rss:
          type: integer
          format: int64
          description: Total resident set size in bytes
          example: 10
    MemoryCapStats:
      type: object
      description: Physical memory cap statistics
      properties:
        physcap:
          type: integer
          format: int64
          description: Physical memory cap in bytes
          example: 10
        rss:
          type: integer
          format: int64
          description: Current resident set size in bytes
          example: 10
        nover:
          type: integer
          format: int64
          description: Number of times memory went over the cap
          example: 10
        pagedout:
          type: integer
          format: int64
          description: Total bytes paged out due to capping
          example: 10
        pgpgin:
          type: integer
          format: int64
          description: Pages paged in
          example: 10
        anonpgin:
          type: integer
          format: int64
          description: Anonymous pages paged in
          example: 10
    SwapCapStats:
      type: object
      description: Swap cap statistics
      properties:
        swapcap:
          type: integer
          format: int64
          description: Swap cap in bytes
          example: 10
        usage:
          type: integer
          format: int64
          description: Current swap usage in bytes
          example: 10
        nover:
          type: integer
          format: int64
          description: Number of times swap exceeded the cap
          example: 10
    CpuCapStats:
      type: object
      description: CPU cap statistics
      properties:
        value:
          type: integer
          format: int64
          description: CPU cap value in microseconds per second
          example: 10
        usage:
          type: integer
          format: int64
          description: Current CPU usage in microseconds per second
          example: 10
        nwait:
          type: integer
          format: int64
          description: Number of times threads waited due to cap
          example: 10
        below:
          type: integer
          format: int64
          description: Time spent below the cap in nanoseconds
          example: 10
        above:
          type: integer
          format: int64
          description: Time spent above the cap in nanoseconds
          example: 10
        maxusage:
          type: integer
          format: int64
          description: Maximum CPU usage observed
          example: 10
        zonename:
          type: string
          description: Zone name
          example: example_value
    CpuInfo:
      type: object
      properties:
        brand:
          type: string
          description: CPU brand string
          example: example_value
        chip_id:
          type: integer
          example: '500123'
        clock_MHz:
          type: integer
          example: 10
        core_id:
          type: integer
          example: '500123'
        cpu_type:
          type: string
          example: example_value
        implementation:
          type: string
          example: example_value
        ncore_per_chip:
          type: integer
          example: 10
        state:
          type: string
          enum:
          - on-line
          - off-line
          - powered-off
          - no-intr
          - spare
          example: on-line
        vendor_id:
          type: string
          example: '500123'
    SystemMemoryStats:
      type: object
      properties:
        physmem:
          type: integer
          format: int64
          description: Total physical memory pages
          example: 10
        freemem:
          type: integer
          format: int64
          description: Free memory pages
          example: 10
        availrmem:
          type: integer
          format: int64
          description: Available real memory pages
          example: 10
        lotsfree:
          type: integer
          format: int64
          description: Lotsfree threshold
          example: 10
        desfree:
          type: integer
          format: int64
          description: Desfree threshold
          example: 10
        minfree:
          type: integer
          format: int64
          description: Minfree threshold
          example: 10
        pp_kernel:
          type: integer
          format: int64
          description: Pages used by kernel
          example: 10