[インデックス 1551] ファイルの概要

このコミットは、Go言語の標準ライブラリに基本的なロギングパッケージ log を追加するものです。Logger 型を定義し、標準出力や標準エラー出力へのログ記録、ファイル名や行番号の付加、さらにはプログラムの終了 (Exit) やパニック (Crash) を引き起こす特殊なロガーの機能を提供します。

コミット

commit 806d00fc63d41529ba2ee661c022d87579b05907
Author: Rob Pike <r@golang.org>
Date:   Mon Jan 26 09:28:07 2009 -0800

    add start to a logging package.
    
    R=rsc
    DELTA=205  (205 added, 0 deleted, 0 changed)
    OCL=23448
    CL=23478
---
 src/lib/Makefile    |   2 +
 src/lib/log.go      | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/lib/log_test.go |  70 +++++++++++++++++++++++++++
 3 files changed, 207 insertions(+)

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/806d00fc63d41529ba2ee661c022d87579b05907

元コミット内容

「ロギングパッケージの開始を追加する。」という簡潔なメッセージで、Go言語の初期段階において、基本的なロギング機能がライブラリとして導入されたことを示しています。

変更の背景

このコミットは2009年1月26日に行われており、Go言語がまだ公開される前の非常に初期の段階に当たります。当時のGo言語は、システムプログラミング、ネットワークサービス、並行処理に焦点を当てた新しいプログラミング言語として開発が進められていました。

プログラム開発において、デバッグ、監視、運用時の問題特定のためにログ出力は不可欠な要素です。Go言語のような新しい言語を設計する際には、標準ライブラリとして基本的なユーティリティを提供することが重要であり、ロギング機能はその中でも優先度の高いものの一つでした。

このコミットは、Go言語の標準ライブラリに、アプリケーションがイベントや状態を記録するための基本的なメカニズムを提供することを目的としています。これにより、開発者はGo言語で記述されたプログラムの動作を追跡し、問題を診断するための手段を得ることができます。特に、Exit や Crash のような特殊なロガーは、プログラムの異常終了時の情報収集に役立つように設計されています。

前提知識の解説

Go言語のパッケージと標準ライブラリ

Go言語は、コードをパッケージという単位で整理します。パッケージは関連する機能の集合であり、他のパッケージからインポートして利用できます。src/lib は、当時のGo言語の標準ライブラリが配置されていたディレクトリの一つであり、log パッケージもその一部として追加されました。

io.Writer インターフェース

io.Writer はGo言語の標準ライブラリ io パッケージで定義されているインターフェースです。データを書き込むための単一のメソッド Write([]byte) (n int, err error) を持ちます。これにより、ファイル、ネットワーク接続、メモリバッファなど、様々な出力先に統一的な方法でデータを書き込むことができます。ロギングパッケージでは、ログメッセージの出力先として io.Writer を利用することで、柔軟な出力設定を可能にしています。

fmt パッケージ

fmt パッケージは、Go言語におけるフォーマットされたI/O（入出力）を実装するためのパッケージです。C言語の printf や scanf に似た機能を提供し、様々な型の値を文字列に変換したり、文字列から値を解析したりする機能を提供します。ロギングにおいて、メッセージを整形するために fmt.Sprintf や fmt.Sprintln が使用されます。

os パッケージ

os パッケージは、オペレーティングシステム（OS）の機能にアクセスするためのインターフェースを提供します。ファイル操作、プロセス管理、環境変数へのアクセスなどが含まれます。このコミットでは、標準出力 (os.Stdout) や標準エラー出力 (os.Stderr) へのアクセス、およびプログラムの終了 (os.Exit) に利用されています。

time パッケージ

time パッケージは、時刻の取得、時間の計測、日付と時刻のフォーマットなど、時間に関する機能を提供します。ロギングにおいて、ログメッセージにタイムスタンプを付加するために利用されます。

panic と recover

Go言語には、プログラムの異常終了を扱うための panic と recover というメカニズムがあります。panic は、回復不能なエラーが発生した際にプログラムの実行を停止させるために使用されます。このコミットでは、Lcrash フラグが設定されたロガーが使用された場合に panic を発生させることで、プログラムをクラッシュさせる機能を提供しています。

sys.Caller

sys.Caller は、当時のGo言語の内部パッケージ sys に存在した関数で、呼び出し元のファイル名、行番号、関数名などの情報を取得するために使用されました。現在のGo言語では、runtime パッケージの runtime.Caller に相当する機能です。ロギングにおいて、ログメッセージに発生元のコードの場所（ファイル名と行番号）を付加するために利用されます。

