Registo e visualização de registos no Cloud Run

Esta página descreve os registos disponíveis quando usa o Cloud Run e como ver e escrever registos.

O Cloud Run tem vários tipos de registos, e estes são enviados automaticamente para o Cloud Logging:

• Registos de pedidos (apenas serviços): registos de pedidos enviados para serviços do Cloud Run. Estes registos são criados automaticamente.
• Registos de contentores (serviços, tarefas e conjuntos de trabalhadores): registos emitidos a partir das instâncias, normalmente a partir do seu próprio código, escritos em localizações suportadas, conforme descrito no artigo Escrever registos de contentores.
• Registos do sistema (serviços, tarefas e conjuntos de trabalhadores): registos gerados pela plataforma que contêm informações sobre as suas cargas de trabalho. Estes registos são escritos em varlog/system.

Ver registos

Pode ver registos do seu serviço, tarefa ou conjunto de trabalhadores de várias formas:

• Use a página do Cloud Run na Google Cloud consola
• Use a CLI gcloud para ver registos com o gcloud (apenas serviços)
• Use o Explorador de registos do Cloud Logging na Google Cloud consola
• Use o Cloud Code (apenas serviços)

Ambos os métodos da consola de visualização de registos examinam os mesmos registos armazenados no Cloud Logging, mas o Explorador de registos do Cloud Logging fornece mais detalhes e mais capacidades de filtragem.

Veja registos no Cloud Run

Pode ver os registos na página do Cloud Run para os seguintes recursos:

• Serviços
• Empregos
• Conjuntos de trabalhadores

Veja registos de um serviço

Para ver os registos de serviço na página do Cloud Run:

1. Aceda ao Cloud Run

2. Clique no serviço na lista apresentada.

3. Clique no separador REGISTOS para obter os registos de pedidos e contentores de todas as revisões deste serviço. Pode filtrar por nível de gravidade do registo.

Veja os registos de um trabalho

Para ver os registos de trabalhos na página do Cloud Run:

1. Aceda ao Cloud Run

2. Clique em Tarefas.

3. Localize o trabalho na lista de trabalhos e clique no mesmo.

4. Clique no separador REGISTOS para ver os registos do contentor de todas as execuções desta tarefa. Pode filtrar por nível de gravidade do registo.

5. Em alternativa, se quiser ver os registos pré-filtrados para uma execução de tarefa específica, clique na execução de tarefa e, de seguida, clique no separador REGISTOS.

Veja registos de um conjunto de trabalhadores

Para ver os registos do conjunto de trabalhadores na página do Cloud Run:

1. Aceda ao Cloud Run

2. Clique em Conjuntos de trabalhadores.

3. Clique no conjunto de trabalhadores na lista apresentada.

4. Clique no separador REGISTOS para obter os registos de pedidos e contentores de todas as revisões deste conjunto de trabalhadores. Pode filtrar por nível de gravidade do registo.

Veja registos de serviços através da CLI do Google Cloud

Pode usar a CLI Google Cloud para ver registos de seguimento ou ler registos existentes para um serviço do Cloud Run na linha de comandos. Por predefinição, os registos são formatados num formato de linha única otimizado para a consola.

Para monitorizar registos, tem de instalar o componente log-streaming na CLI Google Cloud. Se o componente não estiver instalado, é-lhe pedido que o instale quando for necessário.

Veja registos finais na linha de comandos

Pré-visualização — Command-line log tail for Cloud Run services

Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Para um serviço do Cloud Run, pode monitorizar os registos em tempo real a partir do serviço do Cloud Run diretamente na linha de comandos:

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

Substituir:

• SERVICE com o nome do serviço do Cloud Run.
• PROJECT-ID com o Google Cloud ID do projeto. Pode ver o ID do projeto executando o comando gcloud config get-value project.

Leia registos na linha de comandos

Para um serviço do Cloud Run, pode ler os registos existentes de uma das duas formas:

• Num formato otimizado para consolas:

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

• Diretamente a partir do Cloud Logging:

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

Substituir:

• SERVICE com o nome do serviço do Cloud Run.
• PROJECT-ID com o Google Cloud ID do projeto. Pode ver o ID do projeto executando o comando gcloud config get-value project.

Veja registos no Cloud Logging

Nota: a seleção de um conjunto de trabalhadores específico no painel Campos de registo não está implementada. Para filtrar por um conjunto de trabalhadores específico, adicione o seguinte à consulta: resource.labels.worker_pool_name="WORKER_POOL_NAME"

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

1. Aceda à página Explorador de registos na Google Cloud consola:

   Aceda à página do explorador de registos

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

3. Nos menus pendentes, selecione o recurso:

   • Revisão do Cloud Run para um serviço
   • Tarefa do Cloud Run para uma tarefa
   • Cloud Run Worker Pool para um grupo de trabalhadores

Para mais informações, consulte o artigo Usar o Explorador de registos.

Veja os registos de serviço no Cloud Code

Para ver os seus registos no Cloud Code, leia os guias do IntelliJ e do Visual Studio Code.

Leia registos de forma programática

Se quiser ler os registos de forma programática, pode usar um destes métodos:

• Use um destinatário de registos para o Pub/Sub e um script para extrair do Pub/Sub.
• Chame a API Logging através das bibliotecas cliente para a sua linguagem de programação.
• Chame os pontos finais REST da API Logging diretamente.

Formato e conteúdos dos registos de escalabilidade de instâncias

Quando são iniciadas novas instâncias para o seu serviço do Cloud Run, o Cloud Logging inclui entradas de registo com o nome do registo varlog/system a explicar por que motivo cada instância foi criada. A entrada do registo segue este formato:

Starting new instance. Reason: REASON - DESCRIPTION

A tabela seguinte apresenta uma análise detalhada das descrições de instâncias:

Motivo	Descrição
MANUAL_OR_CUSTOMER_MIN_INSTANCE	A instância foi iniciada devido a instâncias mínimas configuradas pelo cliente ou dimensionamento manual.
AUTOSCALING	A instância foi iniciada devido a fatores de escalabilidade configurados (como a utilização da CPU, o débito de pedidos, etc.) ou à capacidade existente insuficiente para o tráfego atual.
DEPLOYMENT_ROLLOUT	A instância foi iniciada devido à mudança de tráfego entre revisões devido à implementação, ao ajuste da divisão de tráfego ou à verificação do estado de implementação.

Escrever registos de contentores

Quando escreve registos a partir do seu serviço, tarefa ou conjunto de trabalhadores, estes são recolhidos automaticamente pelo Cloud Logging, desde que sejam escritos em qualquer uma destas localizações:

• Streams de saída padrão (stdout) ou de erro padrão (stderr)
• Quaisquer ficheiros no diretório /var/log
• syslog (/dev/log)
• Registos escritos através das bibliotecas cliente do Cloud Logging, que estão disponíveis para muitos idiomas populares

Espera-se que a maioria dos programadores escreva registos usando a saída padrão e o erro padrão.

Os registos do contentor escritos nestes locais suportados são automaticamente associados ao serviço, à revisão e à localização do Cloud Run, ao conjunto de trabalhadores, à revisão e à localização do Cloud Run ou ao trabalho do Cloud Run. As exceções contidas nestes registos são capturadas e comunicadas no Error Reporting.

O registo integrado equilibra a fiabilidade e a utilização de recursos, e deve funcionar para a maioria das aplicações. A escrita de entradas de registo através do registo integrado não consome a quota para o número de pedidos por minuto da API Cloud Logging.entries.write

Se a sua aplicação tiver requisitos de volume ou fiabilidade mais elevados, recomendamos que use a API Cloud Logging diretamente, quer como uma biblioteca na sua aplicação ou como um contentor sidecar separado.

Usar texto simples vs. JSON estruturado nos registos

Quando escreve registos, pode enviar uma string de texto simples ou uma única linha de JSON serializado, também denominada dados "estruturados". Esta informação é recolhida e analisada pelo Cloud Logging e é colocada em jsonPayload. Por outro lado, a mensagem de texto simples é colocada em textPayload.

Escreva registos estruturados

O fragmento seguinte mostra como escrever entradas de registo estruturadas. Também mostra como correlacionar as mensagens de registo com o registo de pedidos 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))

Ir

A estrutura de cada entrada de registo é 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 é registada, o método String é chamado para a serializar 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

Ative o registo JSON com o Logback e o SLF4J ativando o codificador JSON do Logstash na sua configuração 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.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

Personalize os nomes dos campos padrão para excluir conteúdo indesejável da ingestão no payload dos registos. Para ver uma lista dos nomes dos campos e dos formatos de dados esperados, consulte o artigo Use o agente de registo.

<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 em mensagens

Quando fornece um registo estruturado como um dicionário JSON, alguns campos especiais são removidos do jsonPayload e são escritos no campo correspondente no LogEntry gerado, conforme descrito na documentação para campos especiais.

Por exemplo, se o seu JSON incluir uma propriedade severity, esta é removida de jsonPayload e aparece como severity da entrada do registo. A propriedade message é usada como o texto de apresentação principal da entrada do registo, se estiver presente. Para mais informações sobre propriedades especiais, leia a secção Recurso de registo abaixo.

Correlacione os registos do contentor com um registo de pedidos (apenas para serviços)

No Explorador de registos, os registos correlacionados pelo mesmo trace são visíveis no formato "principal-secundário": quando clica no ícone de triângulo à esquerda da entrada do registo de pedidos, os registos do contentor relacionados com esse pedido são apresentados aninhados no registo de pedidos.

Os registos de contentores não são correlacionados automaticamente com os registos de pedidos, a menos que use uma biblioteca de cliente do Cloud Logging. Para correlacionar os registos de contentores com os registos de pedidos sem usar uma biblioteca de cliente, pode usar uma linha de registo JSON estruturada que contenha um campo logging.googleapis.com/trace com o identificador de rastreio extraído do cabeçalho X-Cloud-Trace-Context, conforme mostrado no exemplo acima para registo estruturado.

Controle a utilização de recursos do registo de pedidos (apenas serviços)

Os registos de pedidos são criados automaticamente. Embora não possa controlar a quantidade de registos de pedidos diretamente a partir do Cloud Run, pode usar a funcionalidade de exclusão de registos do Cloud Logging.

Uma nota sobre os agentes de registo

Se usou o Cloud Logging com determinados Google Cloud produtos, como o Compute Engine, pode ter usado agentes de registo do Cloud Logging. O Cloud Run não usa agentes de registo porque tem suporte incorporado para a recolha de registos.

Nomes dos recursos de registo

Os nomes dos recursos de registo do Cloud Run são:

• Revisão do Cloud Run (cloud_run_revision).
• Tarefa do Cloud Run (cloud_run_job).
• Cloud Run Worker Pool (cloud_run_workerpool).

Recursos de registo

Se clicar numa entrada do registo no Logs Explorer, é aberta uma entrada do registo formatada em JSON para que possa analisar os detalhes pretendidos.

Todos os campos numa entrada de registo, como as indicações de tempo, a gravidade e httpRequest são padrão e estão descritos na documentação de uma entrada de registo.

O Cloud Run adiciona metadados adicionais para que possa identificar a origem de um registo. Isto inclui as (etiquetas que define no seu serviço do Cloud Run) e as etiquetas de recursos específicas do Cloud Run.

Campos de entrada do registo para um serviço

Segue-se uma lista de campos que podem ser encontrados na entrada do registo de um serviço do Cloud Run:

Campo	Valores e notas
LogEntry.labels.instanceId	A instância que processou o pedido.
LogEntry.labels.run.googleapis.com/base_image_versions	A versão da imagem base que o serviço usa. Só aparece para serviços implementados a partir da origem e se as atualizações de segurança automáticas estiverem ativadas.
LogEntry.labels.run.googleapis.com/cloud_event_id	O ID do CloudEvent. Aparece apenas para serviços que recebem eventos do Eventarc.
LogEntry.labels.run.googleapis.com/cloud_event_source	A origem do CloudEvent. Aparece apenas para serviços que recebem eventos do Eventarc.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	As etiquetas definidas por si no serviço.
LogEntry.logName	Identifica o registo, por exemplo, registo de pedidos, erro padrão, saída padrão, etc.
LogEntry.resource.labels.location	Identifica a localização do Google Cloud do serviço.
LogEntry.resource.labels.project_id	O projeto no qual o serviço está implementado.
LogEntry.resource.labels.revision_name	A revisão que publicou o pedido.
LogEntry.resource.labels.service_name	O serviço que publicou o pedido.
LogEntry.resource.type	cloud_run_revision. O tipo de recurso do Cloud Run.

Segue-se um exemplo de uma entrada do registo de pedidos para 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:  "europe-west1"
   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 do registo para empregos

Segue-se uma lista de campos que podem ser encontrados na entrada do registo de uma tarefa do Cloud Run:

Campo	Valores e notas
LogEntry.labels.instanceId	A instância.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	As etiquetas que definiu na tarefa.
LogEntry.logName	Identifica o registo, por exemplo, erro padrão, saída padrão, etc.
LogEntry.resource.labels.location	Identifica a Google Cloud localização do trabalho.
LogEntry.resource.labels.project_id	O projeto no qual o trabalho está implementado.
LogEntry.resource.labels.job_name	O nome da tarefa.
LogEntry.labels.execution_name	O nome da execução da tarefa.
LogEntry.labels.task_index	O índice da tarefa.
LogEntry.labels.task_attempt	Quantas vezes esta tarefa foi tentada.
LogEntry.resource.type	cloud_run_job. O tipo de recurso do Cloud Run.

Campos de entrada do registo para grupos de trabalhadores

Segue-se uma lista de campos que podem ser encontrados na entrada do registo de um conjunto de trabalhadores do Cloud Run:

Campo	Valores e notas
LogEntry.labels.instanceId	A instância.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	As etiquetas definidas por si no conjunto de trabalhadores.
LogEntry.logName	Identifica o registo, por exemplo, erro padrão, saída padrão, etc.
LogEntry.resource.labels.location	A Google Cloud localização do grupo de trabalhadores.
LogEntry.resource.labels.project_id	O projeto no qual o grupo de trabalhadores está implementado.
LogEntry.resource.labels.workerpool_name	O nome do conjunto de trabalhadores.
LogEntry.resource.type	cloud_run_workerpool. O tipo de recurso do Cloud Run.

O que se segue

• Use as investigações do Gemini Cloud Assist para diagnosticar problemas, recolher estatísticas acionáveis e resolver problemas. Para mais informações sobre diferentes formas de iniciar uma investigação com o Explorador de registos, consulte o artigo Resolva problemas com as investigações do Gemini Cloud Assist na documentação do Gemini.