使用平台記錄檔

本頁面說明如何使用由 Live Stream API 產生的平台記錄檔，做為 Cloud Logging 的一部分。Live Stream API 會使用 Logging API 服務名稱 livestream.googleapis.com 記錄管道相關活動。

事前準備

啟用平台記錄功能

根據預設，Live Stream API 的 livestream.googleapis.com/channel_activities 平台記錄會停用。如要啟用記錄，您必須在建立或更新管道資源時指定嚴重性層級。

如要啟用記錄，請將下列欄位新增至 projects.locations.channels.create 或 projects.locations.channels.patch 方法的請求 JSON 主體：

   "logConfig": {
     "logSeverity": "SEVERITY_LEVEL"
   },

其中 SEVERITY_LEVEL 是下列其中一項：

  • OFF
  • DEBUG
  • INFO
  • WARNING
  • ERROR

為管道選擇記錄嚴重性等級後，系統只會記錄嚴重性等級高於或等於所選嚴重性等級的平台記錄。舉例來說，如果嚴重性等級為 WARNING，則只會記錄嚴重性等級為 WARNING 和 ERROR 的記錄。如果嚴重性等級為 INFO，系統會記錄 DEBUG 以外所有嚴重性等級的記錄。

如要進一步瞭解記錄嚴重性層級，請參閱 LogSeverity。

查看平台記錄檔

如要查看平台記錄，請按照下列指示操作：

控制台

如要在 Google Cloud 控制台中查看平台記錄，請按照下列步驟操作：

  1. 前往「Logs Explorer」(記錄檔探索工具)：

    前往「Logs Explorer」

  2. 選取適當的 Google Cloud 專案。

  3. 在「Query」欄位中輸入下列查詢指令：

    resource.labels.channel_id=CHANNEL_ID
resource.labels.location=LOCATION
logName="projects/PROJECT_ID/logs/livestream.googleapis.com%2Fchannel_activities"

    其中：

    • CHANNEL_ID 是您要偵錯或監控的頻道 ID。例如：my-channel。

    • LOCATION 是您要偵錯或監控的管道位置。例如：us-central1。

    • PROJECT_ID 是包含您要偵錯或監控的管道專案 ID。例如：my-project。

  4. 點選「執行查詢」。

如要進一步瞭解記錄檔探索工具，請參閱「記錄檔探索工具總覽」和「使用記錄檔探索工具」。

gcloud

gcloud 指令列工具提供 Cloud Logging 的指令列介面。

如要查看專案的 channel_activities 記錄，請執行下列指令：

gcloud logging read "logName:projects/PROJECT_ID/logs/livestream.googleapis.com%2Fchannel_activities" --project=PROJECT_ID

其中 PROJECT_ID 是 Google Cloud 專案的 ID。

如要進一步瞭解如何搭配使用 gcloud 工具和 Cloud Logging，請參閱 gcloud logging。

使用平台記錄檔

本節說明如何使用及解讀 Live Stream API 的特定平台記錄。

eventStateChange

當管道事件狀態發生變更時，系統會產生 eventStateChange 記錄。當管道事件的新狀態為 FAILED 時，eventStateChange 記錄的嚴重性等級為 ERROR。否則，eventStateChange 記錄的嚴重性等級為 INFO。

以下是 eventStateChange 記錄的範例：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    eventStateChange: {
      eventId: "my-ad-break"
      newState: "SCHEDULED"
      previousState: "PENDING"
    }
    message: "State of event "my-ad-break" changed from "PENDING" to "SCHEDULED"."
  }
  ...
  severity: "INFO"
  ...
}

scte35CommandReceived

當輸入串流接收 SCTE35 指令時，系統會產生 scte35CommandReceived 記錄。scte35CommandReceived 記錄的嚴重性等級為 INFO。

系統只會處理 durationFlag、breakDuration、spliceTime 和 outOfNetworkIndicator。缺少 spliceTime 時，系統會立即執行 SCTE35 指令。系統會將所有其他欄位視為無操作。

以下是 scte35CommandReceived 記錄的範例：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    scte35CommandReceived: {
      spliceInfoSection: {
        ptsAdjustment: "123456789"
        spliceInsert: {
          availNum: 0
          availsExpected: 0
          breakDuration: null
          componentCount: 0
          components: [0]
          durationFlag: false
          outOfNetworkIndicator: true
          programSpliceFlag: true
          spliceEventCancelIndicator: false
          spliceEventId: 123456789
          spliceImmediateFlag: true
          spliceTime: null
          uniqueProgramId: 5
        }
      }
    }
    message: "Received inband SCTE35 command, eventID=123456789."
  }
  ...
  severity: "INFO"
  ...
}

streamingStateChange

當頻道的串流狀態發生變更時，系統就會產生 streamingStateChange 記錄。當管道的狀態為 STREAMING_ERROR 時，streamingStateChange 記錄的嚴重性層級為 ERROR。否則，streamingStateChange 記錄的嚴重性等級為 INFO。

