アーリーアクセス招待制です。SDK はまだ公開されていません。招待をリクエスト
本文へスキップ
ドキュメント

JavaScript

Web サイトや Node サービスから構造化ログを送ります。TypeScript、ESM、依存関係なし。

ブラウザと Node

ブラウザと Node 22.12 以降に対応した 1 つのパッケージ、@lyrelog/js です。どこでも同じ import で動きます。バンドラーはブラウザ用ビルドを、Node は Node 用ビルドを選びます。パッケージは ESM のみです。import するか、require() してください(Node 22.12 はフラグなしで ES モジュールを読み込めます)。

社内プレビュー:このパッケージはまだ公開されていません。公開されるまでは pnpm add @lyrelog/js は失敗します。npm にパッケージがないためです。

インストール

pnpm add @lyrelog/js

はじめる

Lyrelog.init はクライアントを返します。ページの読み込みごと、またはプロセスごとに 1 つ、できるだけ早く作成してください。

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_... を使います。そのイベントは検証済みになり、1 アドレスあたりの 1 日の割り当て(月間イベント数の一部)も適用されません。サーバーキーは決してブラウザのコードに含めないでください。ページから検証済みイベントを送るには、自分のサーバーを経由して送信します。

イベントは https://ingest.lyrelog.com に送られます。別の送信先に送る場合にのみ endpoint を指定してください。指定するのはベース URL です。.../v1/events:batch のパスを貼り付けても取り除かれます。

同じ endpoint とキーで init をもう一度呼ぶと、設定が同じなら動作中のクライアントがそのまま返り、異なる場合はそれを閉じて新しいクライアントを開始します。そのため、ホットリロードでクライアントが 2 つ残ることはありません。apiKey がない場合や、endpoint が https でない場合(平文の http は localhost のみ可)、クライアントはコンソールで一度だけ警告し、何も送信しません。

Content Security Policy

サイトで Content Security Policy を設定している場合は、connect-src でインジェストを許可してください。

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

イベントを記録する

レベルごとに 1 つのメソッドがあります: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() の後は、ログの呼び出しは何もしません。

領域ごとのロガー

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

ロガーはすべてのレベルのメソッドと 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"), []);
  // ...
}

リクエスト

リクエストの自動記録はありません。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、最大 3 つの cause が入ります。Error に限らず、throw されたものなら何でも扱えます。Error 以外の値が throw された場合は、その name、message、code、status だけを残し、オブジェクトの他の部分は残しません(HTTP クライアントのエラーにはリクエストの header が含まれていることがあるためです)。ブラウザでは、スタック内の URL からクエリ文字列とフラグメントが取り除かれます。

キャッチされなかったエラー

これらは自動的に記録されます。同じ exception イベントとして、handled: false と mechanism が付きます。

  • ブラウザでは、window まで到達したエラー(onerror)と、ハンドラーのないまま reject された Promise(onunhandledrejection)です。コンソールにも引き続き表示されます。クロスオリジンの不透明な「Script error.」は有用な情報を持たないため、スキップされます。
  • Node では、キャッチされなかった例外や reject です。Lyrelog は監視するだけなので(uncaughtExceptionMonitor を使います)、プロセスは Lyrelog がない場合と同じようにクラッシュします。終了する前に送信する時間はないため、イベントは一時フォルダーの小さなファイルに書き込まれ、次に同じキーでアプリが起動したときに送信されます。

