Visualizar registros nos destinos do coletor

Neste documento, explicamos como é possível encontrar entradas de registro roteadas do Cloud Logging para destinos compatíveis:

Destino Frequência de roteamento
Buckets do Cloud Storage Lotes por hora
Tabelas do BigQuery Quase em tempo real
Tópicos do Pub/Sub Quase em tempo real
Buckets do Cloud Logging Quase em tempo real
Splunk Quase em tempo real

Para uma discussão conceitual sobre coletores, consulte Visão geral de roteamento e armazenamento: coletores.

Para instruções sobre como rotear seus registros, consulte Configurar coletores.

Cloud Storage

Para ver os registros roteados no Cloud Storage, faça o seguinte:

  1. Acesse o navegador do Cloud Storage no Console do Cloud:

    Ir para o navegador do Cloud Storage

  2. Selecione o bucket do Cloud Storage que você está usando como destino de roteamento.

Para detalhes sobre como os registros são organizados no bucket do Cloud Storage, consulte Organização do Cloud Storage neste documento.

Frequência de roteamento

As entradas de registro são salvas em lotes a cada hora nos buckets do Cloud Storage. Pode ser necessário aguardar de duas a três horas até que as primeiras entradas comecem a aparecer.

Organização de registros

Quando você roteia registros para um bucket do Cloud Storage, o Logging grava um conjunto de arquivos no bucket.

Eles são organizados em hierarquias de diretório por data e tipo de registro. O tipo de registro, chamado de[LOG_ID] na páginaLogEntry referência, pode ser um nome simples comosyslog ou um nome composto, como appengine.googleapis.com/request_log de dados. Se esses registros fossem armazenados em um bucket chamado my-gcs-bucket, os diretórios seriam nomeados como no exemplo a seguir:

my-gcs-bucket/syslog/YYYY/MM/DD/
my-gcs-bucket/appengine.googleapis.com/request_log/YYYY/MM/DD/

Um único bucket do Cloud Storage pode conter registros de vários tipos de recursos. Cada arquivo tem aproximadamente 3,5 GiB.

A geração de registros não garante a eliminação de duplicação de entradas de registro de coletores que contêm consultas idênticas ou sobrepostas. As entradas de registro desses coletores podem ser gravadas várias vezes em um bucket do Cloud Storage.

Os diretórios de folha (DD/) contêm vários arquivos, cada um com as entradas de registro roteadas para um período especificado no nome do arquivo. Os arquivos são fragmentados e os nomes deles terminam em um número de fragmento, Sn ou An (n=0, 1, 2 ...). Por exemplo, estes são dois arquivos que podem ser armazenados no diretório my-gcs-bucket/syslog/2015/01/13/:

08:00:00_08:59:59_S0.json
08:00:00_08:59:59_S1.json

Juntos, esses dois arquivos contêm as entradas de registro syslog de todas as instâncias durante a hora que começa às 08:00:00 UTC e termina às 8:59:59 UTC. Os carimbos de data/hora da entrada de registro são expressos em UTC (Tempo Universal Coordenado).

As entradas de registro que chegam com um receiveTimestamp dentro da janela alinhada de 60 minutos de timestamp são gravadas nos arquivos de fragmento principal. Por exemplo, uma entrada de registro com timestamp de 08:00:00 e receiveTimestamp de 08:10:00 é armazenada no arquivo de fragmento principal.

Esses arquivos incluem um fragmento principal numerado no sufixo: _Sn.json.

As entradas de registro que chegam com um timestamp em uma janela alinhada de 60 minutos diferente da receiveTimestamp são gravadas em arquivos de fragmento de adendo. Por exemplo, uma entrada de registro com timestamp de 08:00:00 e receiveTimestamp de 09:10:00 é armazenada em um arquivo de fragmento de adendo.

Esses arquivos incluem um fragmento de adendo numerado com o sufixo: _An.json:Unix_timestamp.

Por exemplo, uma entrada de registro que tem um timestamp entre 08:00:00 e 08:59:59, mas uma receiveTimestamp em uma janela alinhada de 60 minutos diferente é gravada em um arquivo. pelo sufixo _An.json:Unix_timestamp, em que o carimbo de data/hora Unix identifica o horário em que o arquivo foi roteado para o Cloud Storage. Se uma entrada de registro teve um timestamp de 08:50:00 e um receiveTimestamp de 09:10:00 e foi roteada às 9h15:00 de 25 de março de 2021, o arquivo do adendo seria escrito da seguinte maneira:

08:00:00_08:59:59_A0.json:1616681700

Para conseguir todas as entradas de registro, você lerá todos os fragmentos para cada período de tempo. Neste caso, são os fragmentos do arquivo 0 e 1. O número de fragmentos de arquivos gravados pode mudar para cada período, dependendo do volume de entradas de registro.

Nos arquivos fragmentados individuais, as entradas de registro são armazenadas como uma lista de objetos LogEntry. Para ver um exemplo de entrada syslog, consulte Tipo LogEntry neste documento.

A ordem de classificação das entradas de registro nos arquivos não é uniforme nem garantida de outra forma.

Filtros

Para exemplos de filtros para roteamento de registros no Cloud Storage, consulte Amostra de consultas.

BigQuery

Para ver os registros roteados no BigQuery, faça o seguinte:

  1. Acesse a página do BigQuery no Console do Cloud:

    Ir para o BigQuery

  2. Selecione o conjunto de dados usado como o destino do coletor.

  3. Selecione uma das tabelas desse conjunto. Você encontra as entradas de registro na guia Detalhes. Também é possível consultar a tabela para retornar os dados.

Para mais informações, consulte Organização da tabela para saber como as tabelas são organizadas e Como exportar registros e o esquema do BigQuery para saber como o registro roteado campos de entrada são nomeados.

Frequência de roteamento

Quando uma nova tabela é criada à medida que o Logging encaminha as entradas de registro para o BigQuery, pode levar vários minutos para que as primeiras entradas apareçam na nova tabela. As entradas de registro posteriores aparecem dentro de um minuto.

Organização da tabela

Quando você encaminha registros para um conjunto de dados do BigQuery, o Logging cria tabelas datadas para armazenar as entradas de registro roteadas. As entradas de registro são colocadas em tabelas, que são nomeadas com base nos nomes e nos carimbos de data/hora das entradas de registro1. Na tabela a seguir, há exemplos de como os nomes de registro e os carimbos de data/hora são mapeados para nomes de tabela:

Nome do registro Carimbo de data/hora da entrada de registro1 Nome da tabela do BigQuery
syslog 2017-05-23T18:19:22.135Z syslog_20170523
apache-access 2017-01-01T00:00:00.000Z apache_access_20170101
compute.googleapis.com/activity_log 2017-12-31T23:59:59.999Z compute_googleapis_com_activity_log_20171231

1 Os carimbos de data/hora da entrada de registro são mostrados em UTC (Tempo Universal Coordenado).

Esquemas e campos

Os esquemas de tabela do BigQuery para registros roteados são baseados na estrutura do LogEntry e no conteúdo dos payloads de registro. É possível visualizar o esquema da tabela selecionando uma tabela com entradas de registro roteadas na IU da Web do BigQuery.

O esquema da tabela do BigQuery usado para representar payloads de entradas de registro complexos pode ser confuso e, no caso de registros de auditoria roteados, algumas regras de nomenclatura especiais são usadas. Para mais informações, consulte Esquema do BigQuery para registros exportados.

Consultas

Para ver exemplos de consultas para roteamento de registros no BigQuery, veja Amostra de consultas.

Para mais informações sobre a sintaxe da consulta do BigQuery, consulte a Referência de consulta. São especialmente úteis as Funções de caracteres curinga de tabela, que permitem fazer consultas em várias tabelas e o Operador de nivelamento, que permite exibir dados de campos repetidos.

Amostra de consulta de registros do Compute Engine

A seguinte consulta do BigQuery recupera entradas de registro de vários dias e tipos:

  • A consulta pesquisa os últimos três dias dos registros syslog e apache-access. Ela foi feita em 23 de fevereiro de 2015 e abrange todas as entradas de registro recebidas entre os dias 21 e 22, além daquelas recebidas no dia 23, até o momento em que a consulta foi emitida.

  • A consulta recupera resultados de uma única instância do Compute Engine, 1554300700000000000.

SELECT
  timestamp AS Time,
  logName as Log,
  textPayload AS Message
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.syslog_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())),
  (TABLE_DATE_RANGE(my_bq_dataset.apache_access_,
    DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP()))
WHERE
  resource.type == 'gce_instance'
  AND resource.labels.instance_id == '1554300700000000000'
ORDER BY time;

Veja alguns exemplos de linhas de resultado:

