<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Genta Kamitani on Medium]]></title>
        <description><![CDATA[Stories by Genta Kamitani on Medium]]></description>
        <link>https://medium.com/@genkami?source=rss-6d36fc2f1076------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*Hj5ZjFcbmAv2U_j-U5L4xQ.jpeg</url>
            <title>Stories by Genta Kamitani on Medium</title>
            <link>https://medium.com/@genkami?source=rss-6d36fc2f1076------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 16:44:35 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@genkami/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[社内で書いたデザインドキュメントを(ほぼ)そのまま公開します]]></title>
            <link>https://mixi-developers.mixi.co.jp/design-doc-a6cd1c015ff3?source=rss-6d36fc2f1076------2</link>
            <guid isPermaLink="false">https://medium.com/p/a6cd1c015ff3</guid>
            <category><![CDATA[japanese]]></category>
            <category><![CDATA[google-cloud-platform]]></category>
            <dc:creator><![CDATA[Genta Kamitani]]></dc:creator>
            <pubDate>Thu, 23 Dec 2021 08:23:52 GMT</pubDate>
            <atom:updated>2021-12-23T08:23:52.639Z</atom:updated>
            <content:encoded><![CDATA[<h3>はじめに</h3><p>本記事は、<a href="https://qiita.com/advent-calendar/2021/mixi">ミクシィグループ Advent Calendar 2021</a>の17日目の記事です。そう、17日目の記事です。果たして今は何日でしょうか………。皆さんすみません……… 🙇</p><p>改めまして、ミクシィの開発本部CTO室SREグループの<a href="https://twitter.com/GentaKamitani">神谷</a>です。</p><p>最近は「<a href="https://ghost-scramble.com/">ゴーストスクランブル</a>」という新規ゲームのクローズドβテストのためにインフラ面などを色々と整えていました。その過程で久々にデザインドキュメントを書く機会があったため、内容をほぼそのまま公開してみようと思います。</p><p>※ この記事はあくまで最近書いたデザインドキュメントを公開するというだけのもので、このデザインドキュメントで説明されているものが現時点で社内にあるわけではありません。もしかするとこの先色々な部分が変更になったり、そもそも没になったりする可能性もあります。</p><h3>背景</h3><p>以下の文章は、「<a href="https://ghost-scramble.com/">ゴーストスクランブル</a>」という開発中のゲームで使われているロガーについてのデザインドキュメントです。対象となる読者は主にゴーストスクランブルのサーバーエンジニアを想定しています。対象の範囲が狭いため、この文章はどちらかというと形式張っていない、かつ必要以上に冗長な説明は避けている傾向にあるものとなっています。そのため、文章内には社外の方には伝わりにくい表現や暗黙の前提等が含まれている可能性があります。</p><p>この文章が社外の方にとっても有益なものとなるように、基本的な用語やアプリケーションの構成などについてはこのセクションでできる限り説明しています。また、文章中に現れる内部用語に基づいた変数名、パッケージ名、パス、識別子などはそれぞれ意味の通る別なものに置き換えています。しかし、どうしても一部わかりにくい部分などはあるかと思います。あらかじめご了承ください。</p><h4>デザインドキュメントが説明している対象について</h4><p>このドキュメントは、dlogger v2という内製のロガーについてのデザインドキュメントです。元々あったdlogger v1に対して、さらに拡張性や検索性などを向上させる目的で開発されました。この文章ではdlogger v1自体の設計について詳しくは説明していませんが、おおまかな設計やそれに起因する問題点などはなんとなく把握できる構成になっているかと思います。</p><p>なお、名前のプレフィックスにある “d” は社内プロジェクトのコードネームに由来していますが、ここでは説明しません。</p><h4>ゴーストスクランブルのサーバー構成</h4><p>ゴーストスクランブルのサーバーサイドにおける主なコンポーネントとして、以下のようなものがあります:</p><ul><li>APIサーバー: 主にユーザーの資産を管理するためのサーバーです。クライアントとはgRPCでやりとりを行います。この文章で説明するdloggerは、主にこのAPIサーバーで使われることを想定しています。このサーバーはGoで書かれており、<a href="https://cloud.google.com/kubernetes-engine">Google Kubernetes Engine</a> (以下GKE上)で動作します。</li><li>管理ツール: ゲームの設定情報を管理するためのサーバーです。Vue.jsのフロントエンドとgRPC-Webのサーバーからなります。このサーバーもGoで書かれており、GKE上で動作します。</li><li>ボイスチャットサーバー: ゲーム中にプレイヤーがボイスチャットを行うためのサーバーです。Elixirで書かれており、内製の<a href="https://github.com/xflagstudio/requiem">ReQUIem</a>というライブラリを使ってQuicTransportで音声データをやり取りします。このサーバーはGKE上で動作し、<a href="https://agones.dev/site/">Agones</a>によって管理されています。</li><li>ゲームサーバー: ゲーム中にユーザーの行動をリアルタイムに他のユーザーへ伝えるためのサーバーです。このサーバーのみ様々な事情により<a href="https://cloud.google.com/compute">Compute Engine</a>上で動作しています。</li></ul><h4>GKEでのロギングについての前提知識</h4><p>このデザインドキュメントではGoogle Cloudのロギングに関する機能である<a href="https://cloud.google.com/logging">Cloud Logging</a>と、そのGKEとの連携部分についての知識が暗黙の前提となっています。そのため、これらについても簡単に説明を行います。</p><p>Cloud LoggingはGoogle Cloudのログ分析基盤です。ログはJSONのような構造化されたデータとして保存され、ログエントリの特定のフィールドについて条件が一致するものを検索したり、集計したりすることができます。ログの書き込みは<a href="https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/write">entries.write</a>のようなAPIを用いて行うことができる他、後述するようにGoogle Cloud上のコンポーネントであれば場合によっては特にCloud Loggingの存在を意識することなくログの書き込みを行うこともできます。</p><p>GKEは、先程述べたようなCloud Loggingの存在を意識しなくてよいサービスのうちの一つです。GKE上には(そういう設定をすれば)Google Cloud用の設定がされた<a href="https://fluentbit.io/">Fluent Bit</a>が自動でデプロイされており、何もしなくてもコンテナ上の標準出力や標準エラーに書かれたテキストをCloud Logging上に保存してくれます。また、標準出力等に書かれたデータがJSONのような構造化されたフォーマットであった場合、それらの構造を解釈した上でCloud Loggingに保存してくれます。</p><p>詳細については以下の記事を参照してください:</p><ul><li><a href="https://cloud.google.com/stackdriver/docs/solutions/gke/managing-logs">Managing GKE logs | Operations Suite | Google Cloud</a></li></ul><h3>用語について</h3><p>このデザインドキュメントでは、チーム内のメンバー間で共通認識となっている社内用語や固有名詞、ツール名などについては説明が省略されています。また、外部のツール等についても長い名前については適宜省略するなどして書かれています。このセクションでは、そのような単語についての説明を行います。</p><ul><li>ゴーストスクランブル, ghost-scramble: 私達のチームで現在開発中のゲームです。(<a href="https://ghost-scramble.com/">公式サイト</a>)</li><li>CBT: 11/26–12/3に開催された、クローズドβテストのことを指します。(<a href="https://ghost-scramble.com/news/20211002_2.html">開催概要</a>)</li><li>解析チーム: データ分析や分析基盤の構築に特化したエンジニアのチームです。(<a href="https://mixigroup-recruit.mixi.co.jp/recruitment-category/career/3544/">詳細</a>)</li><li>ghost-scramble-server-api, (単に)API: 上で説明した、ユーザーの資産を管理するためのAPIサーバーを指します。</li><li>zap: Goの有名なロギングライブラリである<a href="https://github.com/uber-go/zap">uber-go/zap</a>を指します。</li><li>logr: Goの有名なロギングライブラリである<a href="https://github.com/go-logr/logr">go-logr/logr</a>を指します。</li><li>proto: <a href="https://developers.google.com/protocol-buffers">Protocol Buffers</a> を指します。元のデザインドキュメントでは序盤で正式な表記を用い、以降では省略形を使うという形でしたが、一貫性のためにこちらで用語説明を行った上で、文章内では省略形で統一します。</li><li><a href="https://cloud.google.com/trace">Cloud Trace</a>: Google Cloudの分散トレーシングシステムです。Cloud Loggingと連携して、特定のトレースに紐付いたログを検索するといった機能もあります。(<a href="https://cloud.google.com/blog/products/management-tools/cloud-monitoring-with-full-stack-observability">詳細</a>)</li></ul><p>以下、本題のデザインドキュメントです。</p><h3>TL;DR</h3><ul><li>dlogger v1 は「protoで定義されたメッセージをログとして送る」ことに特化していたので、解析チームにデータを渡すための諸々をする上では特に困ることはなかった</li><li>dlogger v1 はそれ以外の部分、特に構造化ロギングを行うための機能が足りず、ちょっとデバッグログを出してCloud Loggingで集計するみたいなことができない。結果としてprotoで定義されている部分以外はあんまり機械可読ではなくなってしまった。</li><li>dlogger v1 は「Cloud Logging用にログを吐く部分」「ghost-scramble-server-apiの固有のロジック」「テスト用の機能」などなどが全部密結合しているため、ちょっとログエントリの型を増やしたい程度の変更でもコードの多くの箇所に手を加えないといけなくなり、さらに変更漏れが起きそうな構造になっている</li><li>このへんを解決しようとした結果ほぼ別物になってしまいました。</li><li>dlogger v2は機械可読であることを若干意識する必要があるものの、dlogger v1と比べても使い勝手は特に悪くないはず。</li></ul><h3>ゴール</h3><p>dlogger v2のゴールはだいたい以下のようなものです:</p><ol><li>機械可読なデータとしてロギングを行うことができる(≒構造化ロギングができる)</li><li>特定の第三者にログの内容を渡すために、外部でフォーマットが定義された構造体をログとして送信することができる</li><li>サーバーエンジニアが低コストでログの集計や検索を行うために、フリーフォーマットのキーバリューペアや構造体をログとして送信することができる</li><li>Google Cloud 上のサービスと低コストで連携することができる</li></ol><p>dlogger v1は(明示的に書かれてはいないものの)、このうち主に1(部分的), 2, 4を満たすようなロガーでした。<br>dlogger v2はこれに加えて、1のために足りなかった部分と3を行うことでより検索、集計がしやすいログを吐くことができるようにする目的で設計されています。</p><h3>dlogger v1の問題点</h3><p>上で書いた通り、dlogger v1は「解析チーム向けにフォーマットの決まったデータをログとして送信する」ことに特化していました。実際、CBTリリースまでの時点ではそれ以外でログが使われることはあまり無かったため、この時点ではdlogger v1は目的に合ったロガーであると言えました。</p><p>しかし、今後本リリースにあたって「サーバーエンジニアがバグの特定のために使うログ」「特定の時刻におけるサーバーの状態を把握するためのログ」などが必要になってくるはずです。<br>実際にこのような用途でdlogger v1を使おうとした場合、以下のような部分が問題になってきます:</p><ul><li>protoで定義されているデータしか吐けない</li><li>ロガーに関するあらゆるロジックが密結合している(ため、変更しにくい)</li></ul><h4>問題点の具体例: protoで定義されているデータしか吐けない</h4><p>具体的にこの問題が影響してくるケースを考えてみましょう。例として、staging環境のAPIサーバーに来ているgRPCリクエストのうちINTERNALエラーを返しているもののログだけを絞り込んで、それらのエラーの詳細を眺めてみたいとしましょう。</p><p>APIサーバーのログはCloud Loggingに流れています。まず最初にGoogle Cloudコンソールのログエクスプローラーを開いて、APIサーバーのgRPCリクエストに関するログのみをフィルタしてみましょう。</p><p>ログのクエリはだいたいこんな感じになるはずです:</p><pre>resource.type=”k8s_container”<br>resource.labels.cluster_name=”staging”<br>resource.labels.namespace_name=”staging”<br>labels.k8s-pod/app_kubernetes_io/component=”api”<br>(ログの種類に関するキー)=”(gRPCのリクエストログであることを表す値)”<br>(gRPCのステータスコードに関するキー)=”INTERNAL”</pre><p>しかし、今の所肝心な部分である「ログの種類に関するキー」と「gRPCのステータスコードに関するキー」は存在しません。<br>これらが現時点で存在しない原因の(おそらく)大きなものとして、dlogger v1では「protoで定義されたデータ1個 + 平文のメッセージ」しか吐けないという点があります。<br>現時点でこれらの情報がログに載っていないのは問題ですが、仮に載せられるとしても</p><pre>jsonPayload.msg=”gRPC error: INTERNAL”</pre><p>みたいな内容を構造化されていないテキストとして吐いた後に頑張って正規表現で抽出するしか手段がありません。</p><h4>問題点の具体例: ロガーに関するあらゆるロジックが密結合している</h4><p>さらに、例えばgRPCのリクエストに関するデータを新しいログエントリの型として定義したい場合についても考えてみましょう。<br>仮に、この型を既存の AccessLog(HTTP用) に合わせて GRPCAccessLog という名前で定義するとします。<br>ログエントリの型の追加は、まず最初に dlogger/types に先程の型を定義するところから始まります。</p><pre>type GRPCAccessLog struct {<br>    Code int32 `json:&quot;code&quot;` // gRPC のステータスコード<br>    LogType string `json:&quot;log_type&quot;` // このログが GRPCAccessLog であることを表す値。他に置き場がないのでとりあえずここに定義しています。<br>    Error string `json:&quot;error,omitempty&quot;` // エラーがあった場合、その詳細<br>}</pre><p>実は、型の定義はこれでは不完全です。 dlogger v1 の意図するログを吐くためには、他の必要なフィールドも個別に定義してやる必要があります:</p><pre>type GRPCAccessLog struct {<br>    Code int32 `json:&quot;code&quot;` // gRPC のステータスコード<br>    LogType string `json:&quot;log_type&quot;` // このログが GRPCAccessLog であることを表す値。他に置き場がないのでとりあえずここに定義しています。<br>    Error string `json:&quot;error,omitempty&quot;` // エラーがあった場合、その詳細</pre><pre>// Cloud Logging 向けの共通フィールド<br>    Severity string `json:&quot;severity&quot;`<br>    Time Time `json:&quot;time&quot;`<br>    HTTPRequest HTTPRequest `json:&quot;httpRequest&quot;`</pre><pre>// APIサーバー全体で共通のデータ<br>    Metadata *metadata.Metadata `json:&quot;metadata&quot;`<br>}</pre><p>いくつか足りない共通フィールドがあるかもしれませんが(こういう状況が生まれるの自体あまりよくない)、とりあえず GRPCAccessLog 型はだいたい完成しました。</p><p>次に、今定義した GRPCAccessLog を出力するためのメソッドを Logger に追加します。</p><pre>func (l *Logger) GRPCAccessInfo(req *http.Request, code int32, err error) {<br>    logEntry := &amp;types.GRPCAccessLog{ /* 引数を元にフィールドの中身を埋める */}<br>    jsonEntry, _ := json.Marshal(logEntry) // エラーハンドリング省略<br>    l.config.AccessLogOut.Write(jsonEntry)<br>}</pre><p>しかし、ここで問題が発生します。 config にあるログの出力先の候補は、現時点で AccessLogOut 以外に ErrorLogOut と ApplicationLogOut があります。<br>GRPCAccessLog は名前上 AccessLog ではあります。そういう意味では、 AccessLogOut にこのログを出力するのが正しそうな感じがします。<br>しかし、 AccessLog という出力先は、それ自身が生まれるタイミングでは GRPCAccessLog の存在なんて考えてもいなかったはずです。そう考えると、 AccessLog に出力してしまうのは後々不要な混乱を生みそうな気がします。<br>それではこのログはどこへ出力すればよいでしょうか。エラーが出た場合は ErrorLogOut に吐くのが適切そうな気がしますが、先程と同様の理由でそうではない気もします。ここはそれぞれの XXXOut の責務をややこしくさせないために、 GRPCAccessLog 専用の出力先である GRPCAccessLogOut を用意することにしましょう。</p><p>dlogger/config.Config を以下のように変更します:</p><pre>type Config struct {<br>    ...<br>    AccessLogOut      io.Writer<br>    GRPCAccessLogOut io.Writer<br>    ErrorLogOut       io.Writer<br>    ApplicationLogOut io.Writer<br>    ...<br>}</pre><pre>func (c Config) Validate() error {<br>    if c.AccessLogOut == nil {<br>        return errors.New(&quot;AccessLogOut is required&quot;)<br>    }<br>    if c.GRPCAccessLogOut == nil {<br>        return errors.New(&quot;GRPCAccessLogOut is required&quot;)<br>    }<br>    ...<br>}</pre><p>その後、先程の GRPCAccessInfo を変更して、ログを GRPCAccessLogOut に書き込むように変更します。</p><pre>func (l *Logger) GRPCAccessInfo(req *http.Request, code int32, err error) {<br>    logEntry := &amp;types.GRPCAccessLog{ /* 引数を元にフィールドの中身を埋める */}<br>    jsonEntry, _ := json.Marshal(logEntry) // エラーハンドリング省略<br>    l.config.GRPCAccessLogOut.Write(jsonEntry)<br>}</pre><p>これで完成のように見えますが、実はまだ見落としがあります。テスト用の機能である Observer の存在です。<br>dlogger のログ出力関数は、テストのためにdlogger.Observer がいた場合、 Observer にもログを書き込む必要があります。</p><pre>func (l *Logger) GRPCAccessInfo(req *http.Request, code int32, err error) {<br>    logEntry := &amp;types.GRPCAccessLog{ /* 引数を元にフィールドの中身を埋める */}<br>    jsonEntry, _ := json.Marshal(logEntry) // エラーハンドリング省略<br>    if l.observer != nil {<br>        l.observer.Write(logEntry.Severity, logEntry)<br>    }<br>    l.config.GRPCAccessLogOut.Write(jsonEntry)<br>}</pre><p>おそらく、これで GRPCAccessInfo は完成です。<br>しかし、 Observer の部分の実装が本当に正しいのかは自分にも自信がありません。 Observer への書き込み機能はかなりアドホックに作られているためです。例えば先程の AccessLog の場合は GRPCAccessLog と同様に logEntry 自身を Observer に書き込むような実装になっていますが、別種のログである ApplicationLog を書き込む際は logEntry 自身ではなく logEntry.Message (※注: ログの種類によってはここにテキストのメッセージが入っています)を書き込んでいたりします。<br>この2種類の Observer の使い方に何らかの規則があるのか、それともうっかりそうなってしまったのかは、少なくとも自分にはわかりません。</p><p>さらに、この実装には既に問題点があります。 Config に新たな XXXOut を足してしまったことです。このため、 dlogger を使っている他のコンポーネント(例えばゴーストスクランブルの管理ツールや、今後生まれる予定の社内の別サービスとの連携サーバー等)は、仮に gRPC を使っていなかったとしても GRPCAccessLogOut に何かしらを指定しなければならなくなってしまいました。</p><p>それだけではありません。先程例に挙げたコードからわかる通り、ログエントリの共通フィールドやログ出力部分などの共通で使う部分に変更が加わった場合、全てのログエントリの型やそれらを出力する関数を全部見て回って、適切に修正を行う必要があります。<br>このような状態でバグを生まずにログの種類を追加していくのはおそらく不可能でしょう。(現時点でも既に共通フィールドが足りてなさそうなログエントリの型があったり、先程挙げたように Observer の取り扱いを間違えていそうな部分があったりします。)</p><h4>問題点の具体例: まとめ</h4><p>dlogger v1は解析チーム向けにスキーマの決まったデータを出力するという点においては十分な機能を持っていました。しかし、今後本リリースに向けてデバッグ用途、集計用途のログが増えてきた場合、dlogger v1は以下のような部分が問題になってくるはずです:</p><ol><li>新しいログエントリ型とその出力関数を dlogger 内部に定義しないとログエントリにフィールドを生やせない(フィールドを生やすためのコストがかなり大きい)</li><li>1 により、特定のアプリケーション固有のログを定義したい場合、他のアプリケーションも変更の影響を受けてしまう</li><li>Cloud Logging用の機能、テスト用の機能、アプリケーション固有の機能が全て密結合している</li><li>3 により、共通部分に変更が加わった場合、全てのログエントリ型とそれらの出力用関数も全部変更しないといけない可能性がある。これらを全て整合性を保ったまま変更するのは難しい</li><li>2, 3 により、他のアプリケーションがCloud Logging向けのログを吐きたいだけの場合には dlogger を使い回すことができない</li></ol><h3>問題点に対する解決方法のアプローチ</h3><h4>よりGoでよくあるようなログのインターフェースに変更</h4><p>そもそもの問題として、コードのある一部が「ログとして何を吐くべきであるか」という完全な情報を持っていることは基本的にありません。今起こっている問題の根本の部分は、「ログとして何を吐くべきであるか」についての完全な情報を dlogger/types にあるログエントリの型が全て知っていないといけないということにあると思っています。</p><p>これを解決するために、 zap や logr のようなより標準的な Go のログインターフェースを導入します。</p><p>ここでいう「標準的な Go のログインターフェース」とは、合成可能なキーバリューペアによる構造化ロギングを行えるものを指します。</p><p>この定義について詳しく説明します。ここで、構造化ロギングとはログが機械可読な形で出力される想定の設計がされている状態のことを指します。機械可読であるとは、ログエントリを検索、集計するようなプログラム(もしくはクエリ)が自然に(余計な努力無く)書けるようにログエントリが設計されていることを指します。<br>より具体的には、ここではログエントリが例えば JSON, MessagePack, CBOR などの、プログラムに読ませる想定の広く使われているデータフォーマットで表現されている状態を想定しています。</p><p>次に、合成可能とは、「ロガーをラップして、出力時に指定されたデータの他に追加のデータを出力できるようなロガーにする」ことができる状態を指します(※注: 「合成可能」はこの説明のために定義した語で、一般的に使われているものではありません)。擬似コードで説明すると、例えば以下のようなインターフェースのロガーが「合成可能なロガー」に該当します:</p><pre>logger.Info(“msg”, “hello”)<br>// Output: {“msg”: “hello”}</pre><pre>logger2 := logger.With(“wrapped”, true)<br>logger2.Info(“msg”, “bye”)<br>// Output: {“msg”: “bye”, “wrapped”: true}</pre><p>2021年現在でよく使われる Go のロガーは、多くがこのようなことができる「合成可能な」ロガーになっています。<br>先程述べた “コードのある一部が「ログとして何を吐くべきであるか」という完全な情報を持っていることは基本的にない” という問題を解決する上で、ロガーが合成可能であることは非常に重要です。<br>特に HTTP や gRPC の API を提供するようなサーバーである場合、ログとして吐くべき具体的な情報は各 interceptor や middleware が部分的にのみ知っているというような場合が多いです。このような場合では、各 interceptor はログの情報を部分的にロガーに合成し、内側の処理に引き渡していくというような動作ができることが必須になってきます。</p><p>ところで、 dlogger v1 はこの問題を部分的に解決しています。 dlogger v1 はロギングのために必要な情報が全て context.Context に入っているという前提の上で、ログを吐く際にこれらの情報を都度 Context から取り出していました。<br>ただし、この方法では必要な情報が1つ増えるたびにログ出力メソッド側でもそれを取り出すための変更を加えないといけません(加えて、先程のコード片から推察できるようにあらゆるログ出力メソッドに対してこういう変更を加えていく必要があります)。この問題が、 dlogger v1 のもう一つの問題である密結合につながってきます。</p><h4>コンポーネントの分割</h4><p>現状の dlogger v1 は、主に「Cloud Logging用にログを吐く部分」「ghost-scramble-server-apiの固有のロジック」「テスト用の機能」の3つが密結合しています。 これらは本来互いにあまり関係ない処理であるため、以下のようになっていると望ましいです:</p><ul><li>Cloud Logging のログフォーマットについての変更を行いたい場合(例えば、新たに Cloud Trace のトレースIDを追加したくなった場合)、Cloud Loggingに関連するパッケージのみに変更を加える(ロガー本体には変更を加えなくてよい)。</li><li>ghost-scramble-server-api固有のロジックについての変更を行いたい場合、 ghost-scramble のリポジトリの /ghost-scramble-server/ 以下のパッケージのみに変更を加える(ロガー本体には変更を加えなくてよい)。</li><li>ログ出力用の関数やメソッドは、今標準エラーにログを吐いているのか、それともテスト用途でメモリ上にログを吐いているのかを区別しなくてよい。</li></ul><p>ロガーがこのような状態であることを目指すため、 dlogger v2 は以下で述べるような構成になっています。</p><h3>dlogger v2の概要</h3><p>dlogger v2 は、 v1 と比べて以下の特徴を持っています:</p><ul><li>dlogger v2 の本体はただのインターフェースであり、具体的な出力部分の実装とは完全に分離されている</li><li>dlogger v2 は、プログラムによって検索、集計が容易な機械可読なログを吐くことを意図している</li><li>dlogger v2 は、 v1 と同様に proto でスキーマを定義されたデータをメッセージとして出力することができる</li><li>dlogger v2 は、 proto でスキーマを定義されていないデータも自由に出力することができる</li></ul><p>以下で、これらについて具体的なコード例とともに説明します。</p><h4>ログインターフェースとログ実装の分離</h4><p>dlogger v2 の本体は、ただのログ API を提供するインターフェースです(※ Go の用語としての interface ではありません)。ログが具体的にどのように出力されるかは、ログ出力部分の実装である LogSink が決定します。</p><pre>type Logger struct { /* ... */ }</pre><pre>func New(sink LogSink) *Logger { /* ... */ }</pre><pre>func (l *Logger) Debug(t LogType, fields ...Field) { /* ... */ }<br>func (l *Logger) Info(t LogType, fields ...Field) { /* ... */ }<br>func (l *Logger) Error(t LogType, fields ...Field) { /* ... */ }</pre><pre>type Field struct { /* ... */ }<br>func F(key string, value interface{}) Field { /* ... */ }</pre><pre>type LogSink interface {<br> Log(Severity, LogType, ...Field)<br> /* ... */<br>}</pre><p>Logger は、 Cloud Logging のセマンティクスに沿ったログ出力を行うためのAPIです。中身は LogSink の薄いラッパーになっています。</p><p>LogSink は、ログの具体的な出力方法を規定します。 LogSink の中には標準エラーにJSONを出力するものがいるかもしれませんし、 Cloud Logging の entries.write を直接叩くものがいるかもしれません。どこにもログを出力せずに破棄するようなものもいるかもしれません。</p><p>(※ Go のログ事情に詳しい人は、これが logr にかなり似ていることに気付くかと思います。実際、 dlogger v2 は logr (やその他の Go のロギングライブラリ)を大きく参考にしています。このドキュメントの後半で logr との比較についても述べます。)</p><h4>機械可読性の向上</h4><p>先程のコード例に出てきた LogType は、ログの唯一の必須フィールドです。この値は例えば com.xflag.ghost-scramble.application.quest.started のような、ログエントリの種類を識別するための、階層的な文字列が想定されています。<br>多くのロギングライブラリがメッセージに相当するものを必須フィールドにしているのに対して、 dlogger v2 では機械用の分類に使うこの値のみが必須になっています。</p><p>この変更によって、上で例に挙げた「gRPCのリクエストに関するログのみ検索することができない」というような状況は解決されます。</p><p>また、後述するように構造化されたデータを(dlogger v1 に比べて)簡単に出力できるようになっているため、機械可読性はかなり向上しているはずです。</p><h4>protoで定義されたデータの出力</h4><p>dlogger v1 と同様に、 dlogger v2 は proto でスキーマの定義されたデータをログとして出力することができます。<br>例えば、 pb というパッケージにログ用に定義されたメッセージが定義されているとすると、 dlogger v2 は次のようにこれらのメッセージを出力することができます:</p><pre>import pb &quot;...&quot;</pre><pre>logger.Info(&quot;com.xflag.ghost-scramble.example&quot;,<br>    dlogger.F(&quot;hogeMsg&quot;, &amp;pb.HogeMsg{ .. }), dlogger.F(&quot;fugaMsg&quot;, &amp;pb.FugaMsg{ .. }))</pre><p>dlogger v1 のときのように、共通フィールドを気にしたりロガーに新たなメソッドを生やしたりする必要はありません。</p><p>なお、protoで定義されたメッセージが実際にどのようなフォーマットで出力されるのかは具体的な LogSink によります。テストの場合はメッセージをそのままメモリ内に保持しておいて後から検証できるようにしたいかもしれないですし、本番環境の場合は <a href="https://pkg.go.dev/google.golang.org/protobuf@v1.27.1/encoding/protojson">protojson</a> でエンコードして標準エラーに出力したいかもしれません。</p><h4>protoで定義されていない、フリーフォーマットなデータの出力</h4><p>protoで定義されていないメッセージも、先程と全く同様の方法で出力することができます。ここが dlogger v1 との大きな違いです。</p><pre>logger.Info(&quot;com.xflag.ghost-scramble.example&quot;,<br>    dlogger.F(&quot;msg&quot;, &quot;Hello&quot;), dlogger.F(&quot;to&quot;, &quot;world&quot;))</pre><p>また、よく使うフィールドについては専用のコンストラクタを用意してもよいでしょう:</p><pre>var req *http.Request<br>var err error<br>logger.Info(&quot;com.xflag.ghost-scramble.system.http.responseSent&quot;,<br>    field.Msg(&quot;response sent by API server&quot;), field.HTTPRequest(req), field.Error(err))</pre><p>こうすることによって、フィールド名の一貫性が保たれるという利点もあります。この利点がロガー本体に手を加えず実現できるということも重要なポイントです。</p><p>なお、現在時刻のような動的に変わる値を出力するために、 DynamicField というものも用意されています。</p><pre>logger = logger.WithDynamicField(func() dlogger.Field {<br>    return dlogger.F(&quot;time&quot;, time.Now())<br>})</pre><h3>dlogger v1 と v2 の比較</h3><p>dlogger v2 の機能の大部分については上で述べました。次に、 dlogger v1 でできていたことを dlogger v2 で行うためにはどのようにすればよいかを説明します。</p><p>なお、以降では v1 で終わるパッケージ名や変数名を dlogger v1 のもの、 v2 で終わるものを dlogger v2 のものとします。</p><h4>シンプルなデバッグログの出力</h4><p>シンプルなログの場合、 dlogger v2 は LogType が必須である分簡潔さはやや失われます:</p><pre>// 旧<br> loggerv1.Info(&quot;hello world&quot;)</pre><pre>// 新<br> loggerv2.Info(&quot;com.xflag.ghost-scramble.application.hello&quot;, fieldv2.Msg(&quot;hello world&quot;))</pre><p>LogType を毎回全部書くのが煩雑であれば、専用の関数を用意してもよいでしょう:</p><pre>func Application(name LogType) LogType { return &quot;com.xflag.ghost-scramble.application.&quot; + name }<br> ...<br> loggerv2.Info(Application(&quot;hello&quot;), fieldv2.Msg(&quot;hello world&quot;))</pre><p>値付きの場合は、以下のようになります。 dlogger v2 のほうがやや煩雑であるものの、許容範囲であると思っています。<br>また、この煩雑さを受け入れることによってその後の集計や検索は圧倒的に楽になるはずです。</p><pre>// 旧<br> loggerv1.Info(fmt.Sprintf(&quot;Gacha: got %d items&quot;, itemCount))</pre><pre>// 新<br> loggerv2.Info(&quot;com.xflag.ghost-scramble.application.gacha.gotItems&quot;,<br>  fieldv2.Msg(&quot;Gacha: got items&quot;), dloggerv2.F(&quot;itemCount&quot;, itemCount))</pre><p>なお、 fieldv2 パッケージには先程述べたようなよく使われるフィールドのコンストラクタが定義されているものとします。</p><h4>既存のprotoで定義されたログの出力</h4><p>既存のprotoで定義されたログについては、 dlogger v2 は専用のメソッドを用意することなく出力することができます:</p><pre>// 旧<br> loggerv1.HTTPInfo(*req, 200, respSize, startedAt, latency)</pre><pre>// 新<br> reqEntry := fieldv2.NewHTTPRequestBuilder().<br>  Request(req).Status(200).Latency(latency).Complete() // おそらくこんな感じの builder を用意します<br> loggerv2.Info(&quot;com.xflag.ghost-scramble.http.request&quot;, fieldv2.HTTPRequest(reqEntry))</pre><h4>メタデータの付与</h4><p>例として、ログエントリに付加的な情報として Cloud Trace のトレース名を出力したいような場合を考えます。</p><pre>// 旧<br> loggerv1.SetMetadata(dloggerv1.TraceId, &quot;XXXXX&quot;)<br> loggerv1.Info(&quot;hoge&quot;)</pre><pre>// 新<br> loggerv2 = loggerv2.WithFields(dlogger.F(&quot;logging.googleapis.com/trace&quot;, &quot;XXXXX&quot;))<br> loggerv2.Info(&quot;com.xflag.ghost-scramble.example&quot;, fieldv2.Msg(&quot;hoge&quot;))</pre><p>dlogger v1 は一見 v2 と同程度の簡潔さでこれを達成できているように見えます。しかし、メタデータに新たなフィールドを足したい場合は、まずは dloggerv1/metadata.Metadata 構造体にフィールドを追加し、その後 dloggerv1.Logger.SetMetadata を修正して新たなフィールドに対応させる必要があります。重要なのは、この変更がロガー本体に対して起こることと、それによって新たなフィールドを使う必要が無いコンポーネントもこの変更の影響を受ける可能性があることです。</p><p>これに対して、 dlogger v2 はロガー自体には1行の変更も加えることなく同じ目的を達成することができます。</p><h4>複数の出力先への振り分け</h4><p>dlogger v1 では、出力先は dloggerv1/config.Config のフィールドとして定義されていました。どの出力先にどのログを吐くかは個別のログ出力関数が決めていました。<br>ログの出力先を増やすには、 dlogger v1 のロガー本体が依存している dloggerv1/config.Config のフィールドを追加する必要がありました。これはもちろん dlogger v1 を使っている全てのコンポーネントが影響を受けます。</p><p>dlogger v2 はログAPIと出力方法が完全に分離しているので、 LogSink として振り分けを行うようなものを定義してしまえば問題は解決します。</p><p>例えば、解析チーム向けのログが com.xflag.ghost-scramble.analysis.*, HTTPアクセスログが com.xflag.ghost-scramble.system.http.request という LogType をそれぞれ持つものと仮定すると、これらのログだけを別なところに振り分けるようなロガーは以下のようにして作ることができるかもしれません:</p><pre>var defaultSink dloggerv2.LogSink<br> var analysisSink dloggerv2.LogSink<br> var httpSink dloggerv2.LogSink<br> loggerv2 := dloggerv2.New(<br>  routerv2.NewRouter(<br>   defaultSink,<br>   routerv2.NewRule(&quot;com.xflag.ghost-scramble.http.request&quot;, httpSink),<br>   routerv2.NewRule(&quot;com.xflag.ghost-scramble.analysis&quot;, analysisSink),<br>  ),<br> )</pre><p>routerv2.NewRouter で作られる LogSink は、ログエントリの中身を LogType のプレフィックスによって分類し、それぞれ対応する LogSink に振り分けるようなものです。<br>このような LogSink の実装方法の詳細についてはこのドキュメントには書きませんが、実装するのは(振り分けルールの数が少ないうちは)比較的楽なはずです。</p><p>重要な点として、このような振り分けロジックの実装は dlogger v2 の外で行うことが可能であるということと、この振り分け機能を使いたくないコンポーネントはなんの影響も受けることがないということがあります。</p><h4>テスト</h4><p>dlogger v1 では、ログが吐かれているかどうかのテストは dloggerv1.Logger 組み込みの Observer という機能によって行われていました:</p><pre>obv1 := dloggerv1.NewObserver()<br> loggerv1 := dloggerv1.NewTestLogger().Observe(obv1)<br> msgv1 := &amp;logpbv1.SomeMessage{ /* ... */ }<br> loggerv1.GameInfo(msgv1) // この種のメッセージは GameInfo というメソッド経由で吐くことになっています<br> found := false<br> for _, v := range obv1.Messages() {<br>  // 本当はこうやって存在確認したほうがいいですが、 Expect(Messages()).To(Equal(...)) してるテストも既にあります。<br>  // そのようなテストは近いうちに壊れます。<br>  if m, ok := v.(proto.Message); ok &amp;&amp; proto.Equal(m, msgv1) {<br>   found = true<br>   break<br>  }<br> }<br> Expect(found).To(BeTrue())</pre><p>(※ 上述した内容ですが、 Observer に登録されているメッセージは常に GameInfo() に渡したものと同一であるとは限りません。ログの種類によっては違う方法で比較する必要があるかもしれません。)</p><p>dlogger v2 はログAPIと出力方法が完全に分離しているので、 Observer はそういう LogSink として個別で定義することができます。 Logger本体とテスト用機能が分離しているので、テストしたい内容に応じて別な LogSink を使うこともできるかもしれません。</p><pre>obv2 := observerv2.New()<br> loggerv2 := dloggerv2.New(obv2)<br> msgv2 := &amp;logpbv1.SomeMessage{ /* ... */ }<br> loggerv2.Info(&quot;com.xflag.ghost-scramble.example&quot;, dloggerv2.F(&quot;data&quot;, msgv2))<br> // ↓吐かれたメッセージを確認するために、こういうメソッドを用意する予定です<br> filtered := obv2.Snapshot().Filter(<br>  observerv2.LogType(&quot;com.xflag.ghost-scramble.example&quot;),<br>  observerv2.ProtoField(&quot;data&quot;, msgv2),<br> ).All()<br> Expect(len(filtered)).To(Equal(1))</pre><p>あるいは、次のような gomega matcher を作ってもよいかもしれません:</p><pre>Expect(obv2).To(HaveLog(<br>  observerv2.LogType(&quot;com.xflag.ghost-scramble.example&quot;),<br>  observerv2.ProtoField(&quot;data&quot;, msgv2),<br> ))</pre><p>テスト用の都合のためにロガー本体に手を加える必要がないため、開発者はテスト内容のニーズに応じてどのような手段を取ることもできます。</p><h3>dlogger v2 がゴールを満たせるものであるかの確認</h3><p>この文章の序盤で、以下の4つを dlogger v2 のゴールとして挙げました。ここでは、 dlogger v2 が実際にこれらを満たしているかを確認していきます。</p><ol><li>機械可読なデータとしてロギングを行うことができる(≒構造化ロギングができる)</li><li>特定の第三者にログの内容を渡すために、外部でフォーマットが定義された構造体をログとして送信することができる</li><li>サーバーエンジニアが低コストでログの集計や検索を行うために、フリーフォーマットのキーバリューペアや構造体をログとして送信することができる</li><li>Google Cloud 上のサービスと低コストで連携することができる</li></ol><p>なお、説明の都合上、以下の説明は上記の順序とは違う順番で書いています。</p><h4>フリーフォーマットのキーバリューペアや構造体をログとして送信することができる</h4><p>「protoで定義されていない、フリーフォーマットなデータの出力」のセクションに書いたとおり、 dlogger v2 では、 zap や logr に近いインターフェースで任意の値や構造体を、その構造を残したままログとして出力することができます。</p><pre>var req *http.Request<br>var err error<br>logger.Info(&quot;com.xflag.ghost-scramble.system.http.responseSent&quot;,<br>    field.Msg(&quot;response sent by API server&quot;), field.HTTPRequest(req), field.Error(err))</pre><p>ログが具体的にどのような形式で出力されるかは、具体的な LogSink によります。</p><h4>フォーマットが定義された構造体をログとして送信することができる</h4><p>「protoで定義されたデータの出力」のセクションに書いたとおり、 dlogger v2 では、protoで定義されたデータをそれ以外と特に区別することなくログとして出力することができます。</p><pre>import pb &quot;...&quot;</pre><pre>logger.Info(&quot;com.xflag.ghost-scramble.example&quot;,<br>    dlogger.F(&quot;hogeMsg&quot;, &amp;pb.HogeMsg{ .. }), dlogger.F(&quot;fugaMsg&quot;, &amp;pb.FugaMsg{ .. }))</pre><p>ログの具体的な出力形式は LogSink に依存しますが、 <a href="https://pkg.go.dev/google.golang.org/protobuf@v1.27.1/encoding/protojson">protojson</a> のようなフォーマットを想定しています。</p><h4>機械可読なデータとしてロギングを行うことができる</h4><p>上記2つで説明した内容に加えて LogType によるログの種類の区別によって、 dlogger v2 は現代的なロギングライブラリに求められているものと同等の機械可読性を備えています。</p><h4>Google Cloud 上のサービスと低コストで連携することができる</h4><p>「ログインターフェースとログ実装の分離」のセクションに書いたとおり、 dlogger v2 は Cloud Logging のセマンティクスに沿っています。また、 Cloud Logging においてよく使われる httpRequest や logging.googleapis.com/trace などのフィールドのコンストラクタを提供することによって、例えば以下のように Cloud Logging で必要とされるフィールドを扱うことができます。</p><pre> logger = logger.WithFields(field.Trace(&quot;logging.googleapis.com/trace&quot;, &quot;XXXXX&quot;))</pre><pre>reqEntry := field.NewHTTPRequestBuilder().<br>  Request(req).Status(200).Complete()<br> logger.Info(&quot;com.xflag.ghost-scramble.http.request&quot;, fieldv2.HTTPRequest(reqEntry))</pre><h3>他のロギングライブラリとの比較</h3><p>ここでは、 Go で一般的に使われているロガーとして logr と zap を例に挙げ、それらと dlogger v2 との間の違いを説明します。</p><h4>go-logr/logr</h4><p><a href="https://github.com/go-logr/logr">go-logr/logr</a> は、 Go で最も使われているロギングライブラリのうちの一つです。 dlogger v2 は logr にインスパイアされており、インターフェースも酷似しています。</p><p>両者の間の大きな違いは、 dlogger v2 が Cloud Logging のセマンティクスに沿っていることです。より具体的かつ重要な違いとしては、 logr が相対的な V-level によるログレベルを用いているのに対し、 dlogger v2 は DEBUG, INFO, ERROR などの古典的なログレベルを用いていることがあります。 dlogger v2 は以下の理由により V-level を用いていません:</p><ul><li>ゴーストスクランブル(含むミクシィのサービスのいくつか)は Google Cloud にロックインされる代償として一般性を保つための工数を削減しているという技術的な選択を行っているため、ロガーについても同様の選択をすべきである。</li><li>チームの人数が比較的少なく、今後も大きく増えない(何が起こってもおそらく20人にはならない)はずなので、 V-level による相対的ログレベルのメリットがあまりない。あるログが本番環境でノイズになるのであれば単にそのログを DEBUG レベルに変更するPRを出すだけで済むような規模のチームである。</li></ul><h4>zap</h4><p><a href="https://github.com/uber-go/zap">uber-go/zap</a> も Go で最も使われているロギングライブラリのうちの一つです。 zap と dlogger v2 との違いは、前者がログ実装であるのに対し、後者の本体はただのインターフェースであるということです(※1)。</p><p>dlogger v2 はログ出力部分の内部実装として zap を使う選択をすることもできます。現状は <a href="https://pkg.go.dev/google.golang.org/protobuf@v1.27.1/encoding/protojson">protojson</a> などを用いた独自の LogSink を用いていますが、後から zap を用いたものに切り替えるという可能性もあります。おそらく、現状の LogSink ではパフォーマンスにクリティカルな影響が出てくるといったタイミングでは zap を使うという選択肢が出てくるかもしれません。しかし、今の所ログ部分がボトルネックになる可能性はあまりなさそうなので zap は使っていません。</p><p>※1 zap も zap.Logger がインターフェースで zapcore.Core が出力部分の実体という解釈をすることもできるかもしれません。ただし、それでも zap.Logger の部分の実装は logr や dlogger v2 のものに比べればかなり分厚いものではあります。</p><h3>おわりに</h3><p>今回の記事は、社内で書いたデザインドキュメントをそのまま公開するだけという内容のものでした。他社のデザインドキュメントを見る機会はあまりないと思うので、何らかの参考などになれば幸いです。</p><p>なお、ゴーストスクランブルにおいてSREチームが行っている活動は、他にも以下のような記事で紹介されています:</p><ul><li><a href="https://qiita.com/shka0909/items/ea0ec3ddaecb3dfa8239">gRPC + Locust + boomerで負荷試験をしてみた</a></li><li><a href="https://mixi-developers.mixi.co.jp/kubeconform-2bb477371e06">kubeconformを使ったKubernetes Manifestの型チェックをCIに仕込んでレビューを楽にしよう!</a></li></ul><p>次回は <a href="https://qiita.com/atpons">atpons</a> さんによる、「<a href="https://atpons.hateblo.jp/entry/20211218/1639758084">SECCON CTF 2021 スコアサーバー（バックエンド） writeup</a>」でした！(過去形)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a6cd1c015ff3" width="1" height="1" alt=""><hr><p><a href="https://mixi-developers.mixi.co.jp/design-doc-a6cd1c015ff3">社内で書いたデザインドキュメントを(ほぼ)そのまま公開します</a> was originally published in <a href="https://mixi-developers.mixi.co.jp/">MIXI DEVELOPERS</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>