抢先体验仅限邀请,SDK 尚未发布。申请邀请
跳到正文
文档

JavaScript

从网站或 Node 服务发送结构化日志。TypeScript、ESM,零依赖。

浏览器和 Node

只有一个包 @lyrelog/js,支持浏览器和 Node 22.12 及以上版本。在哪里都用同一个 import:打包工具会选浏览器构建,Node 会选 Node 构建。这个包只提供 ESM:可以 import,也可以 require()(Node 22.12 无需任何参数就能加载 ES 模块)。

内部预览:这个包尚未发布。在发布之前,pnpm add @lyrelog/js 会失败,因为 npm 上还没有这个包。

安装

pnpm add @lyrelog/js

开始使用

Lyrelog.init 返回一个客户端。每次页面加载或每个进程创建一个,越早越好。

import { Lyrelog } from "@lyrelog/js";

export const log = Lyrelog.init({
  apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
  release: "2.0.1",
});

在浏览器中,使用项目的采集密钥 lyr_ing_...:它只能追加事件,所以放在页面里是安全的。在 Node 上,使用服务器密钥 lyr_srv_...:它发送的事件是已验证的,而且不受单个地址每日配额的限制。千万不要把服务器密钥放进浏览器代码。想让页面发出已验证事件,请通过你自己的服务器发送。

事件发往 https://ingest.lyrelog.com。只有要发到别处时才需要传 endpoint。它是基础 URL;如果粘贴了带 .../v1/events:batch 的路径,路径部分会被去掉。

用相同的 endpoint 和密钥再次调用 init 时,如果配置也相同,会返回当前正在运行的客户端;否则会关闭它并新建一个,所以热重载永远不会留下两个客户端。没有 apiKey,或者 endpoint 不是 https(只有 localhost 允许纯 http)时,客户端会在控制台警告一次,然后什么都不发送。

内容安全策略

如果你的网站设置了内容安全策略(Content Security Policy),请在 connect-src 中允许采集地址:

Content-Security-Policy: connect-src 'self' https://ingest.lyrelog.com

记录事件

每个级别一个方法:trace、debug、info、notice、warning、error、critical,或者 log(level, message, options)。

log.info("checkout_done", { category: "checkout", attrs: { items: 3, total_cents: 4200 } });
log.error("job_failed", { attrs: { job: "digest" }, payload: { response: raw } });

每次日志调用都会把事件裁剪到服务器的限制以内、序列化(之后再修改你的对象不会影响它),然后放进队列。无效的输入会被转换成有效内容,绝不会抛出异常。调用 close() 之后,日志调用不再起作用。

按分类划分的 logger

const jobs = log.logger("jobs");
jobs.info("job_done", { attrs: { job: "digest", ms: 412 } });

logger 拥有所有级别方法和 log。要在它的分类下捕获错误,使用 log.captureException(error, { category: "jobs" })。

用户

log.setUser(accountId); // attached to every following event
log.setUser(null);      // on sign-out

log.sessionId 返回当前会话,例如可以显示在客服页面上。用户 id 不会被保存:在浏览器中,每次页面加载、知道当前用户是谁之后,都要再调用一次 setUser。

页面

log.screen("Checkout");

在 navigation 分类下记录一条 screen_viewed,带上前一个页面以及在那个页面停留的秒数,之后的每个事件都会带上 screen。在 Web 上,页面切换时调用它。传页面名称,不要传 URL:/orders/1234 会让每个订单都变成一个单独的页面。

function OrderPage() {
  useEffect(() => log.screen("Order"), []);
  // ...
}

请求

SDK 不会自动记录请求。像 Swift SDK 那样,用一个固定的名称和你想做成图表的字段,记录你关心的请求:

const started = performance.now();
const res = await fetch("/api/cart");
log.log(res.ok ? "debug" : "warning", res.ok ? "http_request" : "http_request_failed", {
  category: "network",
  attrs: { method: "GET", path: "/api/cart", status: res.status, duration_ms: Math.round(performance.now() - started) },
});

