ログの作成、表示、処理

ランタイムログの書き込み

Cloud Functions には、デフォルトで簡単なランタイムのロギング機能が含まれています。stdout または stderr に書き込まれたログは、Cloud Console に自動的に表示されます。より詳細なロギングを行うには、Cloud Logging クライアント ライブラリを使用します。

デフォルトでは、ログのペイロードは次のスニペットのように単純なテキスト文字列です。この文字列は textPayload に格納されています。

Node.js

functions/log/index.js 
exports.helloWorld = (req, res) => {
  console.log('I am a log entry!');
  console.error('I am an error!');
  res.end();
};
ほとんどのログエントリにはログレベルが関連付けられていません。たとえば、次のようなものです。

  • console.log()、console.info()、console.warn()、または console.error() を使用して出力されたログ
  • stdout または stderr に直接書き込まれたログ

内部システム メッセージのログレベルは DEBUG です。

Python

functions/log/main.py 
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!')
  • 標準出力または標準エラーに出力されるログにはログレベルが関連付けられていません。
  • 内部システム メッセージのログレベルは DEBUG です。

Go

functions/helloworld/hello_logging.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.
}
  • stdout または stderr に出力されるログにはログレベルが関連付けられていません。
  • 内部システム メッセージのログレベルは DEBUG です。

Java

functions/logging/log-helloworld/src/main/java/functions/LogHelloWorld.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!");
  }
}
  • stdout または stderr に出力されるログにはログレベルが関連付けられていません。
  • 内部システム メッセージのログレベルは DEBUG です。

C#

functions/logging/LogHelloWorld/Function.cs 
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!");
        }
    }
}
  • stdout（Console.WriteLine など）や stderr（Console.Error.WriteLine など）に書き込まれたテキストにログレベルはありません。
  • ASP.NET Core のログレベルは、次のように Cloud Logging レベルにマッピングされます。
    • LogLevel.Trace と LogLevel.Debug map は Cloud Logging DEBUG にマッピングされます。
    • LogLevel.Information は Cloud Logging INFO にマッピングされます。
    • LogLevel.Warning は Cloud Logging WARNING にマッピングされます。
    • LogLevel.Error は Cloud Logging ERROR にマッピングされます。
    • LogLevel.Critical は Cloud Logging CRITICAL にマッピングされます。

Ruby

functions/helloworld/log/app.rb 
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

ログエントリには、関連付けられたログレベルはありません。

構造化ログの書き込み

上記のデフォルトのテキストログには、関連するログレベルがありません。ログレベルなどの特定のフィールドをログエントリに含めるには、構造化されたデータを使用し、シリアル化された JSON 形式の 1 行で記述します。これは Cloud Logging によって取得され、解析された後、textPayload ではなく jsonPayload に配置されます。データは JSON 辞書として構成されます。以下のスニペットは、これらのログエントリの作成方法を示しています。

Node.js

run/logging-manual/app.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

構造化ロギングは、Python 3.8 以降でサポートされています。

run/logging-manual/main.py 
# 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

各ログエントリの構造は、Entry タイプによって指定されます。

run/logging-manual/main.go 

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

Entry 構造体がログに記録されると、String メソッドが呼び出され、Cloud Logging で想定されている JSON 形式にマーシャリングされます。

run/logging-manual/main.go 

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

logback.xml の構成で Logstash JSON Encoder を有効にして、Logback と SLF4J での JSON ロギングを有効にします。

run/logging-manual/src/main/java/com/example/cloudrun/App.java 
// 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);
run/logging-manual/src/main/resources/logback.xml 
<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>

メッセージ内の特別な JSON フィールドの処理

特殊フィールドのドキュメントで説明されているように、構造化されたデータを JSON 辞書として提供すると、いくつかの特殊フィールドが jsonPayload から削除され、生成された LogEntry の対応フィールドに書き込まれます。

たとえば、JSON に severity プロパティが含まれている場合、jsonPayload から削除され、代わりにログエントリの severity として表示されます。message プロパティが存在する場合は、ログエントリのメイン表示テキストとして使用されます。

ランタイムログの表示

コマンドライン ツールの使用

Cloud Functions のログは、Cloud Logging UI および gcloudコマンドライン ツールを介して表示できます。

gcloud ツールでログを表示するには、logs read コマンドを使用します。

gcloud functions logs read

特定関数のログを表示するには、引数として関数名を入力します。

gcloud functions logs read FUNCTION_NAME

特定の実行内容を確認するために、ログを表示することもできます。

gcloud functions logs read FUNCTION_NAME --execution-id EXECUTION_ID

すべてのログ表示オプションについては、logs read のヘルプをご覧ください。

gcloud functions logs read --help

ロギング ダッシュボードを使う

Cloud Console から Cloud Functions のランタイムログを表示することもできます。

Logging API の使用

Logging API でもランタイムログの書き込みや取得を行うことができます。Cloud Logging クライアント ライブラリには、Logging API 用のインターフェースが用意されています。

Node.js

詳細については、Node.js クライアント ライブラリのリファレンスをご覧ください。
samples/logs.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

詳細については、Python クライアント ライブラリのリファレンスをご覧ください。
samples/snippets/snippets.py 
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

詳細については、Go クライアント ライブラリのリファレンスをご覧ください。
logging/simplelog/simplelog.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

詳細については、Java クライアント ライブラリのリファレンスをご覧ください。
samples/snippets/src/main/java/com/example/logging/ListLogs.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#

logging/api/LoggingSample/Program.cs 
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

logging/sample.rb 
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

Java のその他のロギング オプションについては、Java ロギングをご覧ください。

ランタイムログの処理

Cloud Logging のイベントに応答するには、そのログを Cloud Functions の関数に転送します。詳細については、Cloud Logging でのセカンド パーティ トリガーページをご覧ください。

ビルドイメージのログの表示

デプロイ プロセスのビルドイメージのステップのログも確認できます。リンクをクリックして詳細をご確認ください。