@flowlogs/js

Simple class-based logging SDK for Flowlog. Create a logger instance and use it throughout your application.

Installation

npm install @flowlogs/js

Usage

Basic Setup

import { Flowlog } from "@flowlogs/js";

// Create a logger instance
const logger = new Flowlog({
  apiKey: "your-api-key",
  apiUrl: "https://flowlog.io/api/v1/logs",
  service: "frontend",
});

// Use it anywhere in your application
logger.info("Render", { extra: "tester" });
logger.error("Error", { error, extra: "tester" });
logger.warn("Warning", { extra: "tester" });
logger.critical("Critical", { extra: "Tester" });

Configuration Options

const logger = new Flowlog({
  apiKey: "your-api-key", // Required: Your Flowlog API key
  apiUrl: "https://flowlog.io/api/v1/logs", // Required: Flowlog API endpoint
  service: "my-service", // Optional: Service name (defaults to 'unknown')
  env: "production", // Optional: Environment (defaults to NODE_ENV or 'development')
  enableConsoleFallback: true, // Optional: Enable console fallback on API failure (default: true)
  iterationKey: "optional-key", // Optional: Iteration key for grouping related logs
});

Logging Methods

• logger.info(message, data?) - Log an info message
• logger.error(message, data?) - Log an error message
• logger.warn(message, data?) - Log a warning message
• logger.critical(message, data?) - Log a critical message (mapped to error level for API)

Console Logging

When not in production (i.e., env !== 'production'), logs are automatically printed to the console for debugging. In production, logs are only sent to the Flowlog API.

Batching

Logs are automatically batched and sent to the API for efficiency:

• Maximum batch size: 50 logs or 64KB
• Flush interval: 5 seconds
• Automatic retry with exponential backoff (max 3 attempts)

Manual Flush

You can manually flush pending logs:

await logger.flush();

This is useful when you need to ensure logs are sent immediately, such as before application shutdown.

Examples

In a Logger File

// logger.ts
import { Flowlog } from "@flowlogs/js";

export const logger = new Flowlog({
  apiKey: process.env.FLOWLOG_API_KEY!,
  apiUrl: process.env.FLOWLOG_API_URL!,
  service: "my-app",
  env:
    process.env.NODE_ENV === "production"
      ? "production"
      : "development",
});

Using the Logger

// app.ts
import { logger } from "./logger";

logger.info("Application started");
logger.error("Failed to connect", {
  error: new Error("Connection failed"),
});
logger.warn("Deprecated API used", { endpoint: "/old-endpoint" });
logger.critical("System failure", { component: "database" });

TypeScript Support

Full TypeScript support with type definitions included. All types are exported:

import {
  Flowlog,
  type FlowlogConfig,
  type LogLevel,
} from "@flowlogs/js";

Browser and Node.js Support

Works in both browser and Node.js environments. In browsers, logs are automatically flushed on page unload using the keepalive fetch option.

Error Handling

If the API is unavailable:

• Logs are queued for retry with exponential backoff
• After max retries, logs are sent to console (if enableConsoleFallback is true)
• In development mode, logs are always sent to console for debugging

License

MIT