Como gerar e visualizar registros

Nesta página, descrevemos os registros disponíveis ao usar o Cloud Run e como visualizá-los e gravá-los.

O Cloud Run tem dois tipos de registros, que são enviados automaticamente para o Cloud Logging:

• Registros de solicitação (somente serviços): registros de solicitações enviadas para os serviços do Cloud Run. Esses registros são criados automaticamente.
• Registros de contêiner (serviços e jobs): registros emitidos pelas instâncias, normalmente do próprio código, gravados em locais compatíveis, conforme descrito em Como gravar registros de contêiner.

Ler registros

É possível ver registros do serviço ou job de várias maneiras:

• Usar a página do Cloud Run no console do Google Cloud
• Usando a CLI do Google Cloud CL para ver registros pela gcloud (apenas serviços)
• Usar o Explorador de registros do Cloud Logging no Console do Google Cloud
• Usar o Cloud Code

Os dois métodos de console da visualização de registros examinam os mesmos registros armazenados no Cloud Logging, mas o explorador de registros do Cloud Logging fornece mais detalhes e mais recursos de filtragem.

Ver registros no Cloud Run

É possível ver registros de serviços e jobs nas páginas de serviço e jobs correspondentes.

Ver registros de um serviço

Para visualizar os registros na página do Cloud Run, siga estas etapas:

1. Acesse o Cloud Run

2. Clique no serviço de sua escolha na lista exibida.

3. Clique na guia REGISTROS para receber os registros de solicitação e contêiner para todas as revisões desse serviço. É possível filtrar por nível de gravidade de registro.

Ver registros de um job

Para visualizar os registros na página do Cloud Run, siga estas etapas:

1. Acesse o Cloud Run

2. Clique na guia JOBS.

3. Localize o job na lista e clique nele.

4. Clique na guia REGISTROS para acessar os registros do contêiner de todas as execuções desse job. É possível filtrar por nível de gravidade de registro.

5. Como alternativa, se você quiser ver os registros pré-filtrados de uma execução de job específica, clique na execução do job e na guia REGISTROS.

Ver registros de serviços usando a Google Cloud CLI

Visualização — Command-line logging for Cloud Run services

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

É possível usar a Google Cloud CLI para visualizar os registros de cauda ou ler os registros de um serviço do Cloud Run na linha de comando Por padrão, os registros são formatados em uma linha e otimizados para o console.

Para acompanhar os registros, instale o componente log-streaming na Google Cloud CLI. Se o componente não estiver instalado, você vai receber uma solicitação para instalá-lo quando necessário.

Ver os registros de cauda na linha de comando

Para um serviço do Cloud Run, é possível acompanhar os registros do serviço do Cloud Run em tempo real diretamente na linha de comando:

gcloud beta run services logs tail SERVICE --project PROJECT-ID

Substituir

• SERVICE pelo nome do serviço do Cloud Run.
• PROJECT-ID pelo ID do projeto do Google Cloud. Para ver o ID do projeto, execute o comando gcloud config get-value project.

Ler registros na linha de comando

Para um serviço do Cloud Run, é possível ler os registros de duas maneiras:

• Em um formato otimizado para o console:

  gcloud beta run services logs read SERVICE --limit=10 --project PROJECT-ID
  

• Diretamente do Cloud Logging:

  gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project PROJECT-ID --limit 10

Substituir

• SERVICE pelo nome do serviço do Cloud Run.
• PROJECT-ID pelo ID do projeto do Google Cloud. Para ver o ID do projeto, execute o comando gcloud config get-value project.

Ver registros no Cloud Logging

Para ver os registros do Cloud Run no Explorador de registros do Cloud Logging:

1. Acesse o Explorador de registros no Console do Google Cloud:

   Acessar a página Explorador de registros

2. Selecione um projeto atual do Google Cloud na parte superior da página ou crie um novo.

3. Usando os menus suspensos, selecione o recurso Revisão do Cloud Run para um serviço ou Job do Cloud Run para um job.

Para mais informações, consulte Como usar o Explorador de registros.

Ver os registros de serviços no Cloud Code

Para visualizar registros no Cloud Code, leia os guias do IntelliJ e do Visual Studio Code.

Ler registros de maneira programática

Se você quiser ler os registros de maneira programática, use um destes métodos:

• Use um coletor de registros para o Pub/Sub e um script para receber do Pub/Sub.
• Chame a API Logging usando as bibliotecas de cliente da linguagem de programação sendo usada.
• Chame diretamente os endpoints da API REST do Logging.

Gravar registros de contêiner

Quando você grava registros do serviço ou job, eles são coletados automaticamente pelo Cloud Logging, desde que os registros sejam gravados em qualquer um dos seguintes locais:

• Streamings de saída padrão (stdout) ou de erro padrão (stderr)
• Todos os arquivos no diretório /var/log
• syslog (/dev/log)
• Registros gravados usando as bibliotecas de cliente do Cloud Logging, disponíveis para muitas linguagens conhecidas

Espera-se que a maioria dos desenvolvedores grave registros usando a saída e o erro padrão.

Os registros de contêiner gravados nesses locais compatíveis são associados automaticamente ao serviço, à revisão e ao local do Cloud Run ou ao job do Cloud Run. As exceções contidas nos registros são capturadas e informadas no Error Reporting.

Como usar texto simples ou JSON estruturado nos registros

Ao gravar registros, é possível enviar uma string de texto simples ou uma única linha de JSON serializado, também chamado de dados "estruturados". Ela é selecionada e analisada pelo Cloud Logging e colocada em jsonPayload. Por outro lado, a mensagem de texto simples é colocada em textPayload.

Gravar registros estruturados

O snippet a seguir mostra como gravar entradas de registro estruturadas. Ele também mostra como correlacionar mensagens de registro com o registro de solicitação correspondente.

Node.js

// Uncomment and populate this variable in your code:
// const project = 'The project ID of your function or Cloud Run service';

// Build structured log messages as an object.
const globalLogFields = {};

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// (This only works for HTTP-based invocations where `req` is defined.)
if (typeof req !== 'undefined') {
  const traceHeader = req.header('X-Cloud-Trace-Context');
  if (traceHeader && project) {
    const [trace] = traceHeader.split('/');
    globalLogFields['logging.googleapis.com/trace'] =
      `projects/${project}/traces/${trace}`;
  }
}

// Complete a structured log entry.
const entry = Object.assign(
  {
    severity: 'NOTICE',
    message: 'This is the default display field.',
    // Log viewer accesses 'component' as 'jsonPayload.component'.
    component: 'arbitrary-property',
  },
  globalLogFields
);

// Serialize to a JSON string and output.
console.log(JSON.stringify(entry));

Python

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

Go

A estrutura de cada entrada de registro é fornecida por um tipo Entry:

// Entry defines a log entry.
type Entry struct {
	Message  string `json:"message"`
	Severity string `json:"severity,omitempty"`
	Trace    string `json:"logging.googleapis.com/trace,omitempty"`

	// Logs Explorer allows filtering and display of this as `jsonPayload.component`.
	Component string `json:"component,omitempty"`
}

// String renders an entry structure to the JSON format expected by Cloud Logging.
func (e Entry) String() string {
	if e.Severity == "" {
		e.Severity = "INFO"
	}
	out, err := json.Marshal(e)
	if err != nil {
		log.Printf("json.Marshal: %v", err)
	}
	return string(out)
}

Quando uma estrutura de entrada é registrada, o método String é chamado para organizá-la no formato JSON esperado pelo Cloud Logging:

func init() {
	// Disable log prefixes such as the default timestamp.
	// Prefix text prevents the message from being parsed as JSON.
	// A timestamp is added when shipping logs to Cloud Logging.
	log.SetFlags(0)
}

func indexHandler(w http.ResponseWriter, r *http.Request) {
	// Uncomment and populate this variable in your code:
	// projectID = "The project ID of your Cloud Run service"

	// Derive the traceID associated with the current request.
	var trace string
	if projectID != "" {
		traceHeader := r.Header.Get("X-Cloud-Trace-Context")
		traceParts := strings.Split(traceHeader, "/")
		if len(traceParts) > 0 && len(traceParts[0]) > 0 {
			trace = fmt.Sprintf("projects/%s/traces/%s", projectID, traceParts[0])
		}
	}

	log.Println(Entry{
		Severity:  "NOTICE",
		Message:   "This is the default display field.",
		Component: "arbitrary-property",
		Trace:     trace,
	})

	fmt.Fprintln(w, "Hello Logger!")
}

Java

Ativar a geração de registros JSON com Logback e SLF4J acionando o Codificador JSON do Logstash (links em inglês) na configuração do logback.xml.

// Build structured log messages as an object.
Object globalLogFields = null;

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// TODO(developer): delete this code if you're creating a Cloud
//                  Function and it is *NOT* triggered by HTTP.
String traceHeader = req.headers("x-cloud-trace-context");
if (traceHeader != null && project != null) {
  String trace = traceHeader.split("/")[0];
  globalLogFields =
      kv(
          "logging.googleapis.com/trace",
          String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using key value pairs.
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

Personalize nomes de campo padrão para excluir conteúdo indesejado da ingestão no payload de registros. Para ver uma lista de nomes de campo e formatos de dados esperados, consulte Usar o agente do Logging.

<configuration>
  <appender name="jsonConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
      <!-- Ignore default logging fields -->
      <fieldNames>
        <timestamp>[ignore]</timestamp>
        <version>[ignore]</version>
        <logger>[ignore]</logger>
        <thread>[ignore]</thread>
        <level>[ignore]</level>
        <levelValue>[ignore]</levelValue>
      </fieldNames>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="jsonConsoleAppender"/>
  </root>
</configuration>

Campos JSON especiais nas mensagens

Quando você fornece um registro estruturado como um dicionário JSON, alguns campos especiais são retirados do jsonPayload e gravados no campo correspondente no LogEntry gerado, conforme descrito na documentação sobre campos especiais.

Por exemplo, se o JSON incluir uma propriedade severity, ela será removida do jsonPayload e aparecerá como severity da entrada de registro. A propriedade message é usada como o texto de exibição principal da entrada de registro, se houver. Para mais informações sobre propriedades especiais, leia a seção Recurso de geração de registros abaixo.

Correlacionar os registros de contêiner com um registro de solicitação (somente serviços)

No explorador de registros, os registros correlacionados pelos mesmos trace são visíveis no formato “pai-filho”: quando você clicar no ícone de triângulo à esquerda da entrada de registro de solicitação, os registros do contêiner relacionados a essa solicitação aparecerão aninhados no registro da solicitação.

Os registros de contêiner não são correlacionados automaticamente com os registros de solicitação, a menos que você use uma biblioteca de cliente do Cloud Logging. Para correlacionar registros de contêineres com os registros de solicitação sem usar uma biblioteca de cliente, use uma linha de registro JSON estruturado que contenha um campo logging.googleapis.com/trace com o identificador de trace extraído do cabeçalho X-Cloud-Trace-Context, como mostrado na amostra acima para geração de registros estruturados.

Controlar o uso de recursos de registro de solicitações (somente serviços)

Os registros de solicitação são criados automaticamente. Não é possível controlar a quantidade de registros de solicitação diretamente do Cloud Run, mas é possível usar o recurso de exclusão de registros do Cloud Logging.

Uma observação sobre agentes do Logging

Se você usou o Cloud Logging com determinados produtos do Google Cloud, como o Compute Engine, é possível que tenha usado agentes do Cloud Logging. O Cloud Run não usa agentes do Logging porque tem suporte integrado para a coleta de registros.

Nomes de recursos do Logging

Os nomes dos recursos de geração de registros do Cloud Run são:

• Revisão do Cloud Run (cloud_run_revision).
• Job do Cloud Run (cloud_run_job).

Recursos do Logging

Clicar em uma entrada de registro no explorador de registros abre uma entrada de registro formatada em JSON para que você possa detalhar o que você quer.

Todos os campos em uma entrada de registro, como carimbos de data/hora, gravidade e httpRequest, são padrão e estão descritos na documentação sobre a entrada de registro.

O Cloud Run adiciona outros metadados para que você possa identificar a origem de um registro. Isso inclui os rótulos definidos no serviço do Cloud Run e os rótulos de recursos específicos do Cloud Run.

Campos de entrada de registro para um serviço

Veja a seguir uma lista dos campos que podem ser encontrados na entrada de registro de um serviço do Cloud Run:

Campo	Valores e observações
LogEntry.labels.instanceId	A instância que processou a solicitação.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	Os rótulos definidos por você no serviço.
LogEntry.logName	Identifica o registro, por exemplo, registro de solicitação, erro padrão, saída padrão etc.
LogEntry.resource.labels.location	Identifica o local do serviço do Google Cloud.
LogEntry.resource.labels.project_id	O projeto em que o serviço está implantado.
LogEntry.resource.labels.revision_name	A revisão que atendeu à solicitação.
LogEntry.resource.labels.service_name	O serviço que atendeu à solicitação.
LogEntry.resource.type	cloud_run_revision. O tipo de recurso do Cloud Run.

Veja um exemplo de entrada de registro de solicitação de um serviço do Cloud Run:

{
 httpRequest: {…}
 insertId:  "5c82b3d1000ece0000000000"
 labels: {
  instanceId:  "00bf4bf00000fb59c906a00000c9e29c2c4e06dce91500000000056008d2b6460f163c0057b97b2345f2725fb2423ee5f0bafd36df887fdb1122371563cf1ff453717282afe000001"
  mylabel: "mylabelvalue"
  mysecondlabel: "mysecondlabelvalue"
 }
 logName:  "projects/my-project/logs/run.googleapis.com%2Frequests"
 receiveTimestamp:  "2019-03-08T18:26:25.981686167Z"
 resource: {
  labels: {
   configuration_name:  "myservice"
   location:  "us-central1"
   project_id:  "my-project"
   revision_name:  "myservice-00002"
   service_name:  "myservice"
  }
  type:  "cloud_run_revision"
 }
 severity:  "INFO"
 timestamp:  "2019-03-08T18:26:25.970397Z"
}

Campos de entrada de registro para jobs

Veja a seguir uma lista dos campos que podem ser encontrados na entrada de registro do Cloud Run:

Campo	Valores e observações
LogEntry.labels.instanceId	A instância.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	Os identificadores definidos por você no job.
LogEntry.logName	Identifica o registro, por exemplo, registro de solicitação, erro padrão, saída padrão etc.
LogEntry.resource.labels.location	Identifica o local do serviço do Google Cloud.
LogEntry.resource.labels.project_id	O projeto em que o serviço está implantado.
LogEntry.resource.labels.job_name	O nome do job.
LogEntry.labels.execution_name	O nome da execução do job.
LogEntry.labels.task_index	O índice da tarefa.
LogEntry.labels.task_attempt	Indica quantas vezes essa tarefa foi tentada.
LogEntry.resource.type	cloud_run_job. O tipo de recurso do Cloud Run.