Flowgger

What is Flowgger?

Unlike traditional logging tools, Flowgger requires users to define the flow of their code in advance in .stflow files.

Flowgger matches logging statements against this predefined flow and logs only the step ID. This drastically reduces log size while providing all relevant information in a single log entry, such as execution time of each step, the entire flow, sequence of steps, and flow status.

Reduced Log Size

Logs are minimal, resulting in faster logging and reduced storage requirements. Save up to 90% on log storage costs.

Roadmap

Features planned for future releases:

IN PROGRESS

System level non-flow appenders
Dynamic appenders for temporary debug files

PLANNED

CommonJS module support
Browser support with text-based flows
Integration with Logstash and chat platforms
VS Code plugin: Jump to code from .stflow files
Smart filtering with key consideration

Key Features

Flow Definition

Define code flows in .stflow files. Visualize them in VS Code using the Text2Chart extension.

Keyed Logging

Assign keys to logs for testing new features. Disable them later without deployment or restart.

Play/Pause Controls

Selectively enable or disable logs for specific flows, types, or keys at runtime.

Smart Filtering

Use onlyFor and notFor filters to route logs to specific streams based on flow or type.

Custom Appenders

Write logs to multiple destinations. Send errors to email or chat platforms automatically.

Execution Timing

Track execution time for each step and the entire flow automatically.

Quick Start

Installation

npm install @solothought/flowgger

Basic Setup

import Flowgger from '@solothought/flowgger';

const config = {
  appenders: [
    {
      handler: appenderFn,
      layout: layoutFn,
      onlyFor: {
        types: [],
        flows: []
      }
    }
  ],
  flow: {
    source: path.resolve("./flows"),
    // maxIdleTime: 200
  }
}

// Create Flowgger instance once at application level
const flowgger = new Flowgger(config);

Usage Example

// Initialize logger for a specific flow
const binFlow = flowgger.init("Binary Search");

// Log flow steps
binFlow.info("read low");
binFlow.info("read high");

// Log additional data
binFlow.debug("values", {low: lowVal, high: highVal});

// Handle errors
binFlow.error("NULL POINTER EXCEPTION", e.stackTrace());

// End the flow
binFlow.end();

Pro Tip: The order of steps in your code must match the flow defined in your .stflow file.

Performance Comparison

Smaller log sizes mean faster logging and reduced storage costs.

Log Size Reduction

Comparison between Flowgger and traditional logging frameworks:

Scenario	Log Statements	Avg Length	Size Reduction
Small Application	20 logs/API	20 chars	~85%
Medium Application	20 logs/API	50 chars	~88%
Large Application	50 logs/API	50 chars	~90%

Example: With 10 APIs and 1000 requests each, Flowgger generates 2.75 MB logs compared to 22.3 MB with traditional frameworks (20 log statements per API, 50 chars average).