Como gerar registros e visualizar registros no Cloud Run

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

O Cloud Run tem vários 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, jobs e pools de workers): 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.
• Registros do sistema (serviços, jobs e pools de workers): registros gerados pela plataforma que contêm informações sobre suas cargas de trabalho. Esses registros são gravados em varlog/system.

Como visualizar registros

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

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

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 conferir os registros na página do Cloud Run para os seguintes recursos:

• Serviços
• Jobs

Ver registros de um serviço

1. No console do Cloud de Confiance by S3NS , acesse a página Serviços do Cloud Run:

   Acessar o Cloud Run

2. Clique no serviço 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. No console Cloud de Confiance by S3NS , acesse a página Jobs do Cloud Run:

   Acessar o Cloud Run

2. Localize o job na lista e clique nele.

3. 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.

4. 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

É 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

Substitua:

• SERVICE: o nome do serviço do Cloud Run.
• PROJECT-ID: o ID do projeto Cloud de Confiance by S3NS . Para conferir 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 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

Substitua:

• SERVICE: o nome do serviço do Cloud Run.
• PROJECT-ID: o ID do projeto Cloud de Confiance by S3NS . Para conferir o ID do projeto, execute o comando gcloud config get-value project.

Formato e conteúdo dos registros de escalonamento de instâncias

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

Starting new instance. Reason: REASON - DESCRIPTION

A tabela a seguir mostra um detalhamento das descrições de instâncias:

Gravar registros de contêiner

Quando você grava registros do seu serviço, job ou pool de trabalhadores, 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, ao pool de trabalhadores, à 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.

A geração de registros integrada equilibra confiabilidade e uso de recursos e funciona para a maioria dos aplicativos. A gravação de entradas de registro usando o registro integrado não consome a cota do número de solicitações entries.write por minuto da API Cloud Logging.

Se o aplicativo tiver requisitos para maior volume ou confiabilidade, recomendamos usar a API Cloud Logging diretamente, seja como uma biblioteca no aplicativo ou como um contêiner secundário separado.

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.

// 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));

# 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))

// 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)
}

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!")
}

// 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];
  MDC.put(
      "logging.googleapis.com/trace",
      String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using MDC (Mapped Diagnostic Context) keys.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
MDC.put("component", "arbitrary-property");

logger.info("This is the default display field.");

// Clear MDC at the end of the request to avoid resource leaks
MDC.clear();

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
    <!-- Redirect logs to stdout in JSON format for Cloud Run to capture -->
    <redirectToStdout>true</redirectToStdout>
  </appender>
  <root level="INFO">
    <appender-ref ref="CLOUD"/>
  </root>
</configuration>

{"severity":"INFO","time":"YYYY-MM-DDTHH:MM:SS.SSSZ","logging.googleapis.com/labels":{"component":"arbitrary-property","levelName":"INFO","loggerName":"com.example.cloudrun.App","levelValue":"20000"},"logging.googleapis.com/trace_sampled":false,"message":"This is the default display field."}

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 Análise 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 Cloud de Confiance by S3NS produtos, 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:

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:  "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 de registro para jobs

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