Makefile

Makefile は、ソフトウェアのビルドプロセスを自動化するためのファイルです。make コマンドによって解釈され、ソースコードのコンパイル、ライブラリのリンク、テストの実行など、一連のタスクを定義します。このコミットでは、新しく追加された log パッケージをビルドシステムに組み込むために Makefile が変更されています。

技術的詳細

このコミットで導入された log パッケージは、Go言語におけるロギングの基本的な概念と実装を示しています。

Logger 構造体

type Logger struct {
	out0 io.Write;
	out1 io.Write;
	flag int;
}

Logger 構造体は、ロガーの主要な設定を保持します。

• out0, out1: ログメッセージの出力先となる io.Write インターフェースです。最大2つの出力先に同時にログを書き込むことができます。
• flag: ロガーの動作を制御するためのビットフラグです。

フラグ定数

const (
	Lok = iota;
	Lexit;	// terminate execution when written
	Lcrash;	// crash (panic) when written
	Lshortname = 1 << 5;
)

• Lok: 通常のロギング動作を示します。
• Lexit: このフラグが設定されたロガーに書き込むと、プログラムが os.Exit(1) で終了します。
• Lcrash: このフラグが設定されたロガーに書き込むと、プログラムが panic を発生させてクラッシュします。
• Lshortname: ログメッセージにファイル名を含める際、フルパスではなくファイル名のみを表示するようにします。

NewLogger 関数

func NewLogger(out0, out1 io.Write, flag int) *Logger {
	return &Logger{out0, out1, flag}
}

新しい Logger インスタンスを作成するためのコンストラクタ関数です。

事前定義されたロガー

var (
	stdout = NewLogger(os.Stdout, nil, Lok);
	stderr = NewLogger(os.Stderr, nil, Lok);
	exit = NewLogger(os.Stderr, nil, Lexit);
	crash = NewLogger(os.Stderr, nil, Lcrash);
)

一般的な用途のために、stdout (標準出力), stderr (標準エラー出力), exit (終了), crash (クラッシュ) の4つの Logger インスタンスが事前に定義されています。exit と crash は、ログメッセージを標準エラー出力に書き込みます。

timestamp 関数

func timestamp(ns int64) string {
	t := time.SecondsToLocalTime(ns/1e9);
	// why are time fields private?
	s := t.RFC1123();
	return s[5:12] + s[17:25];	// TODO(r): placeholder. this gives "24 Jan 15:50:18"
}

ナノ秒単位のタイムスタンプを引数に取り、フォーマットされた時刻文字列を返します。当時の time パッケージのAPIの制約（コメントに // why are time fields private? とある）により、RFC1123 フォーマットから部分文字列を抽出して整形している点が興味深いです。これは、Go言語のAPIがまだ成熟していなかった初期の状況を反映しています。

output メソッド

func (l *Logger) output(calldepth int, s string) {
	now := time.Nanoseconds();	// get this early.
	newline := "\n";
	if len(s) > 0 && s[len(s)-1] == '\n' {
		newline = ""
	}
	pc, file, line, ok := sys.Caller(calldepth);
	if ok {
		if l.flag & Lshortname == Lshortname {
			short, ok := shortnames[file];
			if !ok {
				short = file;
				for i := len(file) - 1; i > 0; i-- {
					if file[i] == '/' {
						short = file[i+1:len(file)];
						shortnames[file] = short;
						break;
					}
				}
			}
			file = short;
		}
	} else {
		file = "???";
		line = 0;
	}
	s = fmt.Sprintf("%s %s:%d: %s%s", timestamp(now), file, line, s, newline);
	io.WriteString(l.out0, s);
	if l.out1 != nil {
		io.WriteString(l.out1, s);
	}
	switch l.flag & ^Lshortname {
	case Lcrash:
		panic("log: fatal error");
	case Lexit:
		sys.Exit(1);
	}
}

Logger の中心となるメソッドで、実際のログ出力処理を行います。

• calldepth: sys.Caller に渡す呼び出しスタックの深さを指定します。これにより、ログを呼び出した元のファイルと行番号を正確に取得できます。
• タイムスタンプ、ファイル名、行番号、そしてログメッセージを結合して最終的なログ文字列を生成します。
• Lshortname フラグが設定されている場合、ファイルパスからファイル名のみを抽出します。この際、shortnames マップを使用してファイル名のキャッシュを行い、パフォーマンスを向上させています。
• 生成されたログ文字列を out0 および out1 に書き込みます。
• Lcrash または Lexit フラグが設定されている場合、それぞれ panic または sys.Exit(1) を呼び出してプログラムの動作を制御します。