Row | Time                    | Log                                         | Message
--- | ----------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------
 5  | 2015-02-21 03:40:14 UTC | projects/project-id/logs/syslog             | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269;
 6  | 2015-02-21 04:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 7  | 2015-02-21 04:49:58 UTC | projects/project-id/logs/apache-access      | 128.61.240.66 - - [21/Feb/2015:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)"
 8  | 2015-02-21 05:17:01 UTC | projects/project-id/logs/syslog             | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly)
 9  | 2015-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2015:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"

Amostra de consulta de registros do App Engine

A seguinte consulta do BigQuery recupera solicitações do App Engine que não foram bem-sucedidas no último mês:

SELECT
  timestamp AS Time,
  protoPayload.host AS Host,
  protoPayload.status AS Status,
  protoPayload.resource AS Path
FROM
  (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_,
    DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP()))
WHERE
  protoPayload.status != 200
ORDER BY time

Veja alguns dos resultados:

Row | Time                    | Host                                  | Status | Path
--- | ----------------------- | ------------------------------------- | ------ | ------
 6  | 2015-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo?thud=3
 7  | 2015-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com |    404 | /foo
 8  | 2015-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com         |    404 | /favicon.ico
 9  | 2015-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com         |    404 | /foo?thud=%22what???%22

Pub/Sub

Recomendamos o uso do Pub/Sub para integrar registros do Cloud Logging a softwares de terceiros.

Os registros roteados para o Pub/Sub geralmente estão disponíveis em segundos, com 99% dos registros disponíveis em menos de 60 segundos.

Para ver os registros roteados à medida que são transmitidos por meio do Pub/Sub, faça o seguinte:

  1. Vá até a página Pub/Sub no Console do Cloud:

    Ir para o Pub/Sub

  2. Encontre ou crie uma assinatura no tópico usado no coletor de registros e extraia uma entrada delas. Talvez seja necessário aguardar a publicação de uma nova entrada de registro.

Para detalhes sobre como os registros são organizados no Pub/Sub, consulte Organização de registros neste documento.

Frequência de roteamento

Quando você roteia registros para um tópico do Pub/Sub, o Logging publica cada entrada de registro como uma mensagem do Pub/Sub assim que ele recebe essa entrada.

Organização de registros

O campo data de cada mensagem é um objeto LogEntry codificado em base64. Por exemplo, um assinante do Pub/Sub pode receber o seguinte objeto de um tópico que está recebendo entradas de registro. O objeto mostrado contém uma lista com uma única mensagem, embora o Pub/Sub possa retornar várias mensagens se várias entradas de registro estiverem disponíveis. O valor data (cerca de 600 caracteres) e o valor ackId (cerca de 200 caracteres) foram reduzidos para facilitar a leitura do exemplo:

{
 "receivedMessages": [
  {
   "ackId": "dR1JHlAbEGEIBERNK0EPKVgUWQYyODM...QlVWBwY9HFELH3cOAjYYFlcGICIjIg",
   "message": {
    "data": "eyJtZXRhZGF0YSI6eyJzZXZ0eSI6Il...Dk0OTU2G9nIjoiaGVsbG93b3JsZC5sb2cifQ==",
    "attributes": {
     "compute.googleapis.com/resource_type": "instance",
     "compute.googleapis.com/resource_id": "123456"
    },
    "messageId": "43913662360"
   }
  }
 ]
}

Ao decodificar o campo data e formatá-lo, você recebe o seguinte objeto LogEntry:

{
  "log": "helloworld.log",
  "insertId": "2015-04-15|11:41:00.577447-07|10.52.166.198|-1694494956",
  "textPayload": "Wed Apr 15 20:40:51 CEST 2015 Hello, world!",
  "timestamp": "2015-04-15T18:40:56Z",
  "labels": {
    "compute.googleapis.com\/resource_type": "instance",
    "compute.googleapis.com\/resource_id": "123456"
  },
  "severity": "WARNING"
  }
}

Integração de terceiros ao Pub/Sub

O Logging é compatível com a integração de registros com terceiros, como o Splunk. Veja uma lista atual de integrações na seção Parceiros das integrações de pacotes de operações do Google Cloud.

Você roteia seus registros por meio de um tópico do Pub/Sub, e os terceiros recebem seus registros assinando o mesmo tópico.

