Logger SDK

Use the npm package, a copied file, or raw HTTP — works anywhere fetch is available.

Installation options

Option A — npm package (recommended)

Install

npm install @marvink02/loggerman-sdk

Import from @marvink02/loggerman-sdk in any project with a package manager. Subpath exports:

@marvink02/loggerman-sdk — main client
@marvink02/loggerman-sdk/edge — small bundle for Workers / Vercel Edge
@marvink02/loggerman-sdk/next — App Router middleware helper
@marvink02/loggerman-sdk/standalone — copy-paste source generator

Option B — copy a single file

From the dashboard Settings → Integration, paste loggerman.ts into your repo. No install step; identical API. Best for scripts, restricted environments, or non-Node runtimes where you only want one file.

Both options call the same REST endpoint. Choose npm for maintainability; choose copy when you cannot add dependencies.

createLogger

createLogger posts to /api/projects/:projectId/logs with your Bearer token. Configuration fields:

Field	Required	Description
`projectId`	Yes	Project ID from Settings → API
`token`	Yes	Project API Bearer token
`baseUrl`	Yes	Public origin of your LoggerMan deployment (no trailing slash)
`source`	No	Default source label on every log
`environment`	No	Tag logs with staging / production (stored in metadata)
`retry`	No	Queue failed ingest with backoff (default `true`)
`maxRetryAttempts`	No	Cap retry attempts when `retry` is enabled
`breadcrumbs`	No	Attach recent breadcrumbs to `ERROR` logs (default `true`)
`maxBreadcrumbs`	No	Ring buffer size for breadcrumbs
`devMode`	No	`true` skips network; `"console"` logs locally and still sends

Create a logger instance

import { createLogger } from "@marvink02/loggerman-sdk";

export const logger = createLogger({
  projectId: process.env.LOGGERMAN_PROJECT_ID!,
  token: process.env.LOGGERMAN_TOKEN!,
  baseUrl: process.env.LOGGERMAN_BASE_URL!,
  source: "billing-service",
  environment: process.env.NODE_ENV,
  retry: true,
  breadcrumbs: true,
});

Logging methods

info, warning, error, log, breadcrumbs

// Convenience methods (set type + default criticality)
await logger.info("Payment captured", { invoiceId: "inv_9" });
await logger.warning("Rate limit approaching", { remaining: 12 });
await logger.error("Webhook signature invalid", { provider: "stripe" });

// Ecosystem level aliases (maps to INFO / WARNING / ERROR)
await logger.log({ message: "Verbose trace", level: "debug" });

// Breadcrumbs attach to the next ERROR automatically
logger.breadcrumb?.("User opened checkout", { cartId: "c_1" });

// Full control
await logger.log({
  message: "Custom event",
  type: "WARNING",
  criticality: "HIGH",
  source: "cron",
  metadata: { jobId: "sync-42" },
});

Use level on log() to map debug/info/warn/error from other ecosystems into LoggerMan types.

Failed requests throw an Error with the HTTP status and response body when available. With retry: true, transient failures (rate limits, offline) are queued and retried automatically.

Batch from the SDK

await logger.sendBatch?.([
  { message: "Job started", level: "info", source: "worker" },
  { message: "Job finished", level: "info", metadata: { ms: 120 } },
]);

Next.js middleware

Log unhandled middleware errors and slow paths without wrapping every route. Keep LOGGERMAN_TOKEN server-side only.

middleware.ts

// middleware.ts
import { NextResponse, type NextRequest } from "next/server";
import { createLoggerManMiddleware } from "@marvink02/loggerman-sdk/next";

const withLogging = createLoggerManMiddleware({
  projectId: process.env.LOGGERMAN_PROJECT_ID!,
  token: process.env.LOGGERMAN_TOKEN!,
  baseUrl: process.env.LOGGERMAN_BASE_URL!,
  source: "next-middleware",
  environment: process.env.VERCEL_ENV ?? "development",
});

export async function middleware(req: NextRequest) {
  return withLogging(req, async () => NextResponse.next());
}

Edge runtimes

Use the /edge export on Cloudflare Workers, Vercel Edge, or any environment where bundle size matters.

Worker example

import { createEdgeLogger } from "@marvink02/loggerman-sdk/edge";

export default {
  async fetch(request: Request, env: Env) {
    const logger = createEdgeLogger({
      projectId: env.LOGGERMAN_PROJECT_ID,
      token: env.LOGGERMAN_TOKEN,
      baseUrl: env.LOGGERMAN_BASE_URL,
      source: "worker",
    });
    await logger.info("Request", { path: new URL(request.url).pathname });
    return new Response("ok");
  },
};

Node loggers (Winston / Pino)

Optional transports forward existing log lines without rewriting call sites. Configure them from Settings → Integration in the dashboard.

@marvink02/loggerman-winston — Winston transport
@marvink02/loggerman-pino — Pino transport

These packages ship separately from the core SDK. Install only if you already use Winston or Pino.

CLI and CI

The loggerman CLI supports send, tail, and projects list for terminals and pipelines. A composite GitHub Action under integrations/github-action can post deployment or CI failure events — see Integration settings for env vars.

Tutorial: Next.js API route

Keep secrets on the server. Never expose LOGGERMAN_TOKEN in client bundles.

Server-side logging

// lib/loggerman-server.ts — server-only singleton
import { createLogger } from "@marvink02/loggerman-sdk";

export const logger = createLogger({
  projectId: process.env.LOGGERMAN_PROJECT_ID!,
  token: process.env.LOGGERMAN_TOKEN!,
  baseUrl: process.env.LOGGERMAN_BASE_URL!,
  source: "next-server",
});

// app/api/checkout/route.ts
import { logger } from "@/lib/loggerman-server";

export async function POST(req: Request) {
  try {
    // ...
    await logger.info("Checkout completed");
    return Response.json({ ok: true });
  } catch (err) {
    await logger.error("Checkout failed", {
      error: err instanceof Error ? err.message : "unknown",
    });
    throw err;
  }
}

Tutorial: Background worker

Long-running workers should reuse one logger instance per process and set source to the worker name. Use sendBatch or the batch HTTP endpoint for high throughput.

On process shutdown, await pending logger.error calls so fatal exits still flush to LoggerMan.

Webhooks and forwarding

In Settings → Integration you can configure:

Incoming webhooks — per-project HTTP URLs that accept JSON and map fields into log entries (Zapier, Make, custom scripts).
Outgoing webhooks — push new logs to your systems in real time (default, datadog, or grafana payload shapes).
OTLP ingest — POST OpenTelemetry log exports to map severity into LoggerMan types.

HTTP details for batch ingest, OTLP, and hook URLs are in the API reference.

Standalone file

In Integration → Logger file, copy a self-contained TypeScript module if you cannot import from npm (external services, scripts, other monorepo packages).

Without the SDK

POST JSON directly — see API reference.

cURL example

curl -X POST "$LOGGERMAN_BASE_URL/api/projects/$PROJECT_ID/logs" \
  -H "Authorization: Bearer $LOGGERMAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello from curl","type":"INFO","source":"cli"}'