This page describes how to use platform logs generated by Live Stream API as
part of [Cloud Logging](https://docs.cloud.google.com/logging/docs.md.txt). Live Stream API uses the Logging API service name
[`livestream.googleapis.com`](https://docs.cloud.google.com/logging/docs/api/platform-logs.md.txt#live_stream_api) to log channel-related activity.

## Before you begin

- Make sure you have the correct [IAM permissions and roles](https://docs.cloud.google.com/logging/docs/access-control.md.txt#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.

> [!WARNING]
> **Warning:** Using Cloud Logging [incurs charges to your project](https://docs.cloud.google.com/stackdriver/pricing). Enable platform logs only when necessary to debug and troubleshoot issues, and disable platform logs when you no longer need them.

To activate the logs, add the following field to the request JSON body of the
[`projects.locations.channels.create`](https://docs.cloud.google.com/livestream/docs/reference/rest/v1/projects.locations.channels/create.md.txt) or the
[`projects.locations.channels.patch`](https://docs.cloud.google.com/livestream/docs/reference/rest/v1/projects.locations.channels/patch.md.txt) method:

<br />

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

<br />

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](https://docs.cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry.md.txt#logseverity).

## View platform logs

To view platform logs, follow the instructions below:

### Console

To view platform logs in the Google Cloud console:

1. Navigate to the Logs Explorer:

   [Go to the Logs Explorer](https://console.cloud.google.com/logs/query)
2. Select the appropriate Google Cloud project.

3. 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`.

4. Click **Run query**.

For more information about the Logs Explorer, see
[Logs Explorer Overview](https://docs.cloud.google.com/logging/docs/view/logs-explorer-summary) and [Using the Logs Explorer](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface.md.txt).

### 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`](https://docs.cloud.google.com/sdk/gcloud/reference/logging.md.txt).

## Use platform logs

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

### eventStateChange

`eventStateChange` logs are generated when a channel event's state
changes. The severity level of a `eventStateChange` log is `ERROR` when the
channel event's new state is `FAILED`. Otherwise, the severity level of a
`eventStateChange` log is `INFO`.

The following is an example of an `eventStateChange` log:

```
{
  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

`scte35CommandReceived` logs are generated when the input stream receives an
SCTE35 command. The severity level for an `scte35CommandReceived` log is `INFO`.

Only `durationFlag`, `breakDuration`, `spliceTime`, and `outOfNetworkIndicator`
are processed. When `spliceTime` is missing, the SCTE35 command is executed
immediately. All other fields are treated as no-ops.

The following is an example of an `scte35CommandReceived` log:

```
{
  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` 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`](https://docs.cloud.google.com/apis/design/errors).

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 Cloud Storage 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](https://docs.cloud.google.com/support-hub) 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 <var translate="no">`STREAM_ID`</var> is the unique identifier for a stream included in the [input
endpoint URI](https://docs.cloud.google.com/livestream/docs/overview#input_endpoints).

### 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`](https://docs.cloud.google.com/apis/design/errors).

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 <var translate="no">`STREAM_ID`</var> is the unique identifier for a stream included in the [input
endpoint URI](https://docs.cloud.google.com/livestream/docs/overview#input_endpoints).

### 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"
  ...
}
```