Para realizar a integração, faça o seguinte:

  1. Solicite ao terceiro um nome de conta de serviço do Google Cloud criado a partir do projeto do Google Cloud dele. Por exemplo, 12345-xyz@developer.gserviceaccount.com. Use esse nome para permitir que o terceiro receba os registros.

  2. No seu projeto que contém os registros,

  3. Ative a API Pub/Sub.

    Ative a API

  4. Crie um tópico do Pub/Sub. Faça isso ao configurar um coletor de registros ou siga estes passos:

    1. Acesse a lista de tópicos do Pub/Sub.
    2. Selecione Criar tópico e digite um nome. Por exemplo, projects/my-project-id/topics/my-pubsub-topic. Você roteará seus registros para esse tópico.

      Cada mensagem enviada ao tópico inclui o carimbo de data/hora da entrada de registro roteada na mensagem attributes do Pub/Sub: por exemplo:

      "attributes": {
        "logging.googleapis.com/timestamp": "2018-10-01T00:00:00Z"
      }
      
    3. Clique em Criar.

    4. Autorize o Logging a fim de rotear registros para o tópico. Para instruções, consulte Como definir permissões para Pub/Sub.

  5. Autorize o terceiro a assinar o tópico:

    1. Permaneça na lista de tópicos do Pub/Sub do seu projeto no Console do Cloud.
    2. Selecione o novo tópico.
    3. Selecione Permissões.
    4. Digite o nome da conta de serviço do terceiro.
    5. No menu Selecionar uma função, escolha Assinante do Pub/Sub.
    6. Clique em Adicionar.
  6. Informe o nome do tópico do Pub/Sub ao terceiro. Por exemplo, projects/my-project-number/topics/my-pubsub-topic. Eles devem se inscrever no tópico antes de você iniciar o roteamento.

  7. Comece a rotear os registros assim que o terceiro se inscrever no tópico:

    1. No projeto que contém os registros que você quer rotear, clique em Criar exportação acima da caixa de consulta de pesquisa. O painel Editar exportação será aberto.
    2. Insira um Nome do coletor.
    3. No menu Serviço do coletor, selecione Cloud Pub/Sub.
    4. No menu Destino do coletor, selecione o tópico do Pub/Sub que o terceiro assinou.
    5. Selecione Criar coletor.
    6. Uma caixa de diálogo com a mensagem Sink created será exibida. Essa mensagem indica que o coletor foi criado com sucesso com permissões para gravar registros correspondentes futuros no destino selecionado.

O terceiro começa a receber as entradas de registro de imediato.

Para uma exploração de cenários comuns de roteamento de registros usando o Pub/Sub, consulte Padrões de design para roteamento no Cloud Logging: cenários de exportação de registros.

Cloud Logging

Os buckets de registros são contêineres de armazenamento do Cloud Logging nos projetos do Google Cloud que contêm os dados de registros. É possível criar coletores de registros para rotear todos os registros ou apenas um subconjunto deles para qualquer bucket no Cloud Logging. Essa flexibilidade permite escolher em qual projeto do Cloud seus registros serão armazenados e quais outros registros serão armazenados com eles.

Para instruções sobre como criar e listar os buckets de registros associados ao projeto do Cloud, consulte Como gerenciar buckets.

Organização das entradas de registro

As entradas de registro do Logging são objetos do tipo LogEntry.

Entradas de registro com o mesmo tipo de registro, chamadas de [LOG_ID] na referência LogEntry, geralmente têm o mesmo formato. A tabela a seguir apresenta amostras de entradas de registro:

syslog

O Compute Engine syslog é um tipo de registro personalizado produzido pelo agente de geração de registros google-fluentd, que é executado em instâncias de máquina virtual:

{
  logName: "projects/my-gcp-project-id/logs/syslog",
  timestamp: "2015-01-13T19:17:01Z",
  resource: {
    type: "gce_instance",
    labels: {
      instance_id: "12345",
      zone: "us-central1-a",
      project_id: "my-gcp-project-id"
    }
  },
  insertId: "abcde12345",
  textPayload: "Jan 13 19:17:01 my-gce-instance /USR/SBIN/CRON[29980]: (root) CMD (   cd / && run-parts --report /etc/cron.hourly)"
}

request_log

O App Engine request_log tem entradas de registro que contêm protoPayload campos com objetos do tipo RequestLog:

{
  logName: "projects/my-gcp-project-id/logs/appengine.googleapis.com%2Frequest_log",
  timestamp: "2015-01-13T19:00:39.796169Z",
  resource: {
    type: "gae_app",
    labels: {
      module_id: "default",
      zone: "us6",
      project_id: "my-gcp-project-id",
      version_id: "20150925t173233"
    }
  }
  httpRequest: {
    status: 200
  }
  insertId: "abcde12345",
  operation: {
    id: "abc123",
    producer: "appengine.googleapis.com/request_id",
    first: true,
    last: true
  }
  protoPayload: {
    @type: "type.googleapis.com/google.appengine.logging.v1.RequestLog"
    versionId: "20150925t173233",
    status: 200,
    startTime: "2017-01-13T19:00:39.796169Z",
    # ...
    appId: "s~my-gcp-project-id",
    appEngineRelease: "1.9.17",
  }
}

activity

O registro activity é um registro de auditoria das atividades do administrador. O payload dele é uma representação JSON do tipo AuditLog:

{
 logName: "projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity"
 timestamp: "2017-04-22T13:41:32.245Z"
 severity: "NOTICE"
 resource: {
  type: "gce_instance"
  labels: {
   instance_id: "2403273232180765234"
   zone: "us-central1-b"
   project_id: "my-gcp-project-id"
  }
 }
 insertId: "54DC1882F4B49.A4996C2.6A02F4C1"
 operation: {
  id: "operation-1492868454262-54dc185e9a4f0-249fe233-f73d472a"
  producer: "compute.googleapis.com"
  last: true
 }
 protoPayload: {
  @type: "type.googleapis.com/google.cloud.audit.AuditLog"
  authenticationInfo: {
   principalEmail: "649517127304@cloudservices.gserviceaccount.com"
  }
  requestMetadata: {…}
  serviceName: "compute.googleapis.com"
  methodName: "v1.compute.instances.delete"
  resourceName: "projects/my-gcp-project-id/zones/us-central1-b/instances/abc123"
 }
}

Entradas de registro atrasadas

As entradas de registro encaminhadas são salvas em buckets por hora do Cloud Storage. Pode levar de 2 a 3 horas para que as primeiras entradas comecem a aparecer. Os fragmentos do arquivo de registros roteado com o sufixo An ("Acrescentar") contêm as entradas de registro que chegaram com atraso.

Se o destino sofrer uma interrupção, o Cloud Logging armazenará os dados em buffer até que a interrupção termine.

Se não houver registros no destino do coletor, verifique as métricas do sistema de exportação. As métricas do sistema de exportação indicam quantas entradas de registro são roteadas e quantas são descartadas devido a erros. Se as métricas do sistema de exportação indicarem que nenhuma entrada de registro foi encaminhada para o destino, verifique o filtro para verificar se as entradas de registro correspondentes ao filtro chegaram recentemente ao Logging:

Acessar o roteador de registros

Entradas de registro do App Engine

O App Engine combina várias subentradas do tipo google.appengine.logging.v1.LogLine (também chamado AppLog ou AppLogLine) em uma entrada de registro principal do tipo google.appengine.logging.v1.RequestLog para a solicitação que causa a atividade do registro. Cada linha de registro tem um "ID de solicitação" que identifica a entrada principal. O Explorador de registros exibe as linhas com a entrada de registro da solicitação. O Logging tenta colocar todas as linhas de registro no lote com a solicitação original, mesmo que os carimbos de data/hora as coloquem no próximo lote. Se isso não for possível, a entrada de registro da solicitação poderá estar sem algumas linhas de registro e poderá haver linhas "órfãs" sem uma solicitação no próximo lote. Se essa possibilidade for importante para você, esteja preparado para reconectar as partes da solicitação ao processar seus registros.

Solução de problemas

Se os registros estiverem ausentes no destino do coletor, será possível visualizar as métricas logging.googleapis.com/exports/ para verificar o número de entradas de registro enviadas pelo coletor:

  • exports/byte_count: número de bytes em entradas de registro que foram roteadas.
  • exports/log_entry_count: número de entradas de registro que foram roteadas.
  • exports/error_count: número de entradas de registro que não foram roteadas.

As métricas têm rótulos que registram as contagens por nome do coletor e nome do destino e informam se o coletor está roteando dados de registros com sucesso ou não. Para detalhes sobre como visualizar métricas, consulte Como visualizar métricas com base em registros.

Se você suspeitar que seu coletor não esteja roteando registros corretamente, consulte Solução de problemas de roteamento e coletores.

Preços

O Cloud Logging não cobra pela rota de registros, mas a cobrança de destino pode ser aplicada. Para mais detalhes, consulte os preços do serviço apropriado:

Se você enviar e depois excluir seus registros de fluxo de nuvem privada virtual do Cloud Logging, as cobranças de geração de registros de fluxo de VPC serão aplicadas além das cobranças de destino.