ロギングメソッド

Logf, Log メソッドは、Logger インスタンスに対してフォーマットされたログメッセージや、引数をそのまま出力する機能を提供します。

func (l *Logger) Logf(format string, v ...) {
	l.output(2, fmt.Sprintf(format, v))
}

func (l *Logger) Log(v ...) {
	l.output(2, fmt.Sprintln(v))
}

ヘルパー関数

Stdout, Stderr, Stdoutf, Stderrf, Exit, Exitf, Crash, Crashf といったグローバルなヘルパー関数が提供されており、事前に定義されたロガー (stdout, stderr, exit, crash) を使って簡単にログを出力できます。

func Stdout(v ...) {
	stdout.output(2, fmt.Sprint(v))
}
// ... (他のヘルパー関数も同様)

Makefile の変更

src/lib/Makefile には、新しく追加された log パッケージをビルド対象に含めるための変更が加えられています。

• DIRS 変数に log が追加され、ビルドシステムが log パッケージのソースコードを認識するようにします。
• log.6 ターゲット（Go言語の初期のビルドシステムにおけるパッケージの依存関係を示す）が追加され、log パッケージが fmt, io, os, time パッケージに依存していることを明示しています。

コアとなるコードの変更箇所

src/lib/Makefile

--- a/src/lib/Makefile
+++ b/src/lib/Makefile
@@ -27,6 +27,7 @@ DIRS=\
 FILES=\
 	bufio\
 	flag\
+\tlog\
 	malloc\
 	once\
 	rand\
@@ -91,6 +92,7 @@ test: test.files
 bignum.6: fmt.dirinstall
 bufio.6: io.dirinstall os.dirinstall
 flag.6: fmt.dirinstall
+log.6: fmt.dirinstall io.dirinstall os.dirinstall time.dirinstall
 testing.6: flag.install fmt.dirinstall
 strings.6: utf8.install
 

src/lib/log.go (抜粋)

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Rudimentary logging package. Defines a type, Logger, with simple
// methods for formatting output to one or two destinations. Also has
// predefined Loggers accessible through helper functions Stdout[f],
// Stderr[f], Exit[f], and Crash[f].
// Exit exits when written to.
// Crash causes a crash when written to.

package log

import (
	"fmt";
	"io";
	"os";
	"time";
)

// Lshortname can be or'd in to cause only the last element of the file name to be printed.
const (
	Lok = iota;
	Lexit;	// terminate execution when written
	Lcrash;	// crash (panic) when written
	Lshortname = 1 << 5;
)

type Logger struct {
	out0 io.Write;
	out1 io.Write;
	flag int;
}

func NewLogger(out0, out1 io.Write, flag int) *Logger {
	return &Logger{out0, out1, flag}
}

var (
	stdout = NewLogger(os.Stdout, nil, Lok);
	stderr = NewLogger(os.Stderr, nil, Lok);
	exit = NewLogger(os.Stderr, nil, Lexit);
	crash = NewLogger(os.Stderr, nil, Lcrash);
)

func timestamp(ns int64) string {
	t := time.SecondsToLocalTime(ns/1e9);
	// why are time fields private?
	s := t.RFC1123();
	return s[5:12] + s[17:25];	// TODO(r): placeholder. this gives "24 Jan 15:50:18"
}

var shortnames = make(map[string] string)	// cache of short names to avoid allocation.

// The calldepth is provided for generality, although at the moment on all paths it will be 2.
func (l *Logger) output(calldepth int, s string) {
	now := time.Nanoseconds();	// get this early.
	newline := "\n";
	if len(s) > 0 && s[len(s)-1] == '\n' {
		newline = ""
	}
	pc, file, line, ok := sys.Caller(calldepth);
	if ok {
		if l.flag & Lshortname == Lshortname {
			short, ok := shortnames[file];
			if !ok {
				short = file;
				for i := len(file) - 1; i > 0; i-- {
					if file[i] == '/' {
						short = file[i+1:len(file)];
						shortnames[file] = short;
						break;
					}
				}
			}
			file = short;
		}
	} else {
		file = "???";
		line = 0;
	}
	s = fmt.Sprintf("%s %s:%d: %s%s", timestamp(now), file, line, s, newline);
	io.WriteString(l.out0, s);
	if l.out1 != nil {
		io.WriteString(l.out1, s);
	}
	switch l.flag & ^Lshortname {
	case Lcrash:
		panic("log: fatal error");
	case Lexit:
		sys.Exit(1);
	}
}

