Ver e gravar registros do Cloud Functions

Como gravar registros do ambiente de execução

O Cloud Functions inclui por padrão a geração simples de registros do ambiente de execução. Os registros gravados em stdout ou stderr serão exibidos automaticamente no Console do Google Cloud. Para ter uma geração de registros mais avançada, use as bibliotecas de cliente do Cloud Logging.

Observação: normalmente há um pequeno atraso entre o momento em que as entradas de registro são criadas e quando elas são exibidas no Cloud Logging.

Por padrão, o payload do registros é uma string de texto simples, conforme mostrado nos snippets a seguir. A string é armazenada no campo textPayload da entrada de registro.

Node.js

const functions = require('@google-cloud/functions-framework');

functions.http('helloWorld', (req, res) => {
  console.log('I am a log entry!');
  console.error('I am an error!');
  res.end();
});

A maioria das entradas de registro não tem um nível de registro associado. São eles:

• Registros emitidos usando console.log(), console.info(), console.warn() ou console.error()
• Registros gravados diretamente em stdout ou stderr

Mensagens internas do sistema têm o nível DEBUG.

Python

def hello_world(data, context):
    """Background Cloud Function.
    Args:
         data (dict): The dictionary with data specific to the given event.
         context (google.cloud.functions.Context): The event metadata.
    """
    print("Hello, stdout!")

• Os registros da saída padrão ou de erros padrão não têm um nível de registro associado.
• Mensagens internas do sistema têm o nível DEBUG.

Go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"fmt"
	"log"
	"net/http"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

func init() {
	functions.HTTP("HelloLogging", HelloLogging)
}

// HelloLogging logs messages.
func HelloLogging(w http.ResponseWriter, r *http.Request) {
	log.Println("This is stderr")
	fmt.Println("This is stdout")

	// Structured logging can be used to set severity levels.
	// See https://cloud.google.com/logging/docs/structured-logging.
	fmt.Println(`{"message": "This has ERROR severity", "severity": "error"}`)

	// cloud.google.com/go/logging can optionally be used for additional options.
}

• Os registros de stdout ou stderr não têm um nível de registro associado.
• Mensagens internas do sistema têm o nível DEBUG.

Java

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;
import java.util.logging.Logger;

public class LogHelloWorld implements HttpFunction {

  private static final Logger logger = Logger.getLogger(LogHelloWorld.class.getName());

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    System.out.println("I am a log to stdout!");
    System.err.println("I am a log to stderr!");

    logger.info("I am an info log!");
    logger.warning("I am a warning log!");

    BufferedWriter writer = response.getWriter();
    writer.write("Messages successfully logged!");
  }
}

• Os registros de stdout ou stderr não têm um nível de registro associado.
• Mensagens internas do sistema têm o nível DEBUG.

C#

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using System;
using System.Threading.Tasks;

namespace LogHelloWorld;

public class Function : IHttpFunction
{
    private readonly ILogger _logger;

    public Function(ILogger<Function> logger) =>
        _logger = logger;

    public async Task HandleAsync(HttpContext context)
    {
        Console.WriteLine("I am a log to stdout!");
        Console.Error.WriteLine("I am a log to stderr!");

        _logger.LogInformation("I am an info log!");
        _logger.LogWarning("I am a warning log!");

        await context.Response.WriteAsync("Messages successfully logged!");
    }
}

• Texto escrito para stdout (por exemplo, via Console.WriteLine) e stderr (por exemplo, via Console.Error.WriteLine) não têm um nível de registro.
• Os níveis de registro do ASP.NET Core são mapeados nos níveis do Cloud Logging da seguinte forma:
  • LogLevel.Trace e LogLevel.Debug map para o Cloud Logging DEBUG.
  • LogLevel.Information é mapeado para o Cloud Logging INFO.
  • LogLevel.Warning é mapeado para o Cloud Logging WARNING.
  • LogLevel.Error é mapeado para o Cloud Logging ERROR.
  • LogLevel.Critical é mapeado para o Cloud Logging CRITICAL.