以下是 streamingStateChange 記錄的範例，其中先前的狀態為 STREAMING_ERROR，新狀態為 STREAMING：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    message: "streaming state of channel "CHANNEL_ID" changes from "STREAMING_ERROR" to "STREAMING""
    streamingStateChange: {
      newState: "STREAMING"
      previousState: "STREAMING_ERROR"
      ...
    type: "livestream.googleapis.com/Channel"
  }
  severity: "INFO"
  ...
}

您可以在記錄檔探索工具的「查詢」欄位中新增其他指令，進一步縮小顯示的記錄範圍。

新增下列指令，顯示所有新狀態為 STREAMING 的 streamingStateChange 記錄：

jsonPayload.streamingStateChange.newState="STREAMING"

新增下列指令，只顯示 streamingStateChange 記錄：

jsonPayload.streamingStateChange.newState:*

streamingError

頻道發生串流相關錯誤時，系統會產生 streamingError 記錄。streamingError 記錄的嚴重性等級為 ERROR。

以下是 streamingError 記錄的範例，其中 Live Stream API 無法上傳輸出檔案至指定的 Cloud Storage 值區：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    message: "A live streaming encounters an error."
    streamingError: {
      error: {
        ...
        message: "Permission denied to access the Cloud Storage bucket "STORAGE_BUCKET_NAME""
  ...
  severity: "ERROR"
  ...
}

如果指定的 Cloud Storage 值區不存在，也會發生這個錯誤。

如果 streamingError.message 顯示訊息 This is due to an internal error. If the error persists, please contact support team，請複製記錄內容並傳送給支援團隊，以便排除問題。

inputAccept

當輸入串流成功連線至 Live Stream API 輸入端點時，系統會產生 inputAccept 記錄。inputAccept 記錄的嚴重性等級為 INFO。

inputAccept 記錄中的 inputStreamProperty 欄位包含下列資訊，說明輸入串流的影片和音訊子串流：

影片串流
  • 索引
  • 編解碼
  • 影格速率
  • 解析度
音訊串流
  • 索引
  • 通道數量
  • 頻道版面配置
  • 轉碼器資訊

您可以使用 inputAccept 記錄來驗證輸入串流的格式和接受狀態：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    inputAccept: {
      inputAttachment: "input-primary"
      inputStreamProperty: {
        audioStreams: [
          0: {
            audioFormat: {
              channelCount: 2
              channelLayout: [
                0: "fl"
                1: "fr"
              ]
              codec: "aac"
            }
            index: 1
          }
        ]
        videoStreams: [
          0: {
            videoFormat: {
              codec: "h264"
              frameRate: 60
              heightPixels: 720
              widthPixels: 1280
      ...
      streamId: "STREAM_ID"
    }
    message: "Input stream "STREAM_ID" is accepted by channel "CHANNEL_ID" for input attachment "input-primary""
  }
  ...
  severity: "INFO"
  ...
}

在「Logs Explorer」查詢欄位中加入下列指令，只顯示特定串流的 inputAccept 記錄：

jsonPayload.inputAccept.streamId="STREAM_ID"

其中 STREAM_ID 是 輸入端點 URI 中串流的專屬 ID。

inputError

當 Live Stream API 拒絕輸入串流時，系統會產生 inputError 記錄。inputError 記錄的嚴重性等級為 ERROR。

以下是 inputError 記錄的範例，其中輸入串流已傳送至尚未啟動的管道：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    inputError: {
      error: {
        ...
        message: "The channel has not been started yet"
      }
      streamId: "STREAM_ID"
  ...
  severity: "ERROR"
  ...
}

以下是 inputError 記錄的範例，其中重複的輸入串流會傳送至已串流的頻道：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    inputError: {
      error: {
        code: 9
        message: "input stream "STREAM_ID" has been accepted. Please verify if another input stream has been streaming to the same endpoint."
      }
      streamId: "STREAM_ID"
  ...
  severity: "ERROR"
  ...
}

在 Logs Explorer 的「查詢」欄位中加入下列指令，只顯示特定串流的 inputError 記錄：

jsonPayload.inputError.streamId="STREAM_ID"

其中 STREAM_ID 是 輸入端點 URI 中串流的專屬 ID。

inputDisconnect

當輸入串流與 Live Stream API 中斷連線時，系統會產生 inputDisconnect 記錄。您可以使用 inputDisconnect 記錄，檢查直播意外中斷的情況。inputDisconnect 記錄的嚴重性等級為 INFO。

以下是 inputDisconnect 記錄的範例：

{
  jsonPayload: {
    @type: "type.googleapis.com/google.cloud.video.livestream.logging.v1.ChannelActivity"
    inputDisconnect: {
      inputAttachment: "input-primary"
      streamId: "STREAM_ID"
    }
    message: "Input stream "STREAM_ID" is disconnected by channel "CHANNEL_ID" for input attachment "input-primary""
  ...
  severity: "INFO"
  ...
}