Java と Kotlin(JVM)
Java と Kotlin のサービス(Spring、Ktor、素の JVM)から構造化ログを送ります。Logback の appender 付き。Kotlin 標準ライブラリ以外の依存関係はありません。
JVM SDK は Java 11 以降で動作します。Kotlin で書かれていて、すべての関数を Java から呼び出せます。Android SDK と同じエンジン(lyrelog-core)で動き、Kotlin 標準ライブラリ以外の依存関係はありません。SLF4J と Logback のレコードは、別のオプションの appender を通して取り込めます。
社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは、Gradle や Maven で com.lyrelog:lyrelog-jvm を取得できません。Maven Central になく、リポジトリも非公開で、まだリリースもないためです。
インストール
Maven Central から取得します。Gradle では build.gradle.kts に次のように書きます。
dependencies {
implementation("com.lyrelog:lyrelog-jvm:0.1.0")
// Optional: SLF4J and Logback records (Spring Boot's default logging) to Lyrelog.
implementation("com.lyrelog:lyrelog-jvm-logback:0.1.0")
}Maven では pom.xml に次のように書きます。
<dependencies>
<dependency>
<groupId>com.lyrelog</groupId>
<artifactId>lyrelog-jvm</artifactId>
<version>0.1.0</version>
</dependency>
<!-- Optional: SLF4J and Logback records to Lyrelog. -->
<dependency>
<groupId>com.lyrelog</groupId>
<artifactId>lyrelog-jvm-logback</artifactId>
<version>0.1.0</version>
</dependency>
</dependencies>appender は Logback を持ち込みません。アプリケーションがすでに使っているもの(1.3 以降)を使います。
はじめる
一度だけ、できるだけ早く呼びます。main の中で、フレームワークが起動する前です。
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
fun main(args: Array<String>) {
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"), // a server key, lyr_srv_...
platform = "api",
))
runApplication<OrdersApplication>(*args) // or embeddedServer(Netty, ...) in Ktor
}Java では次のとおりです。
import com.lyrelog.Configuration;
import com.lyrelog.Lyrelog;
public static void main(String[] args) {
Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY")).platform("api").build());
SpringApplication.run(OrdersApplication.class, args);
}プロジェクトの API keys ページ(Send events from a server)で作成したサーバーキー lyr_srv_... を使ってください。これはシークレットです。サーバーの環境変数に置き、アプリや Web ページには決して含めないでください。そのイベントは検証済みになり、1 アドレスあたりの 1 日の割り当て(月間イベント数の一部)も適用されません。インジェストキー lyr_ing_... でも動きますが、そのイベントは検証済みになりません。
start は Lyrelog を開始したときに true を返します。動作中に 2 回目の呼び出しをしても無視され、false を返します。キーが null または空白の場合は何も開始せずに false を返し、以降の呼び出しもすべて何もしません。そのため、開発中やテストで環境変数が設定されていなくてもサービスは止まりません。start より前に記録したイベントは無視されます。start が例外を投げることはありません。
イベントは https://ingest.lyrelog.com に送られます。別の送信先に送る場合にのみ endpoint を指定してください。指定するのはベース URL で(.../v1/events:batch のパスを貼り付けても取り除かれます)、https:// でなければなりません。localhost、127.0.0.1、::1 の場合は http:// も使えます。それ以外の endpoint は拒否されます。何も送信されず、SDK はその旨を診断メッセージで一度だけ伝えます。
イベントを記録する
レベルごとに 1 つの関数があります:trace、debug、info、notice、warning、error、critical、または Lyrelog.log(level, message, ...)。
Lyrelog.info("checkout_done", attrs = mapOf("plan" to "pro", "latency_ms" to 412))
Lyrelog.error("payment_failed",
category = "billing",
attrs = mapOf("code" to "card_declined"),
payload = mapOf("response" to body),
)属性には文字列、数値、真偽値、null、リスト(文字列として送られます)、4 階層までの入れ子のマップを使えます。payload には任意のマップ、リスト、値を使えます。ログの呼び出しはブロックせず、例外も投げません。イベントをコピーしてすぐに返ります。close の後は、ログの呼び出しは何もしません。
領域ごとのロガー
val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))ロガーは作成も保持も軽量です(フィールドや companion object に置けます)。呼び出された時点で動作している Lyrelog に記録するので、start の前に作成しておけます。
ユーザー
サーバーは多くのユーザーを同時に扱います。ユーザーはイベントごとに、または 1 つのリクエストの処理単位で設定してください。
Lyrelog.info("checkout_done", user = customerId) // for this event only
Lyrelog.userScope(customerId).use { // for everything logged on this thread
handle(request) // until the scope is closed
}
Lyrelog.setUser("u_123") // every following event, every thread
Lyrelog.setUser(null) // clear itイベント自身の user がスコープのものより優先され、スコープのものが setUser より優先されます。スコープはスレッドローカルです。Java では、サーブレットフィルターの中で try-with-resources を使って開いてください(後述のリクエストフィルターを参照)。コルーチンやリアクティブなコード(Ktor、WebFlux)はスレッドをまたいで動くので、そこではイベントごとに user を渡してください。メールアドレスではなく、自分のシステムの ID を使ってください。
Logback の appender
lyrelog-jvm-logback を使うと、ロガーが SLF4J や Logback を通して書き出すすべてのレコードを Lyrelog にも送れます。logback.xml(Spring Boot では logback-spring.xml)に appender を追加してください。
<configuration>
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender" />
<root level="INFO">
<appender-ref ref="LYRELOG" />
</root>
</configuration>appender は、上のようにコードで開始した動作中の Lyrelog に転送します。あるいは appender 自身に Lyrelog を開始させることもでき、その場合サービスにはコードが一切不要です。このとき、Logback が停止すると Lyrelog も閉じられます。
<appender name="LYRELOG" class="com.lyrelog.logback.LyrelogAppender">
<apiKey>${LYRELOG_KEY}</apiKey>
<platform>api</platform>
<!-- <environment>staging</environment>, <endpoint>...</endpoint> -->
</appender>Lyrelog が開始する前に記録されたレコードは無視されます。残したいログをフレームワークが出力する前に開始してください。コンソールへの出力も続けたい場合は、コンソールの appender をこの appender と並べて残しておいてください。
private static final org.slf4j.Logger log = LoggerFactory.getLogger(Invoices.class);
MDC.put("user_id", customerId); // the event's user
log.info("Order {} shipped", orderId);
log.atWarn().addKeyValue("attempt", 2).log("invoice_retry");
log.error("charge_failed", e);| SLF4J と Logback | Lyrelog |
|---|---|
ロガー名(com.example.billing.Invoices) | category。ただし appender に <category> がある場合やレコードに category キーがある場合を除きます |
TRACE、DEBUG、INFO、WARN、ERROR | trace、debug、info、warning、error |
| フォーマット済みのメッセージ | message。引数がある場合、パターンはグループ化用に attrs.msg_template に入ります |
MDC のエントリと SLF4J 2 のキーと値のペア(addKeyValue) | attrs。ただし user_id(イベントのユーザー)と category は除きます。<includeMdc>false</includeMdc> で MDC を除外できます |
| 例外 | attrs.error_type、attrs.error_message、payload.exception(フレーム、原因) |
| レコードの時刻 | イベントの時刻 |
Lyrelog 自身の最小レベルも引き続き適用されます。minimumLevel が Level.TRACE でない限り、trace のレコードは破棄されます。appender は com.lyrelog のロガーと SDK 自身のスレッドからのレコードを無視するので、ループすることはありません。Log4j 2 や java.util.logging 用の appender はありません。グラフにしたいイベントは、固定の名前で直接呼び出すほうがよいでしょう。フォーマット済みのメッセージは文章にすぎません。
Spring のリクエストフィルター
組み込みのフィルターはありません。次のフィルターは、すべてのリクエストを http 領域の http_request_served として記録します。レベルは info、4xx では warning、5xx では error です。パスではなくルートのパターンを使うので、ID によってカーディナリティが爆発することはありません。また、リクエストの処理中に記録されるすべてのものに、そのリクエストのユーザーを設定します。
import com.lyrelog.Level;
import com.lyrelog.Lyrelog;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.servlet.HandlerMapping;
@Component
public class LyrelogRequests extends OncePerRequestFilter {
private final com.lyrelog.Logger http = Lyrelog.logger("http");
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
try (Lyrelog.UserScope user = Lyrelog.userScope(currentUserId(request))) { // your own id, or null
long start = System.nanoTime();
int status = 500; // when the handler throws, Spring writes the error page later
try {
chain.doFilter(request, response);
status = response.getStatus();
} finally {
Object route = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
Level level = status >= 500 ? Level.ERROR : status >= 400 ? Level.WARNING : Level.INFO;
http.log(level, "http_request_served", Map.of(
"method", request.getMethod(),
"route", route != null ? route.toString() : "unmatched", // /orders/{id}, not the id
"status", status,
"duration_ms", (System.nanoTime() - start) / 1_000_000));
}
}
}
}Spring はハンドラーが投げた例外をスタック付きで自身のロガーに記録するので、Logback の appender を使っていれば、すでに error_type と error_message 付きで届きます。フィルターでも記録すると二重になってしまいます。
エラー
try {
charge(order)
} catch (e: PaymentException) {
Lyrelog.captureError(e, category = "billing", attrs = mapOf("order_id" to order.id))
}イベントは exception、レベルは error です。属性には error_type(クラス名)と error_message が入り、payload には説明、最大 60 フレーム、原因(最大 8 個、それぞれ 20 フレームまで)、抑制された例外が入ります。指定した属性も追加されますが、この 2 つが優先されます。level でレベルを変え、user でイベントのユーザーを設定できます。logger.captureError(e) はロガーの category を使います。
キャッチされなかった例外
デフォルトでは無効です。captureUncaught = true にすると、どのスレッドであれ、どのコードにもキャッチされなかった例外が exception として記録されます。handled: false、mechanism: uncaught_exception が付き、thread にスレッド名が入ります。その後、元から設定されていたハンドラーが実行されます(なければ JVM の通常の出力)。そのスレッドが最後のスレッドだった場合は、JVM が終了する前にシャットダウンフックがイベントを送信します。
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))フレームワークはリクエスト内の例外を自分でキャッチして記録します。それらは Logback の appender を通して届きます。ExecutorService に submit で渡したタスク内の例外は、このハンドラーではなく、その Future に渡されます。
環境とプラットフォーム
environment は環境変数 LYRELOG_ENVIRONMENT から取得し、なければ production です。platform は jvm です。どちらも設定で指定できます。
Lyrelog.start(Configuration(apiKey = key, environment = "staging", platform = "worker"))名前は自由です。英小文字、数字、-、_ を使い、32 文字までです。設定に書いたそれ以外の文字列は自動的に整えられます(Staging EU は staging-eu になります)。$LYRELOG_ENVIRONMENT が不正な場合は一度だけ報告され、production に置き換えられるので、デプロイ時のタイプミスでサービスが止まることはありません。
release(resource.app_version)のデフォルトは、JVM の起動に使った jar(java -jar orders.jar)の Implementation-Version です。appId(resource.app_id)のデフォルトはその jar の Implementation-Title、なければ jar のファイル名、それもなければメインクラスです。意図した値にならない場合は設定してください。
同意
同意は、誰かのデバイス上で動くアプリのためのものです。サーバー SDK は渡されたものをそのまま送ります。同意のオプションはありません。
フラッシュと停止
Lyrelog.flush() // send what's queued now, waiting up to 5 s; true when it finished
Lyrelog.flushInBackground() // the same, without waiting
Lyrelog.close() // send what's left (up to closeTimeoutMillis), then stopどれもほとんど必要ありません。SDK は 5 秒ごとに送信し、JVM が正常に終了するとき(main の終わり、System.exit、SIGTERM、Ctrl-C)には JVM のシャットダウンフックが SDK を閉じます。kill -9 ではフックは実行されません。フックを無効にするには shutdownHook = false を指定し、自分で close を呼んでください。
flush はサーバーが求めた Retry-After を守り、それより早く送信することはありません。close の後は、再び start を呼べます。
サーバーレス関数(AWS Lambda)では、ハンドラーが return する前に Lyrelog.flush() を呼んでください。ランタイムが次の送信より前にプロセスを凍結することがあります。
イベントの待機場所
イベントはキューディレクトリにバッチごとに 1 ファイルとして書き込まれ、サーバーが受け付けたときにだけディレクトリから取り除かれます。
- デフォルトでは、このプロセス用に
java.io.tmpdirの下に新しいディレクトリを作り、closeで削除します。それまでに送信されなかったものは、メモリ上のキューと同じように失われます。 storageDirectoryを指定すると、自分で用意したディレクトリを使います。送信されなかったもの(サーバーに到達できなかった、または待つよう求められた)はそこに残り、次のstartの後に送られます。同時に使えるのは 1 つのプロセスだけです。ディレクトリはロックされ、すでにロックされていた場合、2 つ目のプロセスは代わりに一時ディレクトリにキューを置き、その旨を一度だけ伝えます。
どちらも上限は 20 MB、7 日間で、古いものから削除されます(maxDiskBytes、maxEventAgeMillis)。
開発時とテスト
キーを指定しなければよいだけです。Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) は環境変数が設定されていなければ何も開始せず、以降の呼び出しもすべて何もしないので、テストでもキーのないノート PC でも同じコードが動きます。Lyrelog が動作していない間は、Logback の appender も何もしません。
テストで何が記録されるかを確認するには、endpoint をローカルの HTTP サーバーに向け(ループバックアドレスでは平文の http:// を使えます)、受け取ったバッチを読んでください。HTTP API のページにあるとおり、gzip された NDJSON で、1 行に 1 イベントです。
Java から使う
Lyrelog のすべての関数は Java からは static で、省略可能な引数のためのオーバーロードがあります。Configuration にはビルダーがあります。
Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY"))
.platform("api")
.environment("staging")
.captureUncaught(true)
.build());
Lyrelog.info("checkout_done");
Lyrelog.info("checkout_done", "billing", Map.of("plan", "pro"));
Lyrelog.captureError(e, "billing");
try (Lyrelog.UserScope scope = Lyrelog.userScope(customerId)) {
Lyrelog.logger("billing").warning("invoice_retry", Map.of("attempt", 2));
}new Configuration(key) も使えます。ロガーの関数にもオーバーロードがあるので、末尾の引数は省略できます。
検証済みイベント
検証済みイベント(verified event)とは、アプリや Web ページから公開のインジェストキーをコピーした第三者には送れないイベントのことです。それが何を証明し、何を証明しないかは検証済みイベントを参照してください。
サーバーキー lyr_srv_... で送信します。このキーで送られるイベントはすべて検証済み(verified_by が server)になり、1 アドレスあたりの 1 日の割り当ても消費しません。サーバーキーは、オーナーが最近のサインイン(10 分以内)の後、プロジェクトの API keys ページの Send events from a server で作成します。キーは一度しか表示されません。これはシークレットです。リポジトリには含めず、サーバーの環境変数やシークレットストアから読み込んでください。
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environment確認するにはエクスプローラーを開き、Filter で Verified by と Server key を選びます(他の値は App Attest と Not verified です)。開いたイベントでは、Context の Sender の行に Verified, server key または Not verified, public key と表示されます。
インジェストキー lyr_ing_... やフルアクセスキー lyr_adm_... で送られたイベントは、検証されずに届き、1 日の割り当ても消費します。公開キーを持っている人なら誰でも同じものを送れたはずだからです。検証済みイベントが証明するのは誰が送ったかであり、その内容が正しいことではありません。
誰が何を検証するのか、そして 1 日の割り当てについては、検証済みイベントを参照してください。
設定
| オプション | デフォルト | 意味 |
|---|---|---|
apiKey | 必須 | プロジェクトのサーバーキー(lyr_srv_...)、またはインジェストキー。null または空白の場合:何も開始しません |
endpoint | https://ingest.lyrelog.com | ベース URL。/v1/... のパスを貼り付けても取り除かれます。https のみ、http は localhost のみ |
environment | $LYRELOG_ENVIRONMENT、なければ production | 有効な任意の名前 |
platform | jvm | api、worker など |
release | 起動した jar の Implementation-Version | resource.app_version として送られます |
appId | 起動した jar の Implementation-Title かファイル名、なければメインクラス | resource.app_id として送られます:サービス名 |
minimumLevel | Level.DEBUG | これより低いレベルのイベントはキューに入る前に破棄されます |
flushIntervalMillis | 5 秒 | バックグラウンドスレッドが送信する間隔 |
maxBatchBytes | 512 KiB | バッチは先に達したほうの上限で閉じられます(4 MiB 以内に収まります) |
maxBatchEvents | 500 | 最大 2,000 |
maxQueue | 10,000 | 書き込み待ちのイベント数。これを超えると最も古いものが破棄され、件数が記録されます |
maxDiskBytes | 20 MB | キューディレクトリの上限。古いものから削除されます |
maxEventAgeMillis | 7 日 | これより古いキュー内のイベントは破棄されます |
redactedKeys | null:DEFAULT_REDACTED_KEYS | マスクするキー名。指定したリストがデフォルトを置き換え、空のリストで無効になります |
storageDirectory | プロセスごとの一時ディレクトリ | キューを置く場所。イベントの待機場所を参照 |
captureUncaught | false | キャッチされなかった例外を記録します |
shutdownHook | true | JVM のシャットダウン時に閉じます |
closeTimeoutMillis | 5 秒 | 閉じるときに最後の送信を待つ時間 |
diagnostics | 標準エラー出力 | SDK 自身のメッセージを受け取ります(Consumer<String>)。Lyrelog に送り込むロガーには向けないでください |
配信と制限
| ブロックしない | ログの記録はイベントをコピーしてすぐに返ります。1 つのバックグラウンドのライターがそれをキューディレクトリに書き込み、ネットワークを待つことはありません。送信は 1 つのバックグラウンドスレッドが行います。並行して使っても安全です。 |
| バッチ | 1 リクエストあたり最大 500 件または 512 KiB、gzip で、flushIntervalMillis ごとに送られます。エンコード後に 1 MiB を超えるイベントは破棄され、件数が記録されます。 |
| リトライ | フルジッター付きで 1 秒から倍々で最大 5 分、Retry-After を守ります。同じバイト列を再送します。それ以外の 4xx ではバッチを破棄し、3xx(リダイレクト。たどることはありません)でも破棄します。キーが拒否された場合(401、403)は、プロセスが再起動するまで送信を止め、イベントは保持します。他のバッチは通るのにサーバーが失敗し続けるバッチは後ろに回され、その後破棄されます。 |
| 月間クォータ | Free の組織が今月のイベント数を使い切ると、サーバーは 429 を返します。イベントはキューに残り、サーバーが再び受け付けるようになった時点で、20 MB と 7 日間の上限の範囲内で送信されます。SDK は診断メッセージに警告を一度出し、その後は間にバッチが受け付けられた場合にのみ再び出します。 |
| 破棄の通知 | 上限によって失われたイベントは、件数を含む 1 つの lyrelog_events_dropped 警告(領域は lyrelog)になります。 |
| SDK 自身の問題 | endpoint の誤り、404、キーの拒否、拒否された行、応答しない endpoint は、プロセスごとに一度だけ diagnostics(デフォルトは標準エラー出力)に出力されます。各行は lyrelog: で始まります。 |
| コンテキスト | os_name と os_version(JVM の os.name と os.version)、アプリ ID、リリース、環境、プラットフォーム、プロセスごとのインストール ID とセッション ID。 |
| シークレット | 名前が authorization、cookie、password、token、secret、apikey など共通のリストにあるもののいずれかと一致するか、それで終わるキーの値は、どの深さでも、何かが切り詰められる前に "[redacted]" になります。 |
| 制限 | 長い文字列は文字の境界で切り詰められ、上限を超えた属性は lyrelog_dropped_attrs に件数が記録され、64 KiB を超える payload は {"lyrelog_truncated": true, "bytes": N, "preview": "..."} として要約されます。 |
| キー | Configuration を出力してもキーは隠されます。 |
マスキングのリストは redactedKeys で変更できます。指定したリストがデフォルトを置き換え、空のリストを渡すとマスキングは無効になります。追加するには次のようにします。
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"),
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "card_number",
))