記録されるのは 1 分あたり最大 10 件、同じエラーは 10 秒に 1 回までなので、例外を投げ続けるループがあってもプロジェクトにエラーが大量に流れ込むことはありません。スキップされた件数は 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: environment が production になるのは NODE_ENV=production のときだけです。それ以外は、NODE_ENV がまったくない場合も含めて development になります。サーバーでは NODE_ENV=production(または environment)を設定してください。platform は node です。
  • ブラウザ: environment は localhost、127.0.0.1、[::1]、または .localhost のホストでは 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、文字列に変換されたものの中で、キー名を小文字にして -、_、.、空白を除いたものが authorization、cookie、password、passwd、secret、token、apikey、privatekey、credential、credentials、accesskey、signature のいずれかと一致するか、それで終わる場合、その値は "[redacted]" になります。つまり X-Api-Key、csrf_token、Set-Cookie、user_token はマスクされますが、token_count と max_tokens はマスクされません。redactKeys はこのリストを独自の名前に置き換えます(照合方法は同じです)。空のリストを渡すとマスキングは無効になります。デフォルトに追加するには、パッケージがエクスポートしている DEFAULT_REDACT_KEYS を展開して使います。

イベントを自分で変更または破棄するには、beforeSend を渡します。マスキングの後、キューに入る前に各イベントを受け取り、変更したかどうかにかかわらずそのイベントを返すか、破棄する場合は null を返します。ID、ts、resource は変更できません。返したイベントは再び制限に収まるよう整えられ、フックが例外を投げた場合はそのイベントは破棄されます。

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;
  },
});

フラッシュと停止

ブラウザではどちらもほとんど必要ありません。タイマーとページが非表示になったときに送信されるためです。

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() を呼んでください。

サーバーレス関数(AWS Lambda、Vercel と Netlify の関数、Cloudflare Workers)では、ランタイムは関数が応答した時点で、タイマーが発火する前に関数を凍結または終了します。return する前にフラッシュしてください。

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 } を返します。disabled は、401 または 403 の後、あるいはクライアントに送信用のキーや endpoint がない場合に true になります。

開発時とテスト

apiKey を空にすると、クライアントは一度だけ警告して何も送信しません。警告なしですべてのイベントを破棄するには consent: "denied" を渡します。

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

検証済みイベント

検証済みイベント(verified event)とは、アプリや Web ページから公開のインジェストキーをコピーした第三者には送れないイベントのことです。それが何を証明し、何を証明しないかは検証済みイベントを参照してください。

Node では、サーバーキー lyr_srv_... で送信します。このキーで送られるイベントはすべて検証済み(verified_by が server)になり、1 アドレスあたりの 1 日の割り当ても消費しません。サーバーキーは、オーナーが最近のサインイン(10 分以内)の後、プロジェクトの API keys ページの Send events from a server で作成します。キーは一度しか表示されません。これはシークレットです。リポジトリには含めず、サーバーの環境変数やシークレットストアから読み込んでください。

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

ブラウザで使うキーは公開のインジェストキーなので、ページからのイベントは検証されずに届き、1 日の割り当ても消費します。サーバーキーは決してブラウザのコードに含めないでください。ページ内のものは何でも読み取れてしまいます。サイトのイベントを検証済みにするには、自分のサーバーを経由して中継します。endpoint をバックエンドのルートに向け、そこで各バッチをサーバーキーで転送します。このルートは自分のサイトでサインインしたセッションからのイベントだけを受け付けるようにしてください。そうしなければ、検証の意味がありません。

確認するにはエクスプローラーを開き、Filter で Verified by と Server key を選びます(他の値は App Attest と Not verified です)。開いたイベントでは、Context の Sender の行に Verified, server key または Not verified, public key と表示されます。

インジェストキーやフルアクセスキー lyr_adm_... で送られたイベントは、検証されずに届きます。公開キーを持っている人なら誰でも同じものを送れたはずだからです。検証済みイベントが証明するのは誰が送ったかであり、その内容が正しいことではありません。

誰が何を検証するのか、そして 1 日の割り当てについては、検証済みイベントを参照してください。

設定