// Basic methods on Logger, analogous to Printf and Print
func (l *Logger) Logf(format string, v ...) {
	l.output(2, fmt.Sprintf(format, v))
}

func (l *Logger) Log(v ...) {
	l.output(2, fmt.Sprintln(v))
}

// Helper functions for lightweight simple logging to predefined Loggers.
func Stdout(v ...) {
	stdout.output(2, fmt.Sprint(v))
}

func Stderr(v ...) {
	stdout.output(2, fmt.Sprintln(v))
}

func Stdoutf(format string, v ...) {
	stdout.output(2, fmt.Sprintf(format, v))
}

func Stderrf(format string, v ...) {
	stderr.output(2, fmt.Sprintf(format, v))
}

func Exit(v ...) {
	exit.output(2, fmt.Sprintln(v))
}

func Exitf(format string, v ...) {
	exit.output(2, fmt.Sprintf(format, v))
}

func Crash(v ...) {
	crash.output(2, fmt.Sprintln(v))
}

func Crashf(format string, v ...) {\
	crash.output(2, fmt.Sprintf(format, v))\
}

src/lib/log_test.go (抜粋)

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package log

// These tests are too simple.

import (
	"bufio";
	"log";
	"os";
	"testing";
)

func test(t *testing.T, flag int, expect string) {
	fd0, fd1, err1 := os.Pipe();
	if err1 != nil {
		t.Error("pipe", err1);
	}
	buf, err2 := bufio.NewBufRead(fd0);
	if err2 != nil {
		t.Error("bufio.NewBufRead", err2);
	}
	l := NewLogger(fd1, nil, flag);
	l.Log("hello", 23, "world");	/// the line number of this line needs to be placed in the expect strings
	line, err3 := buf.ReadLineString('\n', false);
	if line[len(line)-len(expect):len(line)] != expect {
		t.Error("log output should be ...", expect, "; is " , line);
	}
	t.Log(line);
	fd0.Close();
	fd1.Close();
}

func TestRegularLog(t *testing.T) {
	test(t, Lok, "/go/src/lib/log_test.go:25: hello 23 world");
}

func TestShortNameLog(t *testing.T) {
	test(t, Lok|Lshortname, " log_test.go:25: hello 23 world")
}

func testFormatted(t *testing.T, flag int, expect string) {
	fd0, fd1, err1 := os.Pipe();
	if err1 != nil {
		t.Error("pipe", err1);
	}
	buf, err2 := bufio.NewBufRead(fd0);
	if err2 != nil {
		t.Error("bufio.NewBufRead", err2);
	}
	l := NewLogger(fd1, nil, flag);
	l.Logf("hello %d world", 23);	/// the line number of this line needs to be placed in the expect strings
	line, err3 := buf.ReadLineString('\n', false);
	if line[len(line)-len(expect):len(line)] != expect {
		t.Error("log output should be ...", expect, "; is " , line);
	}
	t.Log(line);
	fd0.Close();
	fd1.Close();
}

func TestRegularLogFormatted(t *testing.T) {
	testFormatted(t, Lok, "/go/src/lib/log_test.go:53: hello 23 world");
}

func TestShortNameLogFormatted(t *testing.T) {
	testFormatted(t, Lok|Lshortname, " log_test.go:53: hello 23 world")
}

コアとなるコードの解説

src/lib/Makefile の変更

Makefile の変更は、Go言語のビルドシステムに新しい log パッケージを認識させるためのものです。

• DIRS 変数に log を追加することで、make コマンドが src/lib/log ディレクトリをビルド対象として含めるようになります。
• log.6: fmt.dirinstall io.dirinstall os.dirinstall time.dirinstall という行は、log パッケージがビルドされる前に、fmt, io, os, time の各パッケージがインストールされている必要があることを示しています。これは、log.go がこれらのパッケージをインポートしているため、依存関係を解決するために必要です。

src/lib/log.go の主要部分

