Developer Quickstart Guide

Learn how to integrate the dynamic logging client and trace metrics using our telemetry middlewares.

1. Platform Quickstart

To begin capturing application logs and metrics, you will need to register an account on LogFlow, allocate a pipeline project workspace, and generate an authorized API write token.

Telemetry Security Guidelines

All API keys must remain strictly secret on your server-side environment. Do not bundle or expose these keys within client-facing React/Next.js files as they possess direct telemetry writing scopes.

2. Telemetry Architecture Spec

LogFlow uses high-capacity queuing telemetry buffers. When you emit a log line via the SDK, it does not issue an immediate blocking network transaction. Instead, logs are pooled internally and dispatched as bulk payloads, preserving thread operations.

System metrics, process IDs, and memory utilization stamps are automatically attached to the JSON trace payloads before transmission to your telemetry gateway.

3. SDK Installation

Add the lightweight telemetry compiler as a dependency inside your Node.js application packages:

BASH

npm install logflow-sdk

4. ExpressJS Middleware Hook

Initialize the LogFlow instance inside your ExpressJS server core routing module. Provide the authorization keys and ingestion endpoints to hook the middleware handler:

TYPESCRIPT

import { LogFlow } from 'logflow-sdk';

const logger = new LogFlow({
  apiKey: process.env.LOGFLOW_API_KEY!,
  baseUrl: process.env.LOGFLOW_BASE_URL!
});

// Initialize connection buffer
await logger.initialize();

// Wrap Express application router
app.use(logger.middleware());

This basic setup intercepts request metadata, timing statistics, and route execution results, channeling them asynchronously to your LogFlow project console.

5. Configuration Parameters

The LogFlow class constructor accepts several optional keys to tune stream dispatch intervals, buffer capacities, and networking timeout configurations:

Parameter	Type	Default	Description
apiKey	string	REQUIRED	The unique write authorization token generated in your LogFlow project dashboard.
baseUrl	string	REQUIRED	Your ingestion gateway server base URL. (e.g. https://ingress.logflow.io).
flushIntervalMs	number	5000	Interval at which queued logs in memory are packaged and sent in bulk. Minimum value: 1000ms.
batchSize	number	20	Maximum number of telemetry lines pooled before initiating an immediate bulk post request.
retries	number	1	Maximum retry handshakes to execute if a bulk telemetry push fails due to network dropouts.
timeoutMs	number	10000	Request connection abort threshold for networking handshakes to the telemetry gateway.
console	boolean	false	If set to true, diagnostic logs and SDK initialization metrics are mirrored to local stdout.

Example configuration initializing standard overrides for production telemetry limits:

TYPESCRIPT

import { LogFlow } from 'logflow-sdk';

const logger = new LogFlow({
  apiKey: process.env.LOGFLOW_API_KEY!,
  baseUrl: process.env.LOGFLOW_BASE_URL!,
  flushIntervalMs: 2000,   // Flush logs every 2 seconds
  batchSize: 50,           // Dispatch early if 50 logs aggregate
  retries: 3,              // Attempt 3 connection retries
  timeoutMs: 5000,         // Time out request after 5 seconds
  console: true            // Output debug telemetry to server stdout
});

await logger.initialize();
app.use(logger.middleware());

6. Telemetry Lifecycle Ingestion Flow

The following flowchart illustrates the non-blocking lifecycle of log lines and application metrics from execution within the Express middleware to successful database indexing:

1. Ingress Request Interceptor

Express route executes; LogFlow middleware captures response headers, CPU time, and route indicators.

2. Local In-Memory Buffer

Captured log is serialized to JSON and pushed into a thread-safe local queue. The main HTTP response finishes immediately without lag.

3. Flush Condition Triggered

The internal loop scheduler evaluates batch criteria: has flushIntervalMs passed, or has local pool length hit batchSize?

4. Bulk Network Transmission

Telemetry packages are aggregated into a unified bulk payload and transmitted asynchronously to the Edge Ingress Gateway.

5. Edge Gateways Parsing

The ingestion gateway verifies authorization keys, performs schema validation, and structures logs into ingestion streams.

6. Columnar Logs Lake Indexing

Telemetry is stored securely in highly partitioned columnar shards, instantly visible in the LogFlow console.

7. Offline Ingestion Safeties

When a microservice network gateway is temporarily blocked, or the telemetry ingress suffers downtime, LogFlow protects server memory limits:

Ingestion Failures & Memory Bounds Protection

The Express SDK holds an internal circuit breaker buffer. If LogFlow's ingestion edge gateways become unreachable, logs will pool locally in a secondary safety queue for up to 5 minutes before executing safety drops to prevent memory allocation bounds from locking server processes.