# 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:

```csharp
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:

```csharp
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

```csharp
// 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:**

```python
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:**

```python
# 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**:

```csharp
// 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:

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

### 2. Natural Keywords for Readability
For user-friendly messages, use natural language:

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

### 3. Combine Both Approaches
Prefix for level, keywords for context:

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

### 4. Avoid Ambiguous Messages
Don't mix level keywords in one message:

```csharp
// ❌ 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

```csharp
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

```python
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](Logging-Overview.md) - Main logging documentation
- [Python Stack Traces](Logging-PythonStackTraces.md) - Enhanced Python error formatting