Fly Logging

Fly Logging is a lightweight, standalone logging tool designed for simplicity and flexibility. With features like runtime log filtering, color-coding, and conditional logging, it enhances development efficiency by enabling easy toggling of specific log messages, helping to avoid unnecessary code rewrites.

Core Concept

The core concept of Fly Logging revolves around the idea that logging should be a flexible and integral part of the development and debugging process. Unlike traditional loggers that follow a one-dimensional level hierarchy, Fly Logging introduces a more dynamic approach, allowing developers to easily filter and manage logs. This makes Fly Logging not just a tool for logging errors but a versatile instrument to streamline development workflows.

Out-of-the-box features include:

• Tag-Based and Filename Filtering: Easily filter logs by tags or originating files.
• Flexible Settings: Tailor Fly Logging to your needs with customizable settings.
• Automatic Filename Detection: Automatically detect and log the source filename.
• Log Customization: Modify log appearance and behavior for specific messages.
• Level Customization: Define and use custom log levels with unique filters.
• Enhanced Readability: Smart spacing for clearer and more readable log messages.

Table of Contents

• Installation
• Documentation
  • How To Use Fly Logging
  • Quick Start Guide
  • Advanced Use
  • Fly Logging Settings
  • Configuring Blacklists And Whitelists
• Examples

Installation

Method 1 (NPM)

To install with npm, simply run the command

npm i @slasherrose/fly-logging

Method 2 (Copy-Paste)

To manually add Fly Logging to your project, follow these instructions:

For CommonJS

1. Download the dir /src/commonjs
2. Insert it into your project.
3. Rename the dir commonjs to fly-logging for clarity
4. Import the module as follows const { Fly } = require(./fly-logging/index.cjs)

For ECMAScript

1. Download the dir /src/module
2. Insert it into your project.
3. Rename the dir module to fly-logging for clarity
4. Add the requirement as follows import { Fly } from "./fly-logging/index.js";

(back to top)

Documentation

Usage

Quick Start

Initialize Fly
Create a Fly instance with a unique identifier.

const fly = Fly("uniqueID");

(NOTE: Unless otherwise specified by the settings, a Fly instance uses standard logging functions (see Levels for more details))

Log A Message Use the log method followed by .out() to output your message.

fly.log("Your log message").out();

Colors

Logs messages can be given a color in line to help with identification:

const fly = new Fly("demo", { defaultMessageColor: "BLUE"})

fly.log("Normal message").out();				// This will print with default color BLUE
fly.log("IMPORTANT!!").color("RED").out();		// This will print as red
fly.log("Another normal message.").out();		// This will print with default color BLUE

(NOTE: The color function only affects the color of the message, not additional log attributes. You can adjust those through the settings object).

Conditional Coloring

Conditional coloring allows you to color log messages only if a condition is met:

const n = 3;
fly.log("when n is 3, I am green!")
	.color("RED")
	.if(n < 3)			// When this condition is met, the log message will be RED
	.color("GREEN")
	.if(n === 3)		// When this condition is met, the log message will be GREEN
	.color("YELLOW")
	.if(n > 3)			// When this condition is met, the log message will be YELLOW
	.out();

List Of Available Colors