异常

try {
  await pay();
} catch (error) {
  log.captureException(error, { category: "checkout", attrs: { step: "pay" } });
}

记录一条 exception(级别为 error,如果你传了 level 就用它),属性中带有 error_type 和 error_message,payload 中带有名称、消息、堆栈、code 以及最多三层 cause。抛出任何值都可以,不限于 Error。如果抛出的值不是 Error,只保留它的 name、message、code 和 status,对象的其余部分一概不留(HTTP 客户端的错误可能带着请求 header)。在浏览器中,堆栈里的 URL 会去掉查询字符串和片段。

未捕获的错误

SDK 会替你捕获它们,记为同样的 exception 事件,带有 handled: false 和 mechanism:

  • 在浏览器中:冒泡到 window 的错误(onerror),以及没有被处理的 promise 拒绝(onunhandledrejection)。控制台照样会显示它们。跨域脚本产生的不透明 "Script error." 不含任何有用信息,会被跳过。
  • 在 Node 上:未捕获的异常或拒绝。Lyrelog 只做监听(它用的是 uncaughtExceptionMonitor),所以进程照样会崩溃,和没装 SDK 时一样。进程退出前来不及发送,所以事件会写入临时目录中的一个小文件,等应用下次用同一个密钥启动时再发送。

每分钟最多捕获 10 个,同一个错误每 10 秒只记一次,所以不断抛错的循环不会把你的项目淹没;stats().skippedErrors 统计被跳过的数量。用 captureErrors: false 可以全部关闭。

被框架捕获的错误

框架自己捕获的错误永远不会成为未捕获错误:请在那里调用 captureException。在 React 中,可以在错误边界里调用:

import { Component, type ErrorInfo, type ReactNode } from "react";

class ErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
  state = { failed: false };

  static getDerivedStateFromError() {
    return { failed: true };
  }

  componentDidCatch(error: unknown, info: ErrorInfo) {
    log.captureException(error, { category: "ui", attrs: { component_stack: info.componentStack ?? "" } });
  }

  render() {
    return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
  }
}

在 Express 中,可以在错误处理中间件里调用,把它加在路由之后:

app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
  log.captureException(err, {
    category: "http",
    attrs: { method: req.method, route: req.route?.path ?? "unmatched" },
  });
  next(err);
});

环境和平台

  • Node:只有在 NODE_ENV=production 时,environment 才是 production。其他情况,包括完全没有设置 NODE_ENV,都是 development:请在你的服务器上设置 NODE_ENV=production(或 environment)。platform 为 node。
  • 浏览器:在 localhost、127.0.0.1、[::1] 或 .localhost 主机上,environment 是 development,其他情况是 production。platform 为 web。

两者都可以在 init 中设置,例如 Lyrelog.init({ apiKey, environment: "staging" })。名称不限:小写字母、数字、- 和 _,最多 32 个字符。

const log = Lyrelog.init({ apiKey, consent: "pending" });
// later
log.setConsent("granted"); // or "denied"

pending 把事件留在内存中不发送,granted 发送它们,denied 丢弃所有事件(在 Node 上还包括等待发送的未捕获错误文件)。同意状态不会在页面加载之间保存:请自己保存用户的选择,再传给 init。在浏览器中,获得同意之前,安装 id 和会话 id 只保存在内存中,不写入 localStorage 或 sessionStorage。

脱敏和过滤

无论是在属性、payload 中,还是在任何被转成字符串的内容里,只要某个值的键名转成小写并去掉 -、_、. 和空格后,等于下列之一或以其结尾,这个值就会变成 "[redacted]":authorization、cookie、password、passwd、secret、token、apikey、privatekey、credential、credentials、accesskey 或 signature。所以 X-Api-Key、csrf_token、Set-Cookie 和 user_token 会被脱敏,token_count 和 max_tokens 不会。redactKeys 用你自己的名称替换这个列表,匹配方式相同;传空列表会关闭脱敏。如果想在默认列表的基础上追加,展开包导出的 DEFAULT_REDACT_KEYS 即可。

想自己修改或丢弃事件,传入 beforeSend。它在脱敏之后、入队之前拿到每个事件,返回这个事件(改过或没改),或者返回 null 丢弃它。各个 id、ts 和 resource 不能修改;你返回的内容会再次按限制裁剪;hook 抛出异常时,这个事件会被丢弃。

import { Lyrelog, DEFAULT_REDACT_KEYS } from "@lyrelog/js";

const log = Lyrelog.init({
  apiKey: "lyr_ing_...",
  redactKeys: [...DEFAULT_REDACT_KEYS, "card_number"],
  beforeSend(event) {
    if (event.message === "health_check") return null;
    if (event.attrs?.email) event.attrs.email = "[redacted]";
    return event;
  },
});

立即发送(flush)和停止

在浏览器中,这两个你很少需要手动调用:定时器触发和页面隐藏时都会自动发送。

await log.flush(); // send what is queued now

在 Node 上,请在服务的关闭流程中关闭客户端,让队列中的事件在进程退出前发出去:

process.on("SIGTERM", async () => {
  await log.close(); // sends what is queued, then stops
  process.exit(0);
});

以 process.exit() 结束的脚本会跳过 beforeExit,队列中还没发出的事件就丢了:请先 await log.close(),如上所示。

在 serverless 函数中(AWS Lambda、Vercel 和 Netlify 的函数、Cloudflare Workers),运行时一旦函数返回响应就会冻结或结束它,定时器根本来不及触发。请在返回之前立即发送(flush):

export async function handler(event) {
  log.info("order_created", { attrs: { order_id: event.id } });
  await log.flush();
  return { statusCode: 200 };
}

flush、close 和页面隐藏时的发送都会遵守服务器要求的 Retry-After:在这段时间内,flush 会立即返回,事件继续等待。

log.stats() 返回 { queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled };收到 401 或 403 之后,或者客户端没有可用的密钥或 endpoint 时,disabled 为 true。

开发和测试

把 apiKey 留空,客户端会警告一次,然后什么都不发送;或者传入 consent: "denied",不发出警告,直接丢弃所有事件:

const log = Lyrelog.init({
  apiKey: process.env.LYRELOG_KEY ?? "",
  consent: process.env.NODE_ENV === "test" ? "denied" : "granted",
});

已验证事件

已验证事件是指不可能由从应用或网页中复制了公开采集密钥的人发出的事件。它能证明什么、不能证明什么,请看已验证事件。

在 Node 上,用服务器密钥 lyr_srv_... 发送。它发出的每个事件都是已验证的(verified_by 为 server),并且不计入单个地址的每日配额。服务器密钥由所有者在项目的 API keys 页面,通过 Send events from a server 创建,需要近期登录过(10 分钟以内),而且只显示一次。它是机密:不要放进代码仓库,从服务器的环境变量或机密存储中读取。

export const log = Lyrelog.init({
  apiKey: process.env.LYRELOG_KEY!, // lyr_srv_..., set in the server's environment
});

在浏览器中,密钥是公开的采集密钥,所以页面的事件到达时是未验证的,并且计入每日配额。千万不要把服务器密钥放进浏览器代码:页面里的任何内容都能被读取。要验证网站的事件,请通过你自己的服务器中转:把 endpoint 指向你后端的一个路由,由它用服务器密钥转发每一批事件。这个路由必须只接受来自你自己已登录会话的事件,否则它什么也验证不了。

要检查,打开 explorer:在 Filter 中选择 Verified by 和 Server key(另外两个值是 App Attest 和 Not verified)。打开一个事件,在 Context 下的 Sender 一行会显示:Verified, server key 或 Not verified, public key。

用采集密钥或完全访问密钥 lyr_adm_... 发送的事件到达时是未验证的:任何持有公开密钥的人都可能发出同样的事件。已验证事件证明的是谁发送了它,而不是它的内容属实。

谁验证什么,以及每日配额,请看已验证事件。

配置

选项默认值说明
endpointhttps://ingest.lyrelog.com基础 URL;粘贴的 /v1/... 路径会被去掉。只允许 https,http 仅限 localhost
apiKey必填浏览器:项目的采集密钥,放在客户端代码中是安全的。Node:服务器密钥,绝不放进客户端代码。没有它,客户端什么都不发送
environment自动检测名称不限:小写字母、数字、- 和 _,最多 32 个字符
platformweb / nodeapi、worker……
releaseNode:npm_package_version作为 app_version 发送。只有通过 package script 启动时才有这个默认值:用 node server.js、Docker 或 systemd 启动时,请自己传入
appIdWeb:主机名。Node:npm_package_name作为 app_id 发送。在 Node 上,注意事项同 release
minimumLeveldebug低于这个级别的事件在入队前就被丢弃
flushIntervalMs5000队列多久发送一次
maxQueue10000在内存中等待的事件数;超出后丢弃最旧的
maxQueueBytes16 MiB同一个上限,按字节计
redactKeysDEFAULT_REDACT_KEYS要脱敏的键名;会替换默认列表,[] 关闭脱敏
beforeSend无修改事件,或返回 null 丢弃它
consentgrantedgranted、pending 或 denied
captureErrorstrue捕获未捕获的错误和未处理的 promise 拒绝

发送和限制

何时发送每 5 秒一次;积压到 500 个事件时立即发送;调用 flush() 和 close() 时。在浏览器中,页面隐藏时也会发送;在 Node 上,beforeExit 时也会发送(process.exit() 时不会;定时器永远不会让进程保持运行)。
批次最多 500 个事件或 512 KiB,NDJSON 格式,gzip 压缩(浏览器用 CompressionStream,Node 用 zlib)。超过 1 MiB 的事件会被丢弃并计数。
重试采用带完全抖动(full jitter)的退避(从 1 秒开始翻倍,最长 5 分钟),遵守 Retry-After。重试时用相同的 id 重新发送相同的事件。其他任何 4xx 都会丢弃该批次;3xx 会丢弃该批次并发出警告(不跟随重定向);密钥被拒绝时停止发送直到重启,事件保留。
每月配额Free 组织用完当月事件配额后,服务器返回 429。事件留在队列中,等服务器重新接收时再发出,最多保留 maxQueue 个。客户端会用一次 console.warn 输出服务器的消息,之后只有在中间有批次被接收过,才会再次输出。
自身的问题endpoint 错误、遇到重定向或丢弃了批次:输出一条以 [lyrelog] 开头的 console.warn。密钥被拒绝和行被拒收:输出 console.debug,所以要在浏览器控制台打开详细(verbose)消息才能看到。
上下文Web:os_name: "web",浏览器类型作为 device_model,navigator.language 作为 locale,安装 id 存在 localStorage 中,会话 id 存在 sessionStorage 中(空闲 30 分钟后换新)。Node:process.platform、os.release()、CPU 架构,id 按进程生成。存储抛出异常时(隐私模式)改用内存。
限制入队前裁剪;多出的属性计入 lyrelog_dropped_attrs,属性名中的点变成 _,超过 64 KiB 的 payload 会变成带预览的摘要。

值得注意:

  • 队列在内存中。 标签页彻底关闭、进程被 SIGKILL 杀掉或以 process.exit() 结束时,还在等待的事件会丢失。请在服务器的关闭流程中调用 close(),在 serverless 处理函数末尾调用 flush()。
  • 页面隐藏时最多发送约 60 KB,其余的等页面重新显示时再发。
  • 在 Web 上,采集密钥是公开的。 任何读过你页面的人都能向这个项目发送事件,所以不要把收到的事件当作可信输入。这些事件不是已验证的;Node 上用服务器密钥发出的事件才是。