Skip to content

Latest commit

 

History

History
288 lines (224 loc) · 11.8 KB

README-EMOJIS.md

File metadata and controls

288 lines (224 loc) · 11.8 KB

BackSpace Emoji Logging System

This document describes the emoji logging conventions used throughout BackSpace to make logs more scannable, expressive, and visually distinguishable.

Core Philosophy

Our logging system uses emojis as visual anchors that make it easy to:

  1. Quickly identify log categories by scanning the leftmost emoji
  2. Understand the operation context through consistent emoji phrases
  3. Highlight important information with visually distinct symbols
  4. Track operation flow with consistent start/end markers
  5. Identify error conditions at a glance

Standard Emoji Categories

1. Object Types (Nouns)

Entity Emoji Description
Collection 📚 Stack of books represents a collection
Item 🧩 Puzzle piece represents an individual item
Export 📦 Package/box represents export operations
Profile 🔖 Bookmark represents a configuration profile
Job ⚙️ Gear represents a background job
File 📄 Document represents a file
Cache 🧠 Brain represents memory/cache storage
Connector 🔗 Link/chain represents a connection to external service
Database 💾 Disk represents persistent storage
Config 🔧 Wrench represents configuration/settings
User 👤 Person represents user-related operations
API 🌐 Globe represents API/network operations

2. Actions (Verbs)

Action Emoji Description
Create/New ✨ Sparkles represent creation
Read/Get 🔍 Magnifying glass represents lookup/find
Update/Modify 📝 Pencil represents editing/updating
Delete/Remove 🗑️ Trash bin represents deletion
Process ⚡ Lightning represents processing
Initialize 🚀 Rocket represents startup/initialization
Download ⬇️ Down arrow represents download
Upload ⬆️ Up arrow represents upload
Export 📤 Outbox represents export
Import 📥 Inbox represents import
Validate ✅ Checkmark represents validation
Calculate 🧮 Abacus represents calculation
Transform 🔄 Recycling symbol represents transformation
Connect 🔌 Plug represents connection
Disconnect 🔌❌ Plug with X represents disconnection

3. Status Indicators

Status Emoji Description
Success ✅ Green checkmark represents success
Error ❌ Red X represents error/failure
Warning ⚠️ Warning sign represents warning
Info ℹ️ Information symbol represents general info
Debug 🐞 Bug represents debug information
Start 🏁 Start flag represents beginning of operation
Finish 🏆 Trophy represents successful completion
Pending ⏳ Hourglass represents waiting state
Running 🏃 Running figure represents in-progress state
Skipped ⏭️ Skip forward represents skipped operation
Blocked 🚧 Construction sign represents blocked operation
Critical 🔥 Fire represents critical/urgent issue

4. Measurement & Parameters

Parameter Emoji Description
Time ⏱️ Stopwatch represents time measurement
Duration ⏳ Hourglass represents elapsed time
Count 🔢 Numbers represents counts/quantities
Size 📏 Ruler represents size/dimensions
Performance 🚀 Rocket represents performance metrics
Memory 💾 Disk represents memory/storage metrics
Percentage 📊 Chart represents percentage/ratio
Currency 💰 Money bag represents financial values
ID 🔑 Key represents identifier
Name 📛 Name badge represents names
URL 🔗 Link represents URLs
Email 📧 Email symbol represents email addresses

Emoji Phrase Patterns

We compose emoji phrases following a consistent pattern:

[Status][Action][Object][Parameter]

For example:

  • ✅📝📚 = Success + Update + Collection
  • ❌🔍🧩 = Error + Search + Item
  • 🏁📤📦 = Start + Export + Package

Example Phrases

Operation Emoji Phrase Description
Start Collection Creation 🏁✨📚 Starting to create a collection
Collection Created ✅✨📚 Successfully created a collection
Collection Update Failed ❌📝📚 Failed to update a collection
Item Lookup 🔍🧩 Looking up an item
Export Processing ⚡📤📦 Processing an export operation
Processing Complete ✅⚡ Processing completed successfully
Download Start 🏁⬇️📄 Starting file download
Memory Cache Hit 🧠🔍 Found item in memory cache
Database Write 📝💾 Writing to database
API Request 🔍🌐 Making an API request

Unicode Symbols and Combinations

Emojis can be combined with other Unicode characters to create richer visual patterns:

Flow and Process Indicators

Purpose Symbol Description
Flow direction ➡️ ⬅️ ⬆️ ⬇️ Direction arrows
Process flow 🔄 ↻ ↺ 🔁 Rotation/recycling
Sequence ①②③ ❶❷❸ Numbered steps
Branching ⑂ ⑃ ⑄ ┣━┫ Branch symbols
Grouping 〔 〕 《 》 Grouping brackets

Progress and Status Bars

Progress Symbol Description
0% ▱▱▱▱▱▱▱▱▱▱ Empty progress
25% ▰▰▱▱▱▱▱▱▱▱ Quarter progress
50% ▰▰▰▰▰▱▱▱▱▱ Half progress
75% ▰▰▰▰▰▰▰▰▱▱ Three-quarter progress
100% ▰▰▰▰▰▰▰▰▰▰ Complete progress
Custom [▰▰▰▱▱▱▱▱▱▱] 30% Progress with percentage

