@fenapp/lggy-sdk

Client library for Lggy — send structured logs, errors, and RUM metrics to your Lggy HTTPS ingest endpoint using an API key.

Deploy your own backend and get credentials

Lggy is self-hosted on Firebase. Do not sign up on a shared hosted URL — spin up your own project from the Lggy monorepo (or your fork):

1. Create a Firebase project with Authentication (Email/Password) and Firestore.

2. Deploy this repo to that project (firebase deploy — see the root README).

3. Open your dashboard at https://<PROJECT_ID>.web.app (or http://localhost:3000 for local dev).

4. Sign up, create an organization and a project, then copy from project settings:

   • Organization ID
   • Project ID
   • API key (shown once when the project is created)

5. Set ingestUrl to your deployment’s ingest endpoint, typically:

   https://<PROJECT_ID>.web.app/ingest

   Or the direct function URL: https://us-central1-<PROJECT_ID>.cloudfunctions.net/ingest

Install

npm install @fenapp/lggy-sdk

Usage (Node, bundlers, React, Next.js)

import { init, log, captureException, flush } from "@fenapp/lggy-sdk";

init({
  organizationId: "<org id from your dashboard>",
  projectId: "<project id>",
  apiKey: process.env.LGGY_API_KEY!,
  ingestUrl: "https://<PROJECT_ID>.web.app/ingest",
});

log("info", "User completed checkout", {
  tags: ["checkout"],
  segments: { env: "production" },
});

captureException(new Error("Payment provider timeout"));

// Optional: send queued events immediately (e.g. before page unload in the browser)
await flush();

init options

| Field | Required | Description | |-------|----------|-------------| | organizationId | yes | Organization ID from your dashboard | | projectId | yes | Project ID from your dashboard | | apiKey | yes | Project API key | | ingestUrl | yes | Full URL of the ingest HTTP endpoint (POST JSON) on your Firebase deploy | | defaultSegments | no | Key/value pairs merged into every event | | defaultTags | no | Tags merged into every event | | maxQueue | no | Max events to buffer before forcing a send (default 25) | | autoCaptureLevels | no | Browser-only: which levels to forward from automatic capture (console, failed fetches, resource errors). Default ["error"]. Use e.g. ["debug","info","warn","error"] for full console forwarding. Use [] to disable that automatic capture. | | captureUnhandled | no | Browser-only: report uncaught exceptions and unhandled promise rejections (default true). Set false to disable. | | releaseStage | no | e.g. "production" — used with enabledReleaseStages | | enabledReleaseStages | no | Only send when releaseStage is in this list | | sampleRate | no | Metrics/spans sample rate 0–1 (default 0.15). Errors always sent. | | appVersion | no | Build id merged into segments as build_id |

RUM / performance (opt-in)

import { init, Lggy, collectBrowserContext } from "@fenapp/lggy-sdk";

init({
  /* ...credentials... */
  releaseStage: "production",
  enabledReleaseStages: ["production"],
  sampleRate: 0.15,
  appVersion: "abc123",
  defaultSegments: collectBrowserContext(),
});

Lggy.performance.start(); // web vitals, long tasks (max 5), route changes
Lggy.performance.markHydrationComplete();

See docs/sdk.md for full API reference.

Log levels

"debug" | "info" | "warn" | "error"

LogContext (optional on log / captureException)

• tags — string tags (merged with defaultTags)
• segments — string key/value segments (merged with defaultSegments)
• route — override route string (otherwise the browser may use location.pathname)
• extra — arbitrary JSON-serializable metadata

Advanced: batching

sendEvents(events) is available for low-level batch posts; most apps use init + log / captureException + the internal queue.

Browser bundle (global Lggy)

The package exposes a minified IIFE at @fenapp/lggy-sdk/browser (file dist/browser.global.js). It defines a global Lggy with init, log, captureException, flush, and sendEvents.

<script src="/path/to/browser.global.js"></script>
<script>
  Lggy.init({
    organizationId: "…",
    projectId: "…",
    apiKey: "…",
    ingestUrl: "https://<PROJECT_ID>.web.app/ingest",
  });
  Lggy.captureException(new Error("demo"));
</script>

Privacy note

Widening autoCaptureLevels beyond error increases console and network noise and may capture sensitive data. Prefer ["error"] in production unless you need broader forwarding.

Source

This package is published from packages/sdk in the Lggy monorepo.