Como usar registros da plataforma

Esta página descreve como usar os registros da plataforma gerados pela API Live Stream como parte do Cloud Logging. A API Live Stream usa o nome do serviço da API Logging livestream.googleapis.com para registrar atividades relacionadas ao canal.

Antes de começar

Ativar a geração de registros da plataforma

Por padrão, os registros da plataforma livestream.googleapis.com/channel_activities para a API Live Stream ficam desativados. Para ativar os registros, especifique um nível de gravidade ao criar ou atualizar o recurso do canal.

Para ativar os registros, adicione o seguinte campo ao corpo JSON da solicitação do método projects.locations.channels.create ou projects.locations.channels.patch:

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

em que SEVERITY_LEVEL é um dos seguintes:

  • OFF
  • DEBUG
  • INFO
  • WARNING
  • ERROR

Depois de escolher um nível de gravidade de registro para um canal, apenas os registros da plataforma com um nível de gravidade maior ou igual ao escolhido serão registrados. Por exemplo, se o nível de gravidade for WARNING, apenas os registros com nível de gravidade WARNING e ERROR serão registrados. Se o nível de gravidade for INFO, os registros de todos os níveis de gravidade, exceto DEBUG, serão registrados.

Para mais informações sobre os níveis de gravidade de registro, consulte LogSeverity.

Conferir os registros da plataforma

Para conferir os registros da plataforma, siga as instruções abaixo:

Console

Para conferir os registros da plataforma no console do Google Cloud:

  1. Acesse o Explorador de registros:

    Acesse o Explorador de registros

  2. Selecione o projeto do Google Cloud apropriado.

  3. No campo Consulta, digite o seguinte comando de consulta:

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

    em que:

    • CHANNEL_ID é o ID do canal que você quer depurar ou monitorar. Por exemplo, my-channel.

    • LOCATION é o local do canal que você quer depurar ou monitorar. Por exemplo, us-central1.

    • PROJECT_ID é o ID do projeto que contém o canal que você quer depurar ou monitorar. Por exemplo, my-project.

  4. Clique em Executar consulta.

Para mais informações sobre o Explorador de registros, consulte Visão geral do Explorador de registros e Como usar o Explorador de registros.

gcloud

A ferramenta de linha de comando gcloud fornece uma interface de linha de comando para o Cloud Logging.

Para conferir os registros channel_activities do seu projeto, execute o seguinte comando:

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

em que PROJECT_ID é o ID do projeto do Google Cloud.

Para mais informações sobre como usar a ferramenta gcloud com o Cloud Logging, consulte gcloud logging.

Usar registros da plataforma

Esta seção descreve como usar e interpretar registros de plataforma específicos para a API Live Stream.

eventStateChange

Os registros eventStateChange são gerados quando o estado de um evento do canal muda. O nível de gravidade de um registro eventStateChange é ERROR quando o novo estado do evento do canal é FAILED. Caso contrário, o nível de gravidade de um registro eventStateChange será INFO.

Confira a seguir um exemplo de registro 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

Os registros scte35CommandReceived são gerados quando o fluxo de entrada recebe um comando SCTE35. O nível de gravidade de um registro scte35CommandReceived é INFO.

Somente durationFlag, breakDuration, spliceTime e outOfNetworkIndicator são processados. Quando spliceTime está ausente, o comando SCTE35 é executado imediatamente. Todos os outros campos são tratados como não-operações.

Confira a seguir um exemplo de registro 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

Os registros streamingStateChange são gerados quando o estado de streaming de um canal muda. O nível de gravidade de um registro streamingStateChange é ERROR quando o novo estado do canal é STREAMING_ERROR. Caso contrário, o nível de gravidade de um registro streamingStateChange será INFO.

Confira a seguir um exemplo de registro streamingStateChange em que o estado anterior é STREAMING_ERROR e o novo é 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"
  ...
}

É possível adicionar outros comandos no campo Consulta do Logs Explorer para restringir os registros exibidos.

Adicione o comando a seguir para mostrar todos os registros streamingStateChange em que o novo estado é STREAMING:

jsonPayload.streamingStateChange.newState="STREAMING"

Adicione o seguinte comando para mostrar apenas os registros streamingStateChange:

jsonPayload.streamingStateChange.newState:*

streamingError

Os registros streamingError são gerados quando um canal encontra um erro relacionado ao streaming. O nível de gravidade de um registro streamingError é ERROR.

Confira a seguir um exemplo de um registro streamingError em que a API Live Stream teve a permissão negada para fazer upload de arquivos de saída para o bucket do Cloud Storage especificado:

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

Esse erro também pode ocorrer se o bucket do Cloud Storage especificado não existir.

Se streamingError.message mostrar a mensagem This is due to an internal error. If the error persists, please contact support team, copie o conteúdo do registro e envie para a equipe de suporte para solucionar o problema.

inputAccept

Os registros inputAccept são gerados quando um fluxo de entrada é conectado ao endpoint de entrada da API Live Stream. O nível de gravidade dos registros inputAccept é INFO.

O campo inputStreamProperty em um registro inputAccept inclui as seguintes informações sobre os subfluxos de vídeo e áudio do fluxo de entrada:

Streams de vídeo
  • index
  • codec
  • frame rate
  • resolução
Streams de áudio
  • index
  • contagem de canais
  • layout do canal
  • informações do codec

É possível usar os registros inputAccept para verificar o formato e o status de aceitação do fluxo de entrada:

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

Adicione o comando a seguir no campo Consulta do Explorador de registros para mostrar apenas os registros inputAccept de um fluxo específico:

jsonPayload.inputAccept.streamId="STREAM_ID"

em que STREAM_ID é o identificador exclusivo de um stream incluído no URI do endpoint de entrada.

inputError

Os registros inputError são gerados quando um fluxo de entrada é rejeitado pela API Live Stream. O nível de gravidade de um registro inputError é ERROR.

Confira a seguir um exemplo de registro inputError em que um stream de entrada foi enviado a um canal que ainda não foi iniciado:

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

Confira a seguir um exemplo de registro inputError em que um stream de entrada duplicado foi enviado para um canal que já está em 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"
  ...
}

Adicione o comando a seguir no campo Consulta do Explorador de registros para mostrar apenas registros inputError de uma transmissão específica:

jsonPayload.inputError.streamId="STREAM_ID"

em que STREAM_ID é o identificador exclusivo de um stream incluído no URI do endpoint de entrada.

inputDisconnect

Os registros inputDisconnect são gerados quando os fluxos de entrada são desconectados da API Live Stream. É possível usar os registros inputDisconnect para verificar desconexões inesperadas de transmissões ao vivo. O nível de gravidade de um registro inputDisconnect é INFO.

Confira a seguir um exemplo de registro 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"
  ...
}