Technical and Mathematical Symbols

Type Symbols Description
Math ∑ ∏ √ ∛ ∞ Mathematical operations
Comparison ≈ ≠ ≤ ≥ Comparison operators
Logic ∧ ∨ ¬ ⊕ Logical operators
Sets ∩ ∪ ∈ ∉ ⊂ Set operations
Technical ⌘ ⌥ ⎈ ⌫ Technical commands

Combined Emoji-Symbol Patterns

Purpose Pattern Description
Sequential steps 🏁 → ⚡ → 💾 → ✅ Process steps from start to finish
Hierarchical data 📚 ┣━ 🧩 ┣━ 📄 Parent-child relationships
State transition [⏳🔄] ⟹ [✅🏆] State change
Parameter values 🔢 items:42 ⎮ 📏 size:2.3MB Separated parameter list
Causal relation ❌ ∵ timeout ∴ 🔄 retry Because/therefore relationship

Log Line Structure

For consistent visual scanning, log lines should follow this pattern:

[TimeStamp] [LogLevel] [EmojiPhrase] [ClassName]: [MethodName]: [Message] [Parameters]

For example:

2023-08-15T14:23:45.342Z INFO 🏁📤📚 ExportManager: exportCollection: Starting collection export collection: scifi profiles: 2

Parameter Annotation

When displaying parameters, prefix each parameter with an appropriate emoji:

🔑 id: sci-fi123 📛 name: "Science Fiction" 🔢 items: 42

You can enhance this with Unicode separators:

🔑 id: sci-fi123 │ 📛 name: "Science Fiction" │ 🔢 items: 42

Implementation

The emoji logging system is implemented in src/lib/utils/logger.ts and provides:

  1. A standard set of emoji constants
  2. Helper functions for constructing emoji phrases
  3. Logger methods that efficiently handle emoji inclusion
  4. Performance considerations to avoid unnecessary work

Example Usage

// In a class method
public async processCollection(id: string): Promise<void> {
  const methodName = 'processCollection';
  this.logger.info(methodName, `${emojiPhrase('Start', 'Process', 'Collection')} Processing collection`, { id });
  
  try {
    // operation code...
    
    this.logger.info(methodName, `${emojiPhrase('Success', 'Process', 'Collection')} Collection processed`, { id });
  } catch (error) {
    this.logger.error(methodName, `${emojiPhrase('Error', 'Process', 'Collection')} Failed to process collection`, { id }, error);
    throw error;
  }
}

Visual Log Analysis Tips

When analyzing logs:

  1. Scan the leftmost emoji to quickly identify error conditions (❌)
  2. Look for paired start/end markers (🏁/🏆) to track operation flow
  3. Follow emoji object types (📚, 🧩, etc.) to track specific entities
  4. Notice emoji patterns to understand the application's behavior
  5. Track sequences with arrows and numbered indicators (→, ①, ②)

Advanced Unicode Art for Logs

Banners and Separators

════════════════════════ 🚀 SERVER STARTING 🚀 ════════════════════════

▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ CRITICAL ERROR ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓

≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈

Box Drawing for Grouped Logs

┌─────────────────────── Export Process ───────────────────────┐
│ 🏁📤 Started export job #1234                                │
│ ├── 📚 Collection: Science Fiction                           │
│ ├── 🧩 Items: 42                                             │
│ └── 📁 Target: /export/scifi                                 │
└───────────────────────────────────────────────────────────────┘

Error Highlighting

❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌
  DATABASE CONNECTION FAILED - SYSTEM CANNOT CONTINUE
❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌ ❌

Visual Metrics

Memory usage: 2.4GB  [▰▰▰▰▰▰▱▱▱▱] 60%
CPU load:     1.2    [▰▰▱▱▱▱▱▱▱▱] 20%
Disk space:   120GB  [▰▰▰▰▰▰▰▰▱▱] 80%

Operation Sequences

Collection Update Flow: 📝📚 → 💾 → 🔄 → ✅
╔═══════════╦══════════╦════════════╦═══════════╗
║ 1. MODIFY ║ 2. STORE ║ 3. PROCESS ║ 4. VERIFY ║
╚═══════════╩══════════╩════════════╩═══════════╝

Extended Unicode Emoji Art

For special log sections or important notices, consider these multi-character emoji art patterns:

Purpose Emoji Art Description
Critical Error 💥 🔥 🔥 🔥 💥 Flames indicating critical error
Major Success 🎉 ✨ 🏆 ✨ 🎉 Celebration for major milestone
Security Warning 🔒 ⚠️ 🔒 ⚠️ 🔒 Security-related warning
Performance Issue ⚡ 🐢 ⚡ 🐢 ⚡ Slow performance warning
Data Corruption 💾 🔨 💔 🔨 💾 Data corruption alert
Startup Banner 🚀 🚀 🚀 BackSpace Initialized 🚀 🚀 🚀 Application startup
Shutdown Banner 👋 👋 👋 BackSpace Shutting Down 👋 👋 👋 Application shutdown
Database Operations 💾 ⟲ 🔍 ⟳ 💾 Database read/write cycle
Metrics Dashboard 📊 📈 📉 📊 Performance metrics report