• パッケージ宣言とインポート: package log でパッケージを定義し、fmt, io, os, time をインポートしています。これらはログのフォーマット、出力、システム操作、タイムスタンプ取得にそれぞれ必要です。
• フラグ定数: Lok, Lexit, Lcrash, Lshortname は、ロガーの振る舞いを細かく制御するためのビットフラグです。特に Lexit と Lcrash は、ログ出力がプログラムの終了やクラッシュに直結する特殊なケースを扱います。
• Logger 構造体: out0 と out1 は io.Write 型であり、ログメッセージの出力先（例: os.Stdout, os.Stderr, ファイルなど）を抽象化しています。flag は上述のフラグ定数を保持します。
• NewLogger 関数: Logger インスタンスを生成するファクトリ関数です。
• 事前定義されたロガー: stdout, stderr, exit, crash は、一般的なロギングシナリオを簡素化するために用意されたグローバルな Logger インスタンスです。
• timestamp 関数: ログメッセージに付加するタイムスタンプを生成します。当時の time パッケージのAPIの制約から、RFC1123 フォーマットの文字列を加工して必要な部分を抽出しています。これは、Go言語の標準ライブラリがまだ開発途上であったことを示唆しています。
• output メソッド: このメソッドがロギングの核心です。
  • sys.Caller(calldepth) を使用して、ログを呼び出したソースコードのファイル名と行番号を取得します。calldepth は、呼び出しスタックのどの深さから情報を取得するかを制御します。
  • Lshortname フラグが設定されている場合、ファイルパスからファイル名のみを抽出します。shortnames マップは、この処理のパフォーマンスを向上させるためのキャッシュとして機能します。
  • fmt.Sprintf を使って、タイムスタンプ、ファイル名、行番号、ログメッセージを結合し、最終的なログ文字列を生成します。
  • 生成されたログ文字列は、io.WriteString を使って out0 と out1 に書き込まれます。
  • Lcrash または Lexit フラグに応じて、panic または sys.Exit(1) を呼び出し、プログラムの実行フローを制御します。
• Logf と Log メソッド: Logger 型のメソッドとして、フォーマット文字列と引数を受け取る Logf と、引数をそのまま出力する Log が提供されています。これらは内部的に output メソッドを呼び出します。
• ヘルパー関数: Stdout, Stderr などは、事前定義されたロガーを介して簡単にログを出力するためのグローバル関数です。これにより、log.Stdout("message") のように簡潔にロギングを行うことができます。

src/lib/log_test.go の主要部分

• テストの目的: このテストファイルは、新しく追加された log パッケージの基本的な機能が正しく動作することを確認します。コメントに「These tests are too simple.」とあるように、初期段階のシンプルなテストであることが示されています。
• test 関数と testFormatted 関数: これらのヘルパー関数は、ロギングのテストを行うための共通のロジックを提供します。
  • os.Pipe() を使用してパイプを作成し、ロガーの出力先をこのパイプに設定します。これにより、ロガーが出力したメッセージをテストコードで読み取ることができます。
  • NewLogger でロガーを初期化し、Log または Logf メソッドを呼び出してログを出力します。
  • bufio.NewBufRead を使ってパイプからログメッセージを読み取り、期待される出力と比較します。
  • テストの期待値には、ログが出力されるソースコードのファイル名と行番号が含まれているため、テストコードの行番号が変更されると期待値も更新する必要があることがコメントで示されています。
• TestRegularLog, TestShortNameLog, TestRegularLogFormatted, TestShortNameLogFormatted: これらのテスト関数は、Lok フラグと Lshortname フラグの組み合わせで、通常のログ出力とファイル名が短縮されたログ出力が正しく行われることを検証しています。

関連リンク

• Go言語の公式ドキュメント（現在の log パッケージ）: https://pkg.go.dev/log
• Go言語の io パッケージ: https://pkg.go.dev/io
• Go言語の fmt パッケージ: https://pkg.go.dev/fmt
• Go言語の os パッケージ: https://pkg.go.dev/os
• Go言語の time パッケージ: https://pkg.go.dev/time
• Go言語の runtime パッケージ（runtime.Caller）: https://pkg.go.dev/runtime#Caller

参考にした情報源リンク

• Go言語の初期開発に関する一般的な知識
• Gitのコミット履歴と差分表示
• Go言語の標準ライブラリのドキュメント (現在のバージョン)
• Makefile の基本的な構文と用途
• Go言語における panic と recover の概念
• io.Writer インターフェースの概念
• bufio パッケージの基本的な使い方 (テストコードの理解のため)
• os.Pipe の使い方 (テストコードの理解のため)
• Go言語のテストフレームワーク testing の基本的な使い方
• Go言語の初期のビルドシステムに関する情報 (必要に応じて)
• Rob Pike氏のGo言語に関する講演や記事 (必要に応じて)