Logging ColorKeywords

Color Keywords & Automatic Level Detection

The logging system automatically detects log levels from message content using keywords. This allows you to write natural log messages without explicitly specifying severity levels.

---

How It Works

RevitDevTool scans your log messages for specific keywords and automatically assigns the appropriate log level with color coding:

Level	Color	Keywords
Information	Blue	info, success, completed, finished, done, started
Warning	Yellow	warning, warn, caution, deprecated
Error	Red	error, failed, exception, crash
Critical	Dark Red	fatal, critical, panic
Debug	Gray	debug, verbose

---

Detection Methods

1. Prefix Detection (Highest Priority)

Add a bracketed prefix to your message for explicit level control:

Trace.WriteLine("[INFO] This will be Information level (blue)");
Trace.WriteLine("[WARN] This will be Warning level (yellow)");
Trace.WriteLine("[ERROR] This will be Error level (red)");
Trace.WriteLine("[FATAL] This will be Critical level (dark red)");
Trace.WriteLine("[DEBUG] This will be Debug level (gray)");

// Also works with Console
Console.WriteLine("[INFO] Console output as Information level");
Debug.WriteLine("[DEBUG] Debug output as Debug level");

Supported prefixes:

• [INFO], [INFORMATION] → Information (blue)
• [WARN], [WARNING] → Warning (yellow)
• [ERROR], [ERR] → Error (red)
• [FATAL], [CRITICAL] → Critical (dark red)
• [DEBUG] → Debug (gray)

2. Keyword Detection (Fallback)

If no prefix is found, the system scans the entire message for keywords:

Trace.WriteLine("Operation completed successfully");  // "completed" → Info (blue)
Trace.WriteLine("Warning: Memory usage is high");     // "warning" → Warning (yellow)
Trace.WriteLine("Error occurred during processing");  // "error" → Error (red)
Trace.WriteLine("Fatal crash detected in system");    // "fatal" → Critical (dark red)
Console.WriteLine("Task succeeded without issues");   // "succeeded" → Info (blue)
Debug.WriteLine("This is just a debug message");      // "debug" → Debug (gray)

---

Examples

C# Examples

// Using prefixes - most explicit
Trace.WriteLine("[INFO] Application started");
Trace.WriteLine("[WARN] Configuration file not found, using defaults");
Trace.WriteLine("[ERROR] Database connection failed");
Trace.WriteLine("[FATAL] Critical system failure");

// Using keywords - more natural
Trace.WriteLine("Successfully loaded 150 elements");      // → Info
Trace.WriteLine("Warning: High memory usage detected");   // → Warning
Trace.WriteLine("Failed to process element 123456");      // → Error
Trace.WriteLine("Fatal: Cannot initialize Revit API");    // → Critical

// No keywords - defaults to Information
Trace.WriteLine("Processing elements...");                // → Info (default)

Python Examples

For pyRevit/RevitPythonShell/Dynamo:

import clr
# For Revit 2025+ (.NET 8):
clr.AddReference("System.Diagnostics.TraceSource")
clr.AddReference("System.Console")

from System.Diagnostics import Trace
from System import Console

# Using prefixes
Trace.WriteLine("[INFO] Python script started")
Trace.WriteLine("[WARN] Element not found")
Trace.WriteLine("[ERROR] Export failed")

# Using keywords
Trace.WriteLine("Successfully created 50 walls")         # → Info
Trace.WriteLine("Warning: Door width exceeds limit")     # → Warning
Trace.WriteLine("Error: Invalid room boundary")          # → Error

# Console output also works
Console.WriteLine("[INFO] Analysis complete")

For RevitDevTool Python scripts:

# RevitDevTool automatically captures print() output
print("[INFO] Script started")
print("Successfully created 50 walls")          # → Info
print("Warning: Door width exceeds limit")     # → Warning  
print("Error: Invalid room boundary")          # → Error

# No import needed - works out of the box

---

Default Keywords

Information Level

• info, information
• success, successful, succeeded
• completed, complete
• finished, done
• started, begin, beginning
• loaded, created

Warning Level

• warning, warn
• caution, careful
• deprecated, obsolete
• high, low (when referring to resources)

Error Level

• error, err
• failed, fail, failure
• exception
• invalid, incorrect
• not found, missing
• timeout
• crash, crashed

Critical Level

• fatal
• critical
• panic
• severe

Debug Level

• debug
• verbose
• trace (as a noun, not the class name)

---

Color Output

Light Theme (Revit 2023 and earlier)

• Information: Blue text
• Warning: Yellow text
• Error: Red text
• Critical: Dark red text
• Debug: Gray text

Dark Theme (Revit 2024+)

• Information: Light blue text
• Warning: Orange text
• Error: Light red text
• Critical: Bright red text
• Debug: Light gray text

---

Case Insensitivity

All keyword matching is case-insensitive:

// All of these are detected as Error level:
Trace.WriteLine("ERROR: Failed");
Trace.WriteLine("error: failed");
Trace.WriteLine("Error: Failed");
Trace.WriteLine("An error occurred");

---

Best Practices

1. Use Prefixes for Clarity

When log level is critical, use explicit prefixes:

Trace.WriteLine("[ERROR] Transaction rolled back");  // Clear intent

2. Natural Keywords for Readability

For user-friendly messages, use natural language:

Trace.WriteLine("Successfully exported 100 families");  // Reads naturally

3. Combine Both Approaches

Prefix for level, keywords for context:

Trace.WriteLine("[WARN] Operation succeeded but with warnings");

4. Avoid Ambiguous Messages

Don't mix level keywords in one message:

// ❌ Bad - ambiguous
Trace.WriteLine("Error handling succeeded");  // Is this error or success?

// ✅ Good - clear
Trace.WriteLine("[INFO] Error handling succeeded");  // Explicit prefix

---

Customization

Note: Keywords are currently fixed in the codebase. Future versions may support user-customizable keyword sets in settings.

Current keywords are optimized for:

• English language messages
• Common development terminology
• Standard log level conventions

---

Examples in Context

Element Processing

Trace.WriteLine("[INFO] Starting element processing");
Trace.WriteLine("Processing 50 elements...");

foreach (var element in elements)
{
    try
    {
        ProcessElement(element);
        Trace.WriteLine($"Successfully processed {element.Id}");  // → Info
    }
    catch (Exception ex)
    {
        Trace.WriteLine($"Failed to process {element.Id}: {ex.Message}");  // → Error
    }
}

Trace.WriteLine("Processing completed with 3 warnings");  // → Warning

Python Script

from System.Diagnostics import Trace

Trace.WriteLine("[INFO] Wall analysis script started")

walls = collect_walls()
Trace.WriteLine(f"Successfully found {len(walls)} walls")  # → Info

for wall in walls:
    if wall.Width < 0.1:
        Trace.WriteLine(f"Warning: Wall {wall.Id} is too thin")  # → Warning
    
    if not wall.IsValidObject:
        Trace.WriteLine(f"Error: Invalid wall {wall.Id}")  # → Error

Trace.WriteLine("Analysis completed")  # → Info

---

Related Topics

• Logging Overview - Main logging documentation
• Python Stack Traces - Enhanced Python error formatting