Visualiza y escribe registros de Cloud Function

Escribe registros del entorno de ejecución

De forma predeterminada, Cloud Functions incluye registros sencillos sobre el entorno de ejecución. Los registros que se escriban en stdout o stderr aparecerán de forma automática en la consola de Google Cloud. Para obtener un registro más avanzado, usa las bibliotecas cliente de Cloud Logging.

Nota: Por lo general, hay un ligero retraso entre el momento en que se crean las entradas de registro y el momento en que se muestran en Cloud Logging.

De forma predeterminada, la carga útil del registro es una string de texto simple, como se muestra en los siguientes fragmentos. La string se almacena en el campo textPayload de la 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();
});

La mayoría de las entradas de registro no tienen un nivel de registro asociado. Estos incluyen los siguientes:

• Registros emitidos con console.log(), console.info(), console.warn() o console.error()
• Registros escritos directamente en stdout o stderr

Los mensajes internos del sistema tienen el nivel de registro 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!")

• Los registros escritos en los flujos estándares de salida o error no tienen un nivel de registro asociado.
• Los mensajes internos del sistema tienen el nivel de registro 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.
}

• Los registros escritos en stdout o stderr no tienen un nivel de registro asociado.
• Los mensajes internos del sistema tienen el nivel de registro 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!");
  }
}

• Los registros escritos en stdout o stderr no tienen un nivel de registro asociado.
• Los mensajes internos del sistema tienen el nivel de registro 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!");
    }
}

• El texto escrito en stdout (por ejemplo, a través de Console.WriteLine) y stderr (por ejemplo, a través de Console.Error.WriteLine) no tiene un nivel de registro.
• Los niveles de registro de ASP.NET Core se mapean a los niveles de Cloud Logging de la siguiente manera:
  • LogLevel.Trace y LogLevel.Debug map a DEBUG de Cloud Logging
  • LogLevel.Information se mapea a INFO de Cloud Logging
  • LogLevel.Warning se mapea a WARNING de Cloud Logging
  • LogLevel.Error se mapea a ERROR de Cloud Logging
  • LogLevel.Critical se mapea a CRITICAL de Cloud Logging

Rita

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

Las entradas de registro no tienen un nivel de registro asociado.

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 will log to standard error, which will appear in Cloud Logging
    error_log('error_log logs 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 '';
}

Escribe registros estructurados

Los registros de texto predeterminados descritos con anterioridad no tienen un nivel de registro asociado. Si deseas incluir niveles de registro o algún otro campo específico en las entradas de registro, puedes escribir registros en stdout o stderr en el formato de una sola línea con JSON serializado. Cloud Functions toma y analiza esta línea, y la coloca en el campo jsonPayload en lugar de textPayload. Los siguientes fragmentos demuestran cómo escribir esos registros estructurados.

Nota: Estos fragmentos se escribieron originalmente para Cloud Run. Son aplicables por igual a 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

La compatibilidad con el registro estructurado está disponible en Python 3.8 y versiones 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

Un tipo de Entry proporciona la estructura para cada entrada de registro:

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

Cuando se registra una estructura de Entry, se llama al método String para serializarla según el formato JSON que espera 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 habilitar el registro JSON con Logback y SLF4J, debes habilitar el codificador de JSON de Logstash en la configuración 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);

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

Procesa campos JSON especiales en mensajes

Cuando proporcionas datos estructurados como un diccionario JSON, algunos campos especiales se extraen de jsonPayload y se escriben en el campo correspondiente en el LogEntry generado, como se describe en la documentación de campos especiales.

Por ejemplo, si el JSON incluye una propiedad severity, se quita de jsonPayload y aparece como la severity de la entrada de registro. La propiedad message se usa como el texto de visualización principal de la entrada de registro, si está presente.

Escribe registros mediante bibliotecas cliente

Las bibliotecas cliente de Cloud Logging proporcionan una forma alternativa de escribir registros. Con estas bibliotecas, puedes usar los mecanismos de registro estándar de tu lenguaje de programación y, también, integrarlos en varios frameworks de registro compatibles. Las bibliotecas cliente también simplifican la propagación de los campos JSON especiales, ya que capturan información de forma automática y proporcionan interfaces para propagar correctamente los campos.

Puedes usar las bibliotecas cliente para escribir registros con la API de Cloud Logging de forma síncrona o asíncrona. Algunas bibliotecas cliente también admiten la escritura de registros estructurados directamente en stdout o stderr. Ten en cuenta que si escribes registros de forma asíncrona, la finalización inesperada de funciones puede provocar la pérdida de entradas de registro. Además, ten en cuenta que el registro síncrono con la API de Logging aumenta el tiempo de ejecución de la función, ya que requiere que se completen las llamadas a la API.

Visualiza los registros del entorno de ejecución

Usa la herramienta de línea de comandos

Los registros de Cloud Functions se pueden ver en la IU de Cloud Logging y a través de Google Cloud CLI.

Para ver registros con la CLI de gcloud, usa el comando gcloud functions logs read y, de manera opcional, especifica la marca --gen2 para Cloud Functions (2nd gen):

gcloud functions logs read [--gen2]

Para ver los registros de una función específica, proporciona el nombre de la función como un argumento:

gcloud functions logs read FUNCTION_NAME [--gen2]

En Cloud Functions (1st gen), puedes ver los registros de una ejecución específica:

gcloud functions logs read FUNCTION_NAME --execution-id EXECUTION_ID

Nota: En Cloud Functions (2nd gen), el ID de ejecución de la función no aparece en los registros. Para correlacionar registros de la misma ejecución de función, usa el encabezado de la solicitud de x-cloud-trace-context.

Para ver la gama completa de opciones de visualización de registros, consulta la documentación de gcloud functions logs read.

Usa el panel de Logging

También puedes ver los registros del entorno de ejecución de Cloud Functions en la consola de Google Cloud.

Nota: Los registros de entorno de ejecución de las funciones de Cloud Functions (2nd gen) aparecen con el tipo de recurso cloud_run_revision. Usa este tipo de recurso como filtro en el Explorador de registros para ver los registros del entorno de ejecución tus funciones de 2ª gen.

Usa la API de Logging

Los registros del entorno de ejecución también se pueden escribir y recuperar a través de la API de Cloud Logging. Las bibliotecas cliente de Cloud Logging proporcionan una interfaz idiomática a la API de Logging:

Node.js

Para obtener más información, consulta la referencia de la biblioteca cliente de 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 obtener más información, consulta la referencia de la biblioteca cliente de 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 obtener más información, consulta la referencia de la biblioteca cliente de 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 obtener más información, consulta la referencia de la biblioteca cliente de 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);
    }
}

Si quieres obtener más opciones de registro para Java, consulta Java Logging.

Nota: Para escribir en los registros de Cloud Functions o acceder a ellos, una principal también debe tener los permisos de registro correspondientes. Consulta la guía de control de acceso de Cloud Logging para obtener más información.

Responde los registros del entorno de ejecución

Para responder a los eventos de Cloud Logging reenvía sus registros a una función de Cloud Functions. Para obtener más información, consulta la página Activadores secundarios con Cloud Logging.

Visualiza registros de compilación de imágenes

También puedes ver los registros del paso que abarca la compilación de imágenes del proceso de implementación. Consulta el vínculo para obtener más información.