Écrire, afficher des journaux et y répondre

Écrire des journaux d'exécution

Par défaut, Cloud Functions inclut la journalisation d'exécution simple. Les journaux écrits dans stdout ou stderr s'affichent automatiquement dans Cloud Console. Pour une journalisation plus avancée, utilisez les bibliothèques clientes Cloud Logging.

Par défaut, la charge utile du journal est une simple chaîne de texte, comme illustré dans les extraits ci-dessous. Cette chaîne est stockée dans textPayload.

Node.js

exports.helloWorld = (req, res) => {
  console.log('I am a log entry!');
  console.error('I am an error!');
  res.end();
};
La plupart des entrées de journal ne sont pas associées à un niveau de journalisation. Cela inclut les journaux suivants :

  • Les journaux générés avec console.log(), console.info(), console.warn() ou console.error()
  • Les journaux générés directement dans stdout ou stderr

Les messages système internes ont le niveau de journalisation 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!')
  • Les journaux de sortie standard ou d'erreur standard n'ont pas de niveau de journalisation associé.
  • Les messages système internes ont le niveau de journalisation DEBUG.

Go


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

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

// 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.
}
  • Les journaux de stdout ou stderr n'ont pas de niveau de journalisation associé.
  • Les messages système internes ont le niveau de journalisation 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!");
  }
}
  • Les journaux de stdout ou stderr n'ont pas de niveau de journalisation associé.
  • Les messages système internes ont le niveau de journalisation 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!");
        }
    }
}
  • Le texte écrit dans stdout (par exemple, via Console.WriteLine) et stderr (par exemple, via Console.Error.WriteLine) n'a pas de niveau de journalisation.
  • Les niveaux de journalisation ASP.NET Core sont mappés avec les niveaux Cloud Logging comme suit :
    • LogLevel.Trace et LogLevel.Debug map sont mappés avec DEBUG de Cloud Logging.
    • LogLevel.Information est mappé avec INFO de Cloud Logging.
    • LogLevel.Warning est mappé avec WARNING de Cloud Logging.
    • LogLevel.Error est mappé avec ERROR de Cloud Logging.
    • LogLevel.Critical est mappé avec CRITICAL de Cloud Logging.

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

Les entrées de journal ne sont pas associées à un niveau de journalisation.

Écrire des journaux structurés

Les journaux texte par défaut décrits ci-dessus ne sont associés à aucun niveau de journalisation. Si vous souhaitez inclure des niveaux de journalisation ou d'autres champs spécifiques dans vos entrées de journal, vous pouvez utiliser plutôt des données structurées sous la forme d'une seule ligne de données JSON sérialisées. Cette ligne est récupérée et analysée par Cloud Logging, puis placée dans jsonPayload au lieu de textPayload. Les données sont construites sous forme de dictionnaire JSON. Les extraits ci-dessous illustrent la création de ces entrées de journal.

Node.js


// Uncomment and populate this variable in your code:
// $project = 'The project ID of your 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.
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 journalisation structurée est disponible dans Python 3.8 et versions ultérieures.

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

La structure de chaque entrée de journal est fournie par un type 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"`

	// Cloud Log Viewer 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)
}

Lorsqu'une structure Entry est journalisée, la méthode String est appelée pour la convertir au format JSON attendu par 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

Activez la journalisation JSON avec Logback et SLF4J en activant l'encodeur JSON Logstash dans votre configuration 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.
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));
}
// 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>

Traiter des champs JSON spéciaux dans des messages

Lorsque vous fournissez des données structurées sous forme de dictionnaire JSON, certains champs spéciaux sont supprimés de jsonPayload et écrits dans le champ correspondant de l'entrée LogEntry générée, comme décrit dans la documentation sur les champs spéciaux.

Par exemple, si vos données JSON incluent une propriété severity, celle-ci est supprimée de jsonPayload et apparaît en tant que propriété severity de l'entrée de journal. La propriété message est utilisée comme texte d'affichage principal de l'entrée de journal, le cas échéant.

Afficher les journaux d'exécution

Utiliser l'outil de ligne de commande

Les journaux des fonctions Cloud sont visibles dans l'UI de Cloud Logging et via l'outil de ligne de commande gcloud.

Pour afficher les journaux à l'aide de l'outil gcloud, utilisez la commande logs read :

gcloud functions logs read

Pour afficher les journaux d'une fonction spécifique, indiquez le nom de la fonction en tant qu'argument :

gcloud functions logs read FUNCTION_NAME

Vous pouvez même afficher les journaux relatifs à une exécution spécifique :

gcloud functions logs read FUNCTION_NAME --execution-id EXECUTION_ID

Pour consulter la liste complète des options d'affichage des journaux, consultez l'aide sur logs read :

gcloud functions logs read --help

Utiliser le tableau de bord Logging

Vous pouvez également afficher les journaux d'exécution de Cloud Functions à partir de Cloud Console.

Utiliser l'API Logging

Les journaux d'exécution peuvent également être écrits et récupérés via l'API Cloud Logging. Les bibliothèques clientes de Cloud Logging fournissent une interface idiomatique à l'API Logging :

Node.js

Pour plus d'informations, consultez la documentation de référence sur la bibliothèque cliente 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

Pour en savoir plus, consultez la documentation de référence sur la bibliothèque cliente 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

Pour en savoir plus, consultez la documentation de référence sur la bibliothèque cliente Go.
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"`, projID, 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

Pour en savoir plus, consultez la documentation de référence sur la bibliothèque cliente Java.
// Instantiates a client
LoggingOptions options = LoggingOptions.getDefaultInstance();

String logName = args[0];

try (Logging logging = options.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
  // Below we are restricting the results to only last hour to speedup getting the results back
  Calendar calendar = Calendar.getInstance();
  calendar.add(Calendar.HOUR, -1);
  DateFormat rfc3339 = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
  String logFilter = "logName=projects/" + options.getProjectId() + "/logs/" + logName
      + " AND timestamp>=\"" + rfc3339.format(calendar.getTime()) + "\"";

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

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

Pour connaître les autres options de journalisation pour Java, consultez la page Journalisation Java.

Répondre aux journaux d'exécution

Vous pouvez répondre aux événements Cloud Logging en transférant leurs journaux vers une fonction Cloud. Pour en savoir plus, consultez la page Déclencheurs secondaires avec Cloud Logging.

Afficher les journaux des images de compilation

Vous pouvez également consulter les journaux de l'étape image de compilation du processus de déploiement. Cliquez sur le lien pour obtenir plus d'informations.