|color| ANSI| |-----|-----| |Black |\u001b[30m| |Red |\u001b[31m| |Green |\u001b[32m| |Yellow |\u001b[33m| |Blue |\u001b[34m| |Magenta |\u001b[35m| |Cyan |\u001b[36m| |White |\u001b[37m| |Reset |\u001b[0m| |Light_Black |\u001b[90m| |Light_Red |\u001b[91m| |Light_Green |\u001b[92m| |Light_Yellow |\u001b[93m| |Light_Blue |\u001b[94m| |Light_Magenta |\u001b[95m| |Light_Cyan |\u001b[96m| |Light_White |\u001b[97m|

Tagging

Tagging can be a useful feature for log identification and blacklisting messages.

fly.log("hello world!").tag("hello_world").out();

You can also have multiple tags on the same log

fly.log("Foo Bar")
	.tag("foo")
	.tag("bar")
	.out();

Conditional Tagging

Conditional tagging allows you to tag log messages only if a condition is met:

const start = true;
fly.log("hello world!")
	.tag("is_start")
	.if(start)			// if start is set to true, then this will have the above tag. 
	.out();

Conditional Logging

It is possible to run a log only when certain conditions are met, similar to the conditional tagging and conditional coloring.

fly.log("I will print")
	.if(1 === 1) 						
	.out();

fly.log("I will not print")
	.if(1 === 2)
	.out();

(NOTE: In order to run the .if() command for the log as a whole, you cannot put it after a .color() or .tag(), as that will perform a conditional color or conditional tagging)

(back to top)

Settings

Settings can be passed as the second parameter while initializing a fly

const fly = new Fly("demo", {printTags: false, ... })

Settings List

| Setting | Description | Default Value | |----------|----------|----------| |filename |if provided, then will override the auto-detected filename | null | |autoDetectFileName |when true, the fly will attempt to detect the name of the file it is located in | true |noColors|when true, no colors will be generated in the log regardless of other settings|false |defaultMessageColor|the default color that all messages will be|"BLUE" |defaultFileNameColor|the default color for the file name|"CYAN" |defaultIdColor|the default color for the log ID|"MAGENTA" |defaultLevelColor|the default color for the log level|"YELLOW" |defaultTagsColor|the default color for the log tags|"GREEN" |levels|an object containing different log levels and their configurations|See Section "Levels" |keepDefaultLevels|when true, keeps the default log levels provided|true |thresholdLevel|the minimum log level required for a log to be displayed|0 |allowStringReturn|when true, allows logs to return a string (will continue to print as normal)|true |printTags|when true, prints the tags associated with a log|true | printLevel | when true, prints the log level| false| | printFileName| when true, prints the file name | true| | printId | when true, prints the log ID| true| | printLabels| when true, prints the labels (fileName, id, message, level, tags) in the specified order| true| | printOrder | an array specifying the order in which the labels should be printed| ["fileName", "id", "message", "level", "tags"] | | logDelimiter| the delimiter used to separate sections of the logs when printing| "; "| | tagDelimiter| the delimiter used to separate tags when printing| ", "| | blacklist| See section On Blacklisting | undefined | whitelist| See section On Whitelisting | undefined

Levels

The levels object contains different log levels and their configurations.

Default Levels

| Name | Value | Default Color | |----------|-------|---------------| | trace | 10 | - | | debug | 100 | - | | log | 200 | - | | info | 300 | - | | warn | 400 | YELLOW | | error | 500 | RED | | critical | 1000 | RED |

Custom Log Levels

You can customize the log levels and their configurations according to your requirements.

Example

const { LogLevel } = require("fly-logging")

const settings = {
	fileName: fileName,
	keepDefaultLevels: true, // keep defaults (trace, log, error, etc)
	levels: {
		foo: new LogLevel({ value: 12 }), // Create a new level called "foo" with value of 12 (useful for threshholding)
		bar: new LogLevel({ value: 2000, defaultColor: "RED", forceCaps: true}) // Create a new level called "bar"
	},
};

const fly = Fly("demo", settings);

fly.log("default log level").out();
fly.foo("custom log level").out();
fly.bar("custom log level with color and forced caps").out();

(back to top)

Configuring Blacklists And Whitelists

Control what gets logged with blacklist and whitelist features:

• Blacklist: Specify logs that should be ignored.
• Whitelist: Define logs that are always displayed, regardless of other settings.

Creating A Blacklist / Whitelist

The following attributes can be black/whitelisted as needed:

• id
• filename
• tag

(NOTE: To filter by log level, set the fly's thresholdLevel level in its settings)

How To Use

You can combine attributes for more complex filtering. To block when two or more parameters are both present, add them to the same object in your black/whitelist. To block when any/either of the parameters are met, add them to different objects.

Blacklist Examples

 [
	{"file": "file1.js", "tag": "foo"}, 
	{"id": "badFlyId", "tags": ["foo", "bar"]} 
]

	const blacklist = require("blacklist.json");

	// RULE ONE {"file": "file1.js", "tag": "foo"}
	const fly = new Fly("fly", {fileName: "file1.js", blacklist});
	fly.log("hello world!").out(); // this will print, because it does not contain the prohibited tag
	fly.log("hello world!").tag("bar").out(); // this will print, because this tag is not prohibited for this file/id
	fly.log("hello world!").tag("foo").out(); // this will NOT print, because the tag and fileName match the prohibited values

	...

	// RULE TWO {"id": "badFlyId", "tags": ["foo", "bar"]}  
	
	const fly2 = new Fly("badFlyId", {fileName: "notBlacklisted.js", blacklist});
	fly2.log("hello world!").out(); //This will print, because it is not tagged with EITHER of the prohibited tags (foo and bar)
	fly2.log("hello world!").tag("foo").out(); // this will print, because it is tagged with ONLY ONE of the prohibited tags
	fly2.log("hello world!").tag("foo").tag("bar").out(); // this will NOT print, because has a forbidden id and BOTH prohibited tags for that ID
	

(NOTE: the rule shown above for blacklists also apply to whitelists)

Blacklisting via Factory Function

For a project-wide blacklist, consider using a FlyFactory that reads from a JSON file.

Example FlyFactory with Blacklist

const blacklist = require("blacklist.json");
const { Fly } = require("fly-logging");

function FlyFactory(id, settings) {
	return new Fly(id, {...settings, blacklist: blacklist})
}

(back to top)

Examples

Example (basic)

const fly = Fly("demo"); // creates fly with default settings

fly.log("hello world").out();

Example (advanced)

const { Fly } = require("fly-logging");

const fly = Fly("counterTrackingFly", {
	printFileName: false,
	printId: false,
});
let number = 0;
fly.log("the number is currently", number, ".").out();

while (number < 5) {
	number++;

	fly.log("the number is now '", number, "'")
        .tag("count")
        .out();

	fly.log("the number (", number, ") is even") // print this log only when the number is even.
		.if(number % 2 === 0)
		.color("RED") // When this log runs, color the message red.
		.tag("parity")
		.out();
}

fly.log("the number has finished counting. It is now at", number, ".")
	.color("green")
	.if(number % 2 === 0) // If the number is even when it ends, color it green.
	.color("magenta")
	.if(number % 2 !== 0) // If the number is odd when it ends, color it magenta.
	.out();

(back to top)