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:它使用你的应用已有的 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);
}使用服务器密钥 lyr_srv_...,在项目的 API keys 页面(Send events from a server)创建。它是机密:放在服务器的环境变量中,绝不能放进应用或网页。它发送的事件是已验证的,而且不受单个地址每日配额的限制。采集密钥 lyr_ing_... 也能用,但它发送的事件不是已验证的。
start 成功启动 Lyrelog 时返回 true。在运行期间再次调用会被忽略,并返回 false。密钥为 null 或空白时不会启动任何东西,返回 false,之后的所有调用都不起作用,所以开发或测试时少了某个环境变量也不会让服务停下来。在 start 之前记录的事件会被忽略。start 从不抛出异常。
事件发往 https://ingest.lyrelog.com。只有要发到别处时才需要传 endpoint。它是基础 URL(粘贴的 .../v1/events:batch 路径会被去掉),必须是 https://;localhost、127.0.0.1 或 ::1 可以用 http://。其他任何 endpoint 都会被拒绝:什么都不发送,SDK 会在它的诊断输出中提示一次。
记录事件
每个级别一个函数: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 层的嵌套 map。payload 可以是任意 map、列表或值。日志调用从不阻塞,也从不抛出异常:它复制事件后立即返回。调用 close 之后,日志调用不再起作用。
按分类划分的 logger
val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))logger 创建和持有的开销都很小(可以放在字段或 companion object 中)。它在被调用时把日志写进当时正在运行的实例,所以可以在 start 之前创建。
用户
服务器同时处理很多用户的请求。请在事件上设置用户,或者为一个请求的处理过程设置:
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 优先于 scope 的,scope 的又优先于 setUser 的。scope 是线程局部的:在 Java 中,在 servlet filter 里用 try-with-resources 打开它(参见下面的请求 filter)。协程和响应式代码(Ktor、WebFlux)会在线程之间切换,所以在这些场景中请改为在每个事件上传 user。请使用你自己的 id,不要用电子邮件地址。
Logback appender
有了 lyrelog-jvm-logback,你的 logger 通过 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,也就是像上面那样在代码中启动的实例。也可以让它自己启动 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 |
|---|---|
logger 名称(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(栈帧、cause) |
| 记录的时间 | 事件的时间 |
Lyrelog 自己的最低级别仍然有效:除非 minimumLevel 是 Level.TRACE,否则 trace 记录会被丢弃。appender 会忽略来自 com.lyrelog logger 和 SDK 自身线程的记录,所以永远不会形成循环。没有针对 Log4j 2 或 java.util.logging 的 appender。对于想做成图表的事件,优先直接调用并使用固定的名称:格式化后的消息只是一段文字。
Spring 请求 filter
SDK 没有内置 filter。下面这个 filter 把每个请求记录为 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));
}
}
}
}handler 抛出的异常,Spring 会连同堆栈记录到它自己的 logger 上,所以有了 Logback appender,它到达时已经带有 error_type 和 error_message;如果在 filter 中再捕获一次,就会记录两遍。
错误
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 个栈帧、cause(最多 8 个,每个 20 个栈帧)以及被抑制的异常(suppressed)。你传入的属性会被加上,但与这两个重名时以这两个为准。level 修改级别,user 设置事件的用户。logger.captureError(e) 使用该 logger 的分类。
未捕获的异常
默认关闭。设置 captureUncaught = true 后,任何线程上没有被代码捕获的异常,都会记录为 exception,带有 handled: false、mechanism: uncaught_exception,并在 thread 中记下线程名。随后会运行原先的处理程序(或 JVM 通常的打印输出)。如果那个线程是最后一个线程,shutdown hook 会在 JVM 退出前发送这个事件。
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))框架会自己捕获并记录请求中的异常:这些异常通过 Logback appender 到达。用 submit 提交给 ExecutorService 的任务中的异常,会进入它的 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)默认取它的 Implementation-Title,没有则取 jar 的文件名,再没有则取主类。如果这些不是你想要的,请自己设置。
用户同意
用户同意针对的是运行在用户设备上的应用。服务器 SDK 收到什么就发送什么,没有同意选项。
立即发送(flush)和停止
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),shutdown hook 会关闭它。kill -9 会跳过这个 hook。用 shutdownHook = false 关闭 hook,然后自己调用 close。
flush 会遵守服务器要求的 Retry-After:不会提前发送。调用 close 之后,可以再次调用 start。
在 serverless 函数(AWS Lambda)中,请在 handler 返回前调用 Lyrelog.flush():运行时可能在下一次发送之前就冻结进程。
事件在哪里等待
事件会写入一个队列目录,每个批次一个文件;只有服务器接收了某个批次,它才会离开这个目录。
- 默认情况下,是在
java.io.tmpdir下为当前进程新建的目录,在close时删除。届时还没发出的事件会丢失,和内存队列一样。 - 设置了
storageDirectory时,使用你自己的目录:没发出的事件(服务器无法连接,或要求等待)会留在那里,在下次start之后发出。同一时间只能有一个进程使用:目录会被加锁,第二个进程发现目录已被锁定时,会改用一个临时目录排队,并提示一次。
两种情况的上限都是 20 MB 和 7 天,先丢弃最旧的(maxDiskBytes、maxEventAgeMillis)。
开发和测试
不提供密钥即可:变量没有设置时,Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) 什么都不启动,之后的每个调用都不起作用,所以测试和没有密钥的笔记本电脑运行的是同一份代码。Lyrelog 没有运行时,Logback appender 也什么都不做。
想看测试记录了什么,把 endpoint 指向一个本地 HTTP 服务器(回环地址允许使用纯 http://),读取它收到的批次:gzip 压缩的 NDJSON,每行一个事件,和 HTTP API 页面上描述的一样。
从 Java 调用
在 Java 中,Lyrelog 上的每个函数都是静态的,并为可选参数提供了重载;Configuration 有一个 builder:
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) 也可以用;logger 的函数也有重载,所以末尾的参数可以省略。
已验证事件
已验证事件是指不可能由从应用或网页中复制了公开采集密钥的人发出的事件。它能证明什么、不能证明什么,请看已验证事件。
用服务器密钥 lyr_srv_... 发送。它发出的每个事件都是已验证的(verified_by 为 server),并且不计入单个地址的每日配额。服务器密钥由所有者在项目的 API keys 页面,通过 Send events from a server 创建,需要近期登录过(10 分钟以内),而且只显示一次。它是机密:不要放进代码仓库,从服务器的环境变量或机密存储中读取。
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environment要检查,打开 explorer:在 Filter 中选择 Verified by 和 Server key(另外两个值是 App Attest 和 Not verified)。打开一个事件,在 Context 下的 Sender 一行会显示:Verified, server key 或 Not verified, public key。
用采集密钥 lyr_ing_... 或完全访问密钥 lyr_adm_... 发送的事件到达时是未验证的:任何持有公开密钥的人都可能发出同样的事件,而且这些事件计入每日配额。已验证事件证明的是谁发送了它,而不是它的内容属实。
谁验证什么,以及每日配额,请看已验证事件。
配置
| 选项 | 默认值 | 说明 |
|---|---|---|
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 的 logger |
发送和限制
| 从不阻塞 | 记录日志时复制事件后立即返回;一个后台写入线程把事件放进队列目录,从不等待网络。由一个后台线程负责发送。可以安全地并发使用。 |
| 批次 | 每个请求最多 500 个事件或 512 KiB,gzip 压缩,每隔 flushIntervalMillis 发送一次。编码后超过 1 MiB 的事件会被丢弃并计数。 |
| 重试 | 从 1 秒开始翻倍,最长 5 分钟,带完全抖动(full jitter),遵守 Retry-After;重发的是相同的字节。其他任何 4xx 都会丢弃该批次,3xx(重定向,从不跟随)也会丢弃该批次;密钥被拒绝(401、403)时停止发送,直到进程重启,事件保留。如果其他批次都能发出,而某个批次服务器一直处理失败,这个批次会被移到队尾,最终被丢弃。 |
| 每月配额 | Free 组织用完当月事件配额后,服务器返回 429。事件留在队列中,等服务器重新接收时再发出,受 20 MB 和 7 天的上限约束。SDK 会在诊断输出中打印一次警告,之后只有在中间有批次被接收过,才会再次打印。 |
| 丢弃会被记录 | 因上限而丢失的事件会汇总成一条带数量的 lyrelog_events_dropped 警告(分类为 lyrelog)。 |
| 自身的问题 | 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",
))