Como usar registros exportados

Esta página explica como encontrar e usar entradas de registro exportadas no Cloud Storage, no BigQuery e no Pub/Sub.

Para acessar uma visão geral conceitual da exportação de registros usando o Cloud Logging, leia Visão geral da exportação de registros.

Para instruções sobre como exportar registros com o Logging, consulte as páginas a seguir:

Cloud Storage

Para visualizar seus registros exportados 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 sendo usado na exportação de registros.

Para detalhes sobre como os registros são organizados no bucket, vá até Organização do Cloud Storage nesta página.

Disponibilidade de registros exportados

Se não houver registros exportados, verifique as métricas do sistema de exportação. Elas informam quantas entradas de registro são exportadas e quantas são descartadas por causa de erros. Se as métricas do sistema de exportação indicarem que nenhuma entrada de registro foi exportada, verifique a consulta de exportações para ver se as entradas de registro correspondentes à sua consulta chegaram recentemente ao Logging:

Ir para Exportações de registros

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 exportados

Ao exportar 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 referência LogEntry, pode ser um nome simples, como syslog, ou um nome composto, como appengine.googleapis.com/request_log. 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 pode conter registros de vários tipos de recurso.

O Logging 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 deles contém as entradas de registro exportadas para um período de tempo 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

Esses dois arquivos juntos contêm as entradas do registro syslog para todas as instâncias durante a hora que começa às 8h UTC. Os carimbos de data/hora da entrada de registro são mostrados em Tempo Universal Coordenado (UTC, na sigla em inglês).

Para conseguir todas as entradas de registro, é necessário ler todos os fragmentos para cada período de tempo. Neste caso, são os fragmentos 0 e 1 do arquivo. O número de fragmentos gravados pode mudar em 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 uma entrada syslog, vá até Tipo de LogEntry nessa página.

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

Consultas

Para ver exemplos de consultas sobre exportar registros para o Cloud Storage, vá até Consultas de exemplo.

BigQuery

Para visualizar os registros exportados no BigQuery, faça o seguinte:

  1. Vá até a IU 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, vá até Organização da tabela para saber como as tabelas são organizadas e, também, até Como exportar registros e o esquema do BigQuery para saber como os campos da entrada de registro exportada são nomeados.

Disponibilidade de registros exportados

Se não houver registros exportados, verifique as métricas do sistema de exportação. Elas informam quantas entradas de registro são exportadas e quantas são descartadas por causa de erros. Se as métricas do sistema de exportação indicarem que nenhuma entrada de registro foi exportada, verifique a consulta de exportações para ver se as entradas de registro correspondentes à sua consulta chegaram recentemente ao Logging:

Ir para Exportações de registros

Ao ser criada uma nova tabela enquanto o Logging exporta as entradas de registro para o BigQuery, pode levar alguns minutos até que as primeiras entradas de registro apareçam na nova tabela. As entradas de registro posteriores aparecem dentro de um minuto. Para mais informações, leia Organização da tabela abaixo.

Organização da tabela

Quando você exporta registros para um conjunto de dados do BigQuery, o Logging cria tabelas datadas para manter as entradas de registro exportadas. 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 exportados são baseados na estrutura do tipo LogEntry e no conteúdo dos payloads de registro. Para visualizar a tabela de esquema, selecione uma tabela com entradas de registro exportadas para a IU da Web do BigQuery.

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

Consultas

Para ver exemplos de consultas sobre exportação de registros para o BigQuery, vá até Consultas de exemplo.

Para mais informações sobre a sintaxe da consulta do BigQuery, revise 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

Para visualizar os registros exportados conforme eles 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 na exportação de registros e receba uma entrada de registro dela. Talvez seja necessário aguardar a publicação de uma nova entrada de registro.

Para ver detalhes sobre como os registros são organizados, vá até Organização de registros exportados nesta página.

Disponibilidade de registros exportados

Se não houver registros exportados, verifique as métricas do sistema de exportação. Elas informam quantas entradas de registro são exportadas e quantas são descartadas por causa de erros. Se as métricas do sistema de exportação indicarem que nenhuma entrada de registro foi exportada, verifique a consulta de exportações para ver se as entradas de registro correspondentes à sua consulta chegaram recentemente ao Logging:

Ir para Exportações de registros

Ao exportar registros para um tópico Pub/Sub, o Logging publica cada entrada de registro como uma mensagem Pub/Sub assim que receber essa entrada de registro.

Organização de registros exportados

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 da geração de registros com terceiros. Para uma lista atual de integrações, acesse Integrações do pacote de operações do Google Cloud.

É possível exportar registros por meio de um tópico do Pub/Sub para que um terceiro receba esses registros depois de assinar 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. Isso pode ser feito ao configurar um coletor de registros ou conforme os passos a seguir:

    1. Vá até 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. Os registros serão exportados para esse tópico.

      Cada mensagem enviada para o tópico inclui o carimbo de data/hora da entrada de registro exportada nos attributes da mensagem do Pub/Sub. Por exemplo:

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

    4. Autorize o Logging a exportar registros para o tópico. Para ver instruções, vá até Como configurar permissões para o 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. Ele precisa assinar o tópico antes do início da exportação.

  7. Comece a exportar os registros assim que o terceiro tiver assinado o tópico:

    1. No projeto que contém os registros que você quer exportar, clique em Criar exportação acima da caixa de consulta de pesquisa. Isso abre o painel Editar exportação:

      Painel

    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 para iniciar a exportação.

    6. Uma caixa de diálogo Coletor criado é exibida. Indica que o coletor de exportação foi criado com êxito com permissões para gravar registros correspondentes futuros ao destino selecionado.

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

Objetos de entrada de registro

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

Entradas de registro com o mesmo tipo de registro, chamado de [LOG_ID] na referência LogEntry, geralmente têm o mesmo formato. Na tabela a seguir, há exemplos de entradas de registro:

syslog

O syslog do Compute Engine é um tipo de registro personalizado produzido pelo agente do Logging, google-fluentd, 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 exportadas 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. Os fragmentos do arquivo de registro exportado com o sufixo An ("Append") mantêm as entradas de registro que chegaram atrasadas.

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

Além disso, o App Engine combina várias subentradas do tipo google.appengine.logging.v1.LogLine (também chamadas de AppLog ou AppLogLine) em uma entrada de registro principal do tipo google.appengine.logging.v1.RequestLog para a solicitação que causa a atividade de registro. Cada linha de registro tem um "código de solicitação" que identifica a entrada principal. O Visualizador de registros exibe as linhas com a entrada de registro da solicitação. O Logging tenta colocar todas as linhas do registro no lote com a solicitação original, mesmo que elas sejam colocadas no próximo lote pelos carimbos de data/hora. Se isso não for possível, a entrada de registro da solicitação pode ficar sem algumas linhas de registro, e pode haver linhas de registro órfãs sem uma solicitação no próximo lote. Se essa possibilidade for importante para você, prepare-se para reconectar as partes da solicitação quando processar os registros.

Preços

Os registros exportados não estão sujeitos às cobranças do Cloud Logging, mas é possível que haja cobranças de destino. Para detalhes, consulte a página de preços do produto apropriado:

Observe também que, se você enviar e excluir os registros de fluxo da nuvem privada virtual do Cloud Logging, cobranças de geração de registros de fluxo da VPC serão aplicadas além das taxas de destino.