Using platform logs

This page describes how to use platform logs generated by Live Stream API as part of Cloud Logging. Live Stream API uses the Logging API service name livestream.googleapis.com to log channel-related activity.

Before you begin

Make sure you have the correct IAM permissions and roles to view and manage logs.

Activate platform logging

By default, the livestream.googleapis.com/channel_activities platform logs for Live Stream API are deactivated. To activate the logs, you need to specify a severity level when creating or updating the channel resource.

To activate the logs, add the following field to the request JSON body of the projects.locations.channels.create or the projects.locations.channels.patch method:

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

where SEVERITY_LEVEL is one of the following:

OFF
DEBUG
INFO
WARNING
ERROR

Once you choose a log severity level for a channel, only the platform logs with a severity level higher than or equal to the chosen severity level are logged. For example, if the severity level is WARNING, only logs with severity level WARNING and ERROR are logged. If the severity level is INFO, logs of all severity levels except for DEBUG are logged.

For more information about log severity levels, see LogSeverity.

View platform logs

To view platform logs, follow the instructions below:

Console

To view platform logs in the Google Cloud console:

Navigate to the Logs Explorer:

Go to the Logs Explorer
Select the appropriate Google Cloud project.
In the Query field, enter the following query command:
```
resource.labels.channel_id=CHANNEL_ID
resource.labels.location=LOCATION
logName="projects/PROJECT_ID/logs/livestream.googleapis.com%2Fchannel_activities"
```
where:
- CHANNEL_ID is the ID of the channel you want to debug or monitor. For example, my-channel.
- LOCATION is the location of the channel you want to debug or monitor. For example, us-central1.
- PROJECT_ID is the ID of the project containing the channel you want to debug or monitor. For example, my-project.
Click Run query.

For more information about the Logs Explorer, see Logs Explorer Overview and Using the Logs Explorer.

gcloud

The gcloud command-line tool provides a command-line interface to Cloud Logging.

To view the channel_activities logs for your project, run the following command:

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

where PROJECT_ID is the ID for your Google Cloud project.

For more information about using the gcloud tool with Cloud Logging, see gcloud logging.

Use platform logs

This section describes how to use and interpret specific platform logs for Live Stream API.

StreamingStateChange

StreamingStateChange logs are generated when a channel's streaming state changes. The severity level of a StreamingStateChange log is ERROR when the channel's new state is STREAMING_ERROR. Otherwise, the severity level of a StreamingStateChange log is INFO.

The following is an example of a StreamingStateChange log where the previous state is STREAMING_ERROR and the new state is 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"
  ...
}

You can add additional commands in the Logs Explorer Query field to narrow down the displayed logs.

Add the following command to display all StreamingStateChange logs where the new state is STREAMING:

jsonPayload.streamingStateChange.newState="STREAMING"

Add the following command to display only StreamingStateChange logs:

jsonPayload.streamingStateChange.newState:*

StreamingError

StreamingError logs are generated when a channel encounters a streaming-related error. The log severity level of a StreamingError log is ERROR.

The following is an example of a StreamingError log where Live Stream API was denied permission to upload output files to the specified Cloud Storage bucket:

{
  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 GCS bucket "STORAGE_BUCKET_NAME""
  ...
  severity: "ERROR"
  ...
}

This error may also occur if the specified Cloud Storage bucket does not exist.

If streamingError.message displays the message This is due to an internal error. If the error persists, please contact support team, copy the log's contents and send it to the support team for troubleshooting.

InputAccept

InputAccept logs are generated when an input stream is successfully connected to the Live Stream API input endpoint. The severity level of InputAccept logs is INFO.

The InputStreamProperty field in an InputAccept log includes the following information about the video and audio sub-streams of the input stream:

Video streams	index codec frame rate resolution
Audio streams	index channel count channel layout codec information

You can use InputAccept logs to verify the format and acceptance status of the input stream:

{
  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"
  ...
}

Add the following command in the Logs Explorer Query field to display only InputAccept logs for a specific stream:

jsonPayload.inputAccept.streamId="STREAM_ID"

where STREAM_ID is the unique identifier for a stream included in the input endpoint URI.

InputError

InputError logs are generated when an input stream is rejected by the Live Stream API. The severity level for an InputError log is ERROR.

The following is an example of a InputError log where an input stream was sent to a channel that has not started yet:

{
  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"
  ...
}

The following is an example of a InputError log where a duplicate input stream was sent to a channel that is already streaming:

{
  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"
  ...
}

Add the following command in the Logs Explorer Query field to display only InputError logs for a specific stream:

jsonPayload.inputError.streamId="STREAM_ID"

where STREAM_ID is the unique identifier for a stream included in the input endpoint URI.

InputDisconnect

InputDisconnect logs are generated when the input streams are disconnected from the Live Stream API. You can use InputDisconnect logs to check for unexpected live stream disconnections. The severity level for an InputDisconnect log is INFO.

The following is an example of an InputDisconnect log:

{
  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"
  ...
}