Ruby

require "functions_framework"

FunctionsFramework.http "log-helloworld" do |_request|
  # Any output sent to either stdout or stderr will be captured and written to
  # the function's logs.
  puts "Hello, stdout!"
  warn "Hello, stderr!"

  # Return the response body as a string.
  "Hello, world!"
end

As entradas de registro não têm um nível de registro associado.

PHP

use Psr\Http\Message\ServerRequestInterface;

function helloLogging(ServerRequestInterface $request): string
{
    // Code running in Google Cloud Functions itself writes log entries to
    // Cloud Logging. (Default log severity level is INFO.)
    $log = fopen('php://stderr', 'wb');
    fwrite($log, "Log entry from fwrite().\n");

    // You can also specify a severity level explicitly using structured logs.
    // See this page for a list of log severity values:
    //   https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
    fwrite($log, json_encode([
      'message' => 'Structured log with error severity',
      'severity' => 'error'
    ]) . PHP_EOL);

    // This doesn't log anything
    error_log('error_log does not log in Cloud Functions!');

    // This will log an error message and immediately terminate the function execution
    // trigger_error('fatal errors are logged!');

    // For HTTP functions, this is added to the HTTP response
    // For CloudEvent functions, this does nothing
    var_dump('var_dump goes to HTTP response for HTTP functions');

    // You can also dump variables using var_export() and forward
    // the resulting string to Cloud Logging via an fwrite() call.
    $entry = var_export('var_export output can be captured.', true);
    fwrite($log, $entry);

    // Functions must return a String or PSR-7 Response object
    return '';
}

Como gravar registros estruturados

Os registros de texto padrão descritos acima não têm um nível de registro associado. Se quiser incluir níveis de registro ou outros campos específicos nas entradas, grave os registros em stdout ou stderr na forma uma única linha de JSON serializado Essa linha é capturada e analisada pelo Cloud Functions e colocada no campo jsonPayload em vez de textPayload. Os snippets abaixo demonstram como gravar esses registros estruturados.

Observação: esses snippets foram escritos originalmente para o Cloud Run. Eles são igualmente aplicáveis ao Cloud Functions.

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

O suporte à geração de registros estruturados está disponível no Python 3.8 e versões posteriores.

# 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

Para ativar a geração de registros JSON com Logback e SLF4J, acione 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);

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

Como processar campos JSON especiais em mensagens

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

Por exemplo, se o JSON incluir uma propriedade severity, ela será removida do jsonPayload e aparecerá como a severity da entrada de registro. A propriedade message é usada como o texto de exibição principal da entrada de registro, se houver.

Como gravar registros usando bibliotecas de cliente

As bibliotecas de cliente do Cloud Logging são uma maneira alternativa de gravar registros. Com essas bibliotecas, é possível usar os mecanismos de geração de registros padrão da sua linguagem de programação e fazer a integração com vários frameworks de geração de registros compatíveis. As bibliotecas de cliente também simplificam o preenchimento dos campos JSON especiais capturando automaticamente algumas informações e fornecendo interfaces para preencher adequadamente os campos.

É possível usar bibliotecas de cliente para gravar registros com a API Cloud Logging de maneira síncrona ou assíncrona. Algumas bibliotecas de cliente também são compatíveis com a gravação de registros estruturados diretamente em stdout ou stderr. Se a gravação dos registros for feita de maneira assíncrona, o encerramento inesperado da função poderá resultar na perda de entradas de registro. Além disso, a geração de registros síncrona com a API Logging aumenta o tempo de execução da função, porque ela exige que as chamadas de API sejam concluídas.

Como visualizar registros do ambiente de execução

Como usar a ferramenta de linha de comando

Os registros do Cloud Functions são visíveis na IU do Cloud Logging e por meio da CLI do Google Cloud.

Para ver registros com a CLI gcloud, use o comando gcloud functions logs read especificando a sinalização --gen2 para o Cloud Functions (2a geração):

gcloud functions logs read [--gen2]

