旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

kong.log

この名前空間にはロギング機能のインスタンスが含まれています。このインスタンスは、以下に挙げるすべてのメソッドを含むテーブルです。

このインスタンスはプラグインごとに名前空間化されています。 プラグイン実行前、Kongはこのインスタンスをプラグイン専用の ロギング機能と交換します。これにより、ログの先頭に デバッグ用のプラグインの名前を付けることができます。

kong.log(…)

noticeレベル（print()と同様）の現在のNginx構成ブロックのerror_logディレクティブによって指定されたロケーションにログラインを書き込みます。

Nginx error_logディレクティブは、log_level、proxy_error_log およびadmin_error_logのKong構成プロパティを介して設定されます。

この関数に与えられた引数は、ngx.log()と同様に連結され、ログ行にはこの関数が呼び出されたLuaファイルと行番号が表示されます。ngx.log()とは異なり、この関数はエラーメッセージの先頭に[lua]ではなく[kong]を付けます。

この関数には任意の型の引数を指定できますが、テーブルの引数は tostring で文字列に変換されます（そのため、設定されていればテーブルの __tostring メタメソッドを呼び出す可能性があります） 。この動作は、 使用を簡素化し、より寛容で直感的なものにしようという点で ngx.log() （ __tostringメタメソッドを定義されるテーブル関数のみ受け入れます） とは、動作が異なります。

ロギングがコア内から呼び出された場合、生成されたログラインの形式は以下のようになります。

[kong] %file_src:%line_src %message

比較すると、プラグインによって生成されるログ行の形式は次のようになります。

[kong] %file_src:%line_src [%namespace] %message

この場合、以下の通りです。

• %namespace：設定された名前空間（この場合はプラグイン名）。
• %file_src：ログの呼び出し元となるファイル名。
• %line_src：ログが呼び出された行番号。
• %message: 呼び出し元によって指定された、連結され引数からなるメッセージ。

たとえば、次の呼び出しがあるとします。

kong.log("hello ", "world")

コア内では、次のようなログ行が生成されます。

2017/07/09 19:36:25 [notice] 25932#0: *1 [kong] some_file.lua:54 hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

プラグイン内から呼び出された場合（たとえば、 key-auth）、名前空間の接頭辞が含まれます。

2017/07/09 19:36:25 [notice] 25932#0: *1 [kong] some_file.lua:54 [key-auth] hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

パラメータ

• … ：ログに送信される前にすべてのパラメータは連結され、文字列化されます。

戻り値

• 何も起こりません。無効な入力に対してはエラーが返されます。

使用法

kong.log("hello ", "world") -- alias to kong.log.notice()

kong.log.LEVEL(…)

kong.log()と同様に、生成されたログの重大度は、 noticeではなく<level id="sl-md0000000">によって与えられています。サポートされているレベルは次のとおりです。

• kong.log.alert()
• kong.log.crit()
• kong.log.err()
• kong.log.warn()
• kong.log.notice()
• kong.log.info()
• kong.log.debug()

ログの形式はkong.log()と同じです。たとえば、次の呼び出しがあるとします。

 kong.log.err("hello ", "world")

コア内では、次のようなログ行が生成されます。

2017/07/09 19:36:25 [error] 25932#0: *1 [kong] some_file.lua:54 hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

プラグイン内から呼び出された場合（たとえば、 key-auth）、名前空間の接頭辞が含まれます。

2017/07/09 19:36:25 [error] 25932#0: *1 [kong] some_file.lua:54 [key-auth] hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

パラメータ

• … ：ログに送信される前にすべてのパラメータは連結され、文字列化されます。

戻り値

• 何も起こりません。無効な入力に対してはエラーが返されます。

使用法

kong.log.warn("something require attention")
kong.log.err("something failed: ", err)
kong.log.alert("something requires immediate action")

kong.log.deprecation(…)

非推奨ログ行を書きます（kong.log.warnと同様）。

この関数には任意の型の引数を指定できますが、テーブルの引数は tostring で文字列に変換されます（そのため、設定されていればテーブルの __tostring メタメソッドを呼び出す可能性があります） 。最後の引数がテーブルの場合、非推奨のメタデータと見なされます。テーブルには、次のプロパティを含めることができます。

{
  after = "2.5.0",   -- deprecated after Kong version 2.5.0 (defaults to `nil`)
  removal = "3.0.0", -- about to be removed with Kong version 3.0.0 (defaults to `nil`)
  trace = true,      -- writes stack trace along with the deprecation message (defaults to `nil`)
}

たとえば、次の呼び出しがあるとします。

kong.log.deprecation("hello ", "world")

コア内では、次のようなログ行が生成されます。

2017/07/09 19:36:25 [warn] 25932#0: *1 [kong] some_file.lua:54 hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

プラグイン内から呼び出された場合（たとえば、 key-auth）、名前空間の接頭辞が含まれます。

2017/07/09 19:36:25 [warn] 25932#0: *1 [kong] some_file.lua:54 [key-auth] hello world, client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

また、メタテーブルでは次の呼び出しを行います。

kong.log.deprecation("hello ", "world", { after = "2.5.0", removal = "3.0.0" })

コア内では、次のようなログ行が生成されます。

2017/07/09 19:36:25 [warn] 25932#0: *1 [kong] some_file.lua:54 hello world (deprecated after 2.5.0, scheduled for removal in 3.0.0), client: 127.0.0.1, server: localhost, request: "GET /log HTTP/1.1", host: "localhost"

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

パラメータ

• … : すべてのパラメータは、ログに送信される前に連結され、文字列化されます （最後のパラメータが表の場合、非推奨のメタデータと見なされます）

戻り値

• なし。無効な入力に対してはエラーが返されます。

使用法

kong.log.deprecation("hello ", "world")
kong.log.deprecation("hello ", "world", { after = "2.5.0" })
kong.log.deprecation("hello ", "world", { removal = "3.0.0" })
kong.log.deprecation("hello ", "world", { after = "2.5.0", removal = "3.0.0" })
kong.log.deprecation("hello ", "world", { trace = true })

kong.log.inspect(…)

kong.log()と同様に、この関数はnoticeレベルのログを生成し、任意の数の引数を受け入れます。検査ログがkong.log.inspect.off()で無効になっている場合、この関数は何も出力せず、CPU サイクルを節約するために “NOP” 関数にエイリアスが付けられます。

この機能は、引数がスペース（" "）で連結され、各引数がきれいに印刷されるという意味でkong.log()とは異なります。

• 番号が出力されます（例: 5 -> "5"）
• 文字列は引用符で囲まれます（例："hi" -> '"hi"'）
• 配列に類似するテーブルがレンダリングされます（例：{1,2,3} -> "{1, 2, 3}"）
• Dictionaryのようなテーブルは複数行でレンダリングされます

この関数はデバッグでの使用を目的としています。この関数は高いコストのかかるフォーマット 操作を実行できるため、本番環境のコードでは使用 を避けるべきです。既存のステートメントは本番環境のコードに残すことができますが、kong.log.inspect.off() を呼び出すことで無効化されます。

ログを書き込むとき、 kong.log.inspect()常に以下の独自のフォーマットを使用します。

%file_src:%func_name:%line_src %message

この場合、以下の通りです。

• %file_src：ログの呼び出し元となるファイル名。
• %func_name: ログが呼び出された関数の名前。
• %line_src：ログが呼び出された行番号。
• %message: 呼び出し元によって指定された、連結され、きれいに出力された引数からなるメッセージ。

この関数はinspect.luaライブラリを使用して、引数をPretty-Print（整形表示）します。

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

パラメータ

• … : パラメータはスペースで連結され、説明どおりにレンダリングされます。

使用法

kong.log.inspect("some value", a_variable)

kong.log.inspect.on()

このロギング機能の検査ログを有効にします。kong.log.inspectの呼び出しでは、引数の適切な書式設定を使用してログ行が書き込まれます。

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

使用法

kong.log.inspect.on()

kong.log.inspect.off()

このロギング機能の検査ログを無効にします。kong.log.inspect()への呼び出しはすべてノップされます。

フェーズ

• init_worker、証明書、書き換え、アクセス、header_filter、応答、body_filter、ログ

使用法

kong.log.inspect.off()

kong.log.set_serialize_value(key,value, options)

serializeカスタムテーブルで使用される値を設定します。

ロギングプラグインは、ログのベースとしてkong.log.serialize()の出力を使用します。 この関数を使用すると、ログ出力をカスタマイズできます。

出力内の既存の値を置き換えたり、nil を渡して既存の値を削除したりするために使用できます。

注： valueパラメーターの型チェックには時間がかかる場合があるため、実際のほとんどのケースではログフェーズで発生するserialize()呼び出しまで延期されます。

フェーズ

• certificate, rewrite, access, header_filter, response, body_filter, log

パラメータ

• key （string）：フィールドの名前。
• value （number|string|boolean|table）：設定される値。テーブルが使用される場合、そのキーは数字、文字列、またはブーリアンである必要があり、その値は数字、文字列、またはそれ自体のようなその他のテーブルを再帰的に使用できます。
• option （table）：2つのエントリを含むことができます。options.modeはset（デフォルトでは常に設定）、add（エントリがすでに存在しない場合にのみ追加）、replace（すでに存在する場合は変更値のみ）にすることができます。

戻り値

• table：リクエスト情報テーブル。

使用法

-- Adds a new value to the serialized table
kong.log.set_serialize_value("my_new_value", 1)
assert(kong.log.serialize().my_new_value == 1)

-- Value can be a table
kong.log.set_serialize_value("my", { new = { value = 2 } })
assert(kong.log.serialize().my.new.value == 2)

-- It is possible to change an existing serialized value
kong.log.set_serialize_value("my_new_value", 3)
assert(kong.log.serialize().my_new_value == 3)

-- Unset an existing value by setting it to nil
kong.log.set_serialize_value("my_new_value", nil)
assert(kong.log.serialize().my_new_value == nil)

-- Dots in the key are interpreted as table accesses
kong.log.set_serialize_value("my.new.value", 4)
assert(kong.log.serialize().my.new_value == 4)

kong.log.serialize()

ログ取得に役立つ情報を含むテーブルを生成します。

この方法は、httpサブシステムで使用できます。

返されるテーブルには、次のフィールドが含まれます。

• client_ip- テキスト形式のクライアントIPアドレス。
• latencies- 要求/プロキシの遅延。
• request.id - リクエストID。
• request.headers - リクエストヘッダー。
• request.method - リクエストメソッド。
• request.querystring - クエリ文字列を要求します。
• request.size- リクエストのサイズ。
• request.urlとrequest.uri - リクエストのURLとURI。
• response.headers - 応答ヘッダー。
• response.size - レスポンスのサイズ。
• response.status - レスポンス HTTP ステータスコード。
• route - ルートオブジェクトが一致しました。
• service - 使用されるサービスオブジェクト。
• started_at - このリクエストが届いたタイムスタンプ（ミリ秒単位）。
• tries -アップストリームの情報。これは配列で、バランサーが再試行された場合は複数のエントリが含まれます。
• upstream_uri - リクエストURIがアップストリームに送信されました。

次のフィールドは、認証されたリクエスト（コンシューマあり）にのみ存在します。

• authenticated_entity - 認証に使用される認証情報。
• consumer- リソースにアクセスするコンシューマエンティティ。

次のフィールドはTLS/HTTPSリクエストにのみ存在します。

• request.tls.version- 接続で使用される TLS/SSL バージョン。
• request.tls.cipher - 接続で使用されるTLS/SSL暗号。
• request.tls.client_verify - mTLS検証結果。 内容は$ssl_client_verifyで説明されているものと同じです。

次のフィールドは、トレーシングプラグイン（OpenTelemetryまたはZipkin）が実行されるリクエストにのみ存在します。

• trace_id - トレースID。

次のフィールドは、Correlation IDプラグインが実行されるリクエストにのみ存在します。

• correlation_id - 相関ID。

警告： この関数は機密データ（APIキーなど）を返す可能性があります。 安全でない場所に書き込む前にフィルタリングを検討してください。

返されたテーブル内のすべてのフィールドは、kong.log.set_serialize_value を使用して変更できます。

次のHTTP認証ヘッダーは、リクエスト内に表示される場合、デフォルトでマスキングされています。

• request.headers.authorization
• request.headers.proxy-authorization

設定にどのようなコンテンツが含まれているかを確認するには、 ロギングプラグイン（例：file-log）のいずれかを有効にします。またログファイルに書き込まれる出力はJSONエンコードされた この関数によって返されるテーブルです。

フェーズ

• ログ

戻り値

• table: リクエスト情報テーブル

使用法

kong.log.serialize()