オプションデフォルト意味
endpointhttps://ingest.lyrelog.comベース URL。/v1/... のパスを貼り付けても取り除かれます。https のみ、http は localhost のみ
apiKey必須ブラウザ:プロジェクトのインジェストキー。クライアントのコードに含めても安全です。Node:サーバーキー。クライアントのコードには決して含めません。指定しないとクライアントは何も送信しません
environment自動検出任意の名前:英小文字、数字、-、_、32 文字まで
platformweb / nodeapi、worker など
releaseNode:npm_package_versionapp_version として送られます。デフォルト値があるのはパッケージのスクリプト経由で起動した場合のみです。node server.js、Docker、systemd で起動する場合は自分で指定してください
appIdWeb:ホスト名。Node:npm_package_nameapp_id として送られます。Node では release と同じ注意点があります
minimumLeveldebugこれより低いレベルのイベントはキューに入る前に破棄されます
flushIntervalMs5000キューを送信する間隔
maxQueue10000メモリ内で待機するイベント数。これを超えると古いものから削除されます
maxQueueBytes16 MiB同じ上限をバイト数で指定
redactKeysDEFAULT_REDACT_KEYSマスクするキー名。デフォルトを置き換えます。[] で無効になります
beforeSendなしイベントを変更するか、null を返して破棄します
consentgrantedgranted、pending、denied
captureErrorstrueキャッチされなかったエラーと未処理の Promise の reject を記録します

配信と制限

送信のタイミング5 秒ごと、500 件のイベントがたまった時点、flush() と close() の呼び出し時。ブラウザではページが非表示になったときにも、Node では beforeExit のときにも送信します(process.exit() では送信しません。タイマーがプロセスを生かし続けることはありません)。
バッチ最大 500 件または 512 KiB、NDJSON、gzip(ブラウザでは CompressionStream、Node では zlib)。1 MiB を超えるイベントは破棄され、件数が記録されます。
リトライフルジッター付きのバックオフ(1 秒から倍々で最大 5 分)で、Retry-After を守ります。リトライでは同じイベントを同じ ID で再送します。それ以外の 4xx ではバッチを破棄します。3xx では警告とともに破棄します(リダイレクトはたどりません)。キーが拒否された場合は、再起動するまで送信を止め、イベントは保持します。
月間クォータFree の組織が今月のイベント数を使い切ると、サーバーは 429 を返します。イベントはキューに残り、サーバーが再び受け付けるようになった時点で、maxQueue まで送信されます。クライアントはサーバーのメッセージとともに console.warn を一度出し、その後は間にバッチが受け付けられた場合にのみ再び出します。
SDK 自身の問題endpoint の誤り、リダイレクト、バッチの破棄:[lyrelog] で始まる console.warn を一度出します。キーの拒否と拒否された行:console.debug に出すので、確認するにはブラウザのコンソールで詳細メッセージを表示してください。
コンテキストWeb:os_name: "web"、device_model としてブラウザの種類、locale として navigator.language、localStorage にインストール ID、sessionStorage にセッション ID(30 分操作がないと新しくなります)。Node:process.platform、os.release()、CPU アーキテクチャ、プロセスごとの ID。ストレージが例外を投げる場合(プライベートモード)はメモリにフォールバックします。
制限キューに入る前に整えられます。上限を超えた属性は lyrelog_dropped_attrs に件数が記録され、属性名のドットは _ になり、64 KiB を超える payload はプレビュー付きの要約になります。

知っておきたいこと:

  • キューはメモリ上にあります。 タブが完全に閉じられたとき、またはプロセスが SIGKILL で強制終了されたり process.exit() で終了したりしたときに、まだ待機中だったイベントは失われます。サーバーの終了処理では close() を、サーバーレスのハンドラーの最後では flush() を呼んでください。
  • 非表示になるページが送信できるのは最大でおよそ 60 KB です。 残りはページが再び表示されるまで待機します。
  • Web ではインジェストキーは公開されています。 ページを読める人なら誰でもそのプロジェクトにイベントを送れるので、届いたイベントを信頼できる入力として扱わないでください。それらのイベントは検証済みではありません。サーバーキーを使った Node からのイベントは検証済みです。