Para ver os registros de uma função específica, digite o nome da função como argumento:

gcloud functions logs read FUNCTION_NAME [--gen2]

No Cloud Functions (1a geração), você pode ver os registros de uma execução específica:

gcloud functions logs read FUNCTION_NAME --execution-id EXECUTION_ID

Observação: no Cloud Functions (2ª geração), o ID de execução da função não aparece nos registros. Para correlacionar registros da mesma execução de função, use o cabeçalho de solicitação x-cloud-trace-context.

Para ver todas as opções de visualização de registros, consulte a documentação do gcloud functions logs read.

Como usar o painel do Logging

Também é possível ver os registros do ambiente de execução do Cloud Functions no Console do Google Cloud.

Observação: os registros de ambiente de execução de funções no Cloud Functions (2a geração) aparecem com o tipo de recurso cloud_run_revision. Use esse tipo de recurso como um filtro no Explorador de registros para visualizar os registros das funções de segunda geração.

Como usar a API Logging

Os registros do ambiente de execução também podem ser gravados e recuperados por meio da API Logging. As bibliotecas de cliente do Cloud Logging oferecem uma interface idiomática para a API Logging:

Node.js

Para ver mais informações, consulte a referência da biblioteca de cliente do Node.js.

// Imports the Google Cloud client library
const {Logging} = require('@google-cloud/logging');

// Creates a client
const logging = new Logging();

/**
 * TODO(developer): Uncomment the following line to run the code.
 */
// const logName = 'Name of the log from which to list entries, e.g. my-log';

const log = logging.log(logName);

async function printEntryMetadata() {
  // List the most recent entries for a given log
  // See https://googleapis.dev/nodejs/logging/latest/Logging.html#getEntries
  const [entries] = await log.getEntries();
  console.log('Logs:');
  entries.forEach(entry => {
    const metadata = entry.metadata;
    console.log(`${metadata.timestamp}:`, metadata[metadata.payload]);
  });
}
printEntryMetadata();

Python

Para mais informações, consulte a referência da biblioteca de cliente do Python.

def list_entries(logger_name):
    """Lists the most recent entries for a given logger."""
    logging_client = logging.Client()
    logger = logging_client.logger(logger_name)

    print("Listing entries for logger {}:".format(logger.name))

    for entry in logger.list_entries():
        timestamp = entry.timestamp.isoformat()
        print("* {}: {}".format(timestamp, entry.payload))

Go

Para mais informações, consulte a referência da biblioteca de cliente do Go.

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/logging"
	"cloud.google.com/go/logging/logadmin"
	"google.golang.org/api/iterator"
)

func getEntries(projectID string) ([]*logging.Entry, error) {
	ctx := context.Background()
	adminClient, err := logadmin.NewClient(ctx, projectID)
	if err != nil {
		log.Fatalf("Failed to create logadmin client: %v", err)
	}
	defer adminClient.Close()

	var entries []*logging.Entry
	const name = "log-example"
	lastHour := time.Now().Add(-1 * time.Hour).Format(time.RFC3339)

	iter := adminClient.Entries(ctx,
		// Only get entries from the "log-example" log within the last hour.
		logadmin.Filter(fmt.Sprintf(`logName = "projects/%s/logs/%s" AND timestamp > "%s"`, projectID, name, lastHour)),
		// Get most recent entries first.
		logadmin.NewestFirst(),
	)

	// Fetch the most recent 20 entries.
	for len(entries) < 20 {
		entry, err := iter.Next()
		if err == iterator.Done {
			return entries, nil
		}
		if err != nil {
			return nil, err
		}
		entries = append(entries, entry)
	}
	return entries, nil
}

Java

Para mais informações, consulte a referência da biblioteca de cliente do Java.

import com.google.api.gax.paging.Page;
import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.Logging;
import com.google.cloud.logging.Logging.EntryListOption;
import com.google.cloud.logging.LoggingOptions;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.TimeZone;

