How to view stream health metrics by using the Wowza Streaming Cloud REST API

Learn how to use the REST API to get health metrics for transcoders in the Wowza Streaming Cloud™ service. Health metrics include details about the source connection to the transcoder and transcoder processing data that can help you understand how a stream was received and processed.

Contents


Stream health parameters
View current stream health metrics for an active transcoder
View historic stream health metrics for a transcoder
Related requests

Stream health parameters


Parameter Data Type Description
fields string

The metrics or data you want to view. Omit from the request to return all available data, or include to limit what’s returned to the specified fields.

For current metrics, you can specify audio_codec, bits_in_rate, bits_out_rate, bytes_in_rate, bytes_out_rate, configured_bytes_out_rate, connected, cpu, frame_rate, frame_size, gpu_decoder_usage, gpu_driver_version, gpu_encoder_usage, gpu_memory_usage, gpu_usage, height, keyframe_interval, video_codec, and width.

For historic metrics, you can specify audio_codec, bits_in_rate, bits_out_rate, cpu_idle, frame_rate, height, keyframe_interval, video_codec, and width.

from datetime

For historic metrics only. The start of the range of time you want to view. Express the value by using the ISO 8601 standard of YYYY-MM-DDTHH:MM:SSZ where HH is a 24-hour clock in UTC.

to datetime

For historic metrics only. The end of the range of time you want to view. Express the value by using the ISO 8601 standard of YYYY-MM-DDTHH:MM:SSZ where HH is a 24-hour clock in UTC.

The amount of time between the from and to parameters must be less than 48 hours.

transcoder_id string Required. The unique alphanumeric string that identifies the transcoder
uptime_id string Required. The unique alphanumeric string that identifies the uptime session

View current stream health metrics for an active transcoder


Current metrics for an active transcoder include details about the connection between the source encoder and the transcoder as well as data about how the transcoder is processing the stream.

To view current stream health metrics for an active transcoder, call the resource:

https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/current

The request returns a snaphot of current metrics for the active stream at the time of the request.

Example requests and responses

Notes:

  • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.1.

View the stream health details of an active transcoder:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/current"

Metrics and data for the active session (uptime_id) of the transcoder (transcoder_id) are returned in the response, which should look something like this:

{
  "current": {
    "unique_views": {
      "value": 37,
      "status": "normal",
      "text": "",
      "units": ""
    },
    "connected": {
      "value": "Yes",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "cpu": {
      "value": 80,
      "status": "normal",
      "text": "",
      "units": "%"
    },
    "bytes_in_rate": {
      "value": 1142.7,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    },
    "bytes_out_rate": {
      "value": 5707.8,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    },
    "configured_bytes_out_rate": {
      "value": 6696000,
      "status": "normal",
      "text": "",
      "units": "bps"
    },
    "width": {
      "value": 720,
      "status": "warning",
      "text": "Configured width is different from what Wowza Streaming Cloud is receiving from the source: 720.",
      "units": "px"
    },
    "height": {
      "value": 480,
      "status": "warning",
      "text": "Configured height is different from what Wowza Streaming Cloud is receiving from the source: 480.",
      "units": "px"
    },
    "frame_size": {
      "value": "720x480",
      "status": "warning",
      "text": "Configured frame size is different from what Wowza Streaming Cloud is receiving from the source: 720x480.",
      "units": ""
    },
    "frame_rate": {
      "value": 30.2,
      "status": "normal",
      "text": "",
      "units": "FPS"
    },
    "keyframe_interval": {
      "value": 30,
      "status": "normal",
      "text": "",
      "units": "GOP"
    },
    "video_codec": {
      "value": "avc1",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "audio_codec": {
      "value": "AAC",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "bits_in_rate": {
      "value": 1142.7,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    },
    "bits_out_rate": {
      "value": 5707.8,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    },
    "gpu_driver_version": {
      "value": "not_installed",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "gpu_usage": {
      "value": null,
      "status": "normal",
      "text": "",
      "units": "%"
    },
    "gpu_memory_usage": {
      "value": null,
      "status": "normal",
      "text": "",
      "units": "%"
    },
    "gpu_encoder_usage": {
      "value": null,
      "status": "normal",
      "text": "",
      "units": "%"
    },
    "gpu_decoder_usage": {
      "value": null,
      "status": "normal",
      "text": "",
      "units": "%"
    },
    "stream_target_status_3ypvxt00_d1j8jfzs": {
      "value": "Active",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "stream_target_status_fsfp9bqb_d1j8jfzs": {
      "value": "Active",
      "status": "normal",
      "text": "",
      "units": ""
    },
    "stream_target_status_ydbvnxkk_d1j8jfzs": {
      "value": "Active",
      "status": "normal",
      "text": "",
      "units": ""
    }
  },
  "limits": {
    "fields": [
      "unique_views",
      "connected",
      "cpu",
      "bytes_in_rate",
      "bytes_out_rate",
      "configured_bytes_out_rate",
      "width",
      "height",
      "frame_size",
      "frame_rate",
      "keyframe_interval",
      "video_codec",
      "audio_codec",
      "bits_in_rate",
      "bits_out_rate",
      "gpu_driver_version",
      "gpu_usage",
      "gpu_memory_usage",
      "gpu_encoder_usage",
      "gpu_decoder_usage",
      "stream_target_status_3ypvxt00_d1j8jfzs",
      "stream_target_status_fsfp9bqb_d1j8jfzs",
      "stream_target_status_ydbvnxkk_d1j8jfzs"
    ]
  }
}

View only specific metrics, such as the rate of bits into and out of the transcoder in this example, for a current uptime session:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/current?fields=bits_in_rate,bits_out_rate

The command returns a response with the limits applied and looks something like this:

{
  "current": {
    "bits_in_rate": {
      "value": 1149.3,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    },
    "bits_out_rate": {
      "value": 4669.1,
      "status": "normal",
      "text": "",
      "units": "Kbps"
    }
  },
  "limits": {
    "fields": [
      "bits_in_rate",
      "bits_out_rate"
    ]
  }
}

View historic stream health metrics for a transcoder


Historic health metrics include the audio and video codec used, the rate of bits into and out of the transcoder, the frame rate and keyframe interval of the stream, and the width and height of the frame.

To view historic stream health metrics for a transcoder that's running or stopped, call the resource:

https://api.cloud.wowza.com/api/[version]/ transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/historic

Historic metrics are recorded every 20 seconds. As a result, brief irregularities might not register or be tracked and visualized. If the uptime session was longer than two days, the request returns data for only the most recent 48 hours of the uptime session.

Example requests and responses

View the historic stream health details for an uptime session (uptime_id) of a transcoder (transcoder_id):

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/historic

The command returns a response that looks something like this:

{
  "history": [
    {
      "cpu_idle": {
        "value": 88,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_in_rate": {
        "value": 1653232,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_out_rate": {
        "value": 6051976,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "frame_rate": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "width": {
        "value": 1920,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "height": {
        "value": 1080,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "video_codec": {
        "value": avc1,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "audio_codec": {
        "value": AAC,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:18:22.161Z"
      },
      {
      "cpu_idle": {
        "value": 82,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_in_rate": {
        "value": 1651880,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_out_rate": {
        "value": 6669056,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "frame_rate": {
        "value": 29.885829415715246,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "width": {
        "value": 1920,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "height": {
        "value": 1080,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "video_codec": {
        "value": avc1,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "audio_codec": {
        "value": AAC,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:18:42.161Z"
    },
    ...
    {
        "cpu_idle": {
        "value": 66,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_in_rate": {
        "value": 724880,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "bits_out_rate": {
        "value": 3865840,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "frame_rate": {
        "value": 30.060120240480963,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "width": {
        "value": 1920,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "height": {
        "value": 1080,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "video_codec": {
        "value": avc1,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "audio_codec": {
        "value": aac,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:23:22.161Z"
    }
  ],
  "limits": {
    "from": "2017-04-19T00:16:41.000Z",
    "to": "2017-04-19T02:32:50.000Z",
    "fields": [
      "cpu_idle",
      "bits_in_rate",
      "bits_out_rate",
      "frame_rate",
      "width",
      "height",
      "keyframe_interval",
      "video_codec",
      "audio_codec"
    ]
  }
}

View only specific metrics, such as the frame rate and keyframe interval in this example, for an uptime session of a transcoder that ran in the past:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]/metrics/historic?fields=frame_rate,keyframe_interval

The command returns a response with the limits applied and looks something like this:

{
  "history": [
    {
      "frame_rate": {
        "value": 30.060120240480963,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:18:22.161Z"
    },
    {
      "frame_rate": {
        "value": 29.936091490077363,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:18:42.161Z"
    },
    {
      "frame_rate": {
        "value": 30.13056578506863,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:19:02.162Z"
    },
    {
      "frame_rate": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:19:22.161Z"
    },
    ...
    {
      "frame_rate": {
        "value": 29.855753102985574,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "keyframe_interval": {
        "value": 30,
        "status": "ok",
        "text": "",
        "units": ""
      },
      "created_at": "2017-04-19T00:23:22.161Z"
    }
  ],
  "limits": {
    "from": "2017-04-19T00:16:41.000Z",
    "to": "2017-04-19T02:32:50.000Z",
    "fields": [
      "frame_rate",
      "keyframe_interval"
    ]
  }
}

Related requests


View an active transcoder’s uptime_id:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/state"

The command should return a response that looks something like this:

{
  "transcoder": {
    "ip_address": "1.2.3.4",
    "state": "started",
    "transcoding_uptime_id": "f3p9bvb0",
    "uptime_id": "f3p9bvb0"
  }
}

Get a list of uptime records for a transcoder:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes"

The command should return a response that looks something like this:

{
  "uptimes": [
    {
     "id": "nvg6mjy8",
     "transcoder_id": "fxtpd74j",
     "started_at": "2017-04-19T00:16:41.000Z",
     "ended_at": "2017-04-19T02:32:50.000Z",
     "running": false,
     "billed": true,
     "created_at": "2017-04-19T00:14:11.000Z",
     "updated_at": "2017-04-19T09:00:37.000Z",
     "links": []
    },
    {
     "id": "6bmskgbc",
     "transcoder_id": "fxtpd74j",
     "started_at": "2017-04-19T12:29:37.000Z",
     "ended_at": "2017-04-19T23:23:27.000Z",
     "running": false,
     "billed": true,
     "created_at": "2017-04-19T12:24:41.000Z",
     "updated_at": "2017-04-19T21:00:36.000Z",
     "links": []
    },
    {
     "id": "f3p9bvb0",
      "transcoder_id": "fxtpd74j",
      "started_at": "2017-04-24T22:27:17.000Z",
      "running": true,
      "billed": true,
      "created_at": "2017-04-24T22:24:37.000Z",
      "updated_at": "2017-04-25T09:00:33.000Z",
      "links": []
    }
  ]
],
    "links": []
}

Get the details of a specific uptime for a transcoder:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/uptimes/[uptime_id]"

The command should return a response that looks something like this:

{
"uptime": {
    "id": "f3p9bvb0",
    "transcoder_id": "fxtpd74j",
    "started_at": "2017-04-24T22:27:17.000Z",
    "running": true,
    "billed": true,
    "created_at": "2017-04-24T22:24:37.000Z",
    "updated_at": "2017-04-25T09:00:33.000Z",
    "links": []
  }
}

If you're having problems or want to discuss this article, post in our forum.