public class ListLogEntries {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace the variable value with valid log name before running the sample
    // or provide it as an argument.
    String logName = args.length > 0 ? args[0] : "test-log";

    try (Logging logging = LoggingOptions.getDefaultInstance().getService()) {

      // When composing a filter, using indexed fields, such as timestamp, resource.type, logName
      // and
      // others can help accelerate the results
      // Full list of indexed fields here:
      // https://cloud.google.com/logging/docs/view/advanced-queries#finding-quickly
      // This sample restrict the results to only last minute to minimize number of API calls
      Calendar calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"));
      calendar.add(Calendar.MINUTE, -1);
      DateFormat rfc3339 = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
      String logFilter =
          "logName=projects/"
              + logging.getOptions().getProjectId()
              + "/logs/"
              + logName
              + " AND timestamp>=\""
              + rfc3339.format(calendar.getTime())
              + "\"";

      // List all log entries
      Page<LogEntry> entries = logging.listLogEntries(EntryListOption.filter(logFilter));
      while (entries != null) {
        for (LogEntry logEntry : entries.iterateAll()) {
          System.out.println(logEntry);
        }
        entries = entries.getNextPage();
      }
    }
  }
}

C#

private void ListLogEntries(string logId)
{
    var client = LoggingServiceV2Client.Create();
    LogName logName = new LogName(s_projectId, logId);
    ProjectName projectName = new ProjectName(s_projectId);
    var results = client.ListLogEntries(Enumerable.Repeat(projectName, 1), $"logName={logName.ToString()}",
        "timestamp desc", callSettings: _retryAWhile);
    foreach (var row in results)
    {
        Console.WriteLine($"{row.TextPayload.Trim()}");
    }
}

Ruby

require "google/cloud/logging"

# log_name = "my_log_name"
logging = Google::Cloud::Logging.new
entries = logging.entries filter: "logName:#{log_name}",
                          max:    1000,
                          order:  "timestamp desc"

entries.each do |entry|
  puts "[#{entry.timestamp}] #{entry.log_name} #{entry.payload.inspect}"
end

PHP

use Google\Cloud\Logging\LoggingClient;

/**
 * Print the timestamp and entry for the project and logger.
 *
 * @param string $projectId The Google project ID.
 * @param string $loggerName The name of the logger.
 */
function list_entries($projectId, $loggerName)
{
    $logging = new LoggingClient(['projectId' => $projectId]);
    $loggerFullName = sprintf('projects/%s/logs/%s', $projectId, $loggerName);
    $oneDayAgo = date(\DateTime::RFC3339, strtotime('-24 hours'));
    $filter = sprintf(
        'logName = "%s" AND timestamp >= "%s"',
        $loggerFullName,
        $oneDayAgo
    );
    $options = [
        'filter' => $filter,
    ];
    $entries = $logging->entries($options);

    // Print the entries
    foreach ($entries as $entry) {
        /* @var $entry \Google\Cloud\Logging\Entry */
        $entryInfo = $entry->info();
        if (isset($entryInfo['textPayload'])) {
            $entryText = $entryInfo['textPayload'];
        } else {
            $entryPayload = [];
            foreach ($entryInfo['jsonPayload'] as $key => $value) {
                $entryPayload[] = "$key: $value";
            }
            $entryText = '{' . implode(', ', $entryPayload) . '}';
        }
        printf('%s : %s' . PHP_EOL, $entryInfo['timestamp'], $entryText);
    }
}

Para outras opções de geração de registros do Java, consulte este link.

Observação: para gravar ou acessar registros do Cloud Functions, um principal também precisa ter as permissões de registro adequadas. Consulte o Guia de controle de acesso do Cloud Logging para mais informações.

Como responder a registros do ambiente de execução

Responda a eventos do Cloud Logging encaminhando os registros para uma Função do Cloud. Para mais informações, consulte a página Gatilhos secundários com o Cloud Logging.

Como ver registros de imagem do build

Você também pode ver os registros da etapa de criação da imagem do processo de implantação. Acesse o link para mais informações.