Output Formats
The Brobot logging system supports three output formats, each optimized for different use cases.
SIMPLE Formatโ
Human-readable format for development and debugging.
Configurationโ
brobot.logging.output.format=SIMPLE
Example Outputโ
[14:23:45.123] [ACTIONS] INFO - Searching for login button... [FIND->submitButton]
[14:23:45.148] [ACTIONS] INFO - Login button found! [FIND->submitButton] โ (95%) (0.025s) @(100,200)
[14:23:45.163] [ACTIONS] INFO - Clicked submit button [CLICK->submitButton] โ (0.015s) @(100,200)
[14:23:45.313] [TRANSITIONS] INFO - Navigated to Settings [state_change] โ (0.150s)
[14:23:50.456] [PERFORMANCE] INFO - Batch processing completed [batch_process] โ (5.000s)
[14:23:50.457] [MATCHING] WARN - Low similarity match detected (65%)
[14:23:50.500] [SYSTEM] ERROR - Connection failed: timeout after 30s โ
Format Breakdown:
[HH:mm:ss.SSS]- Timestamp (ifinclude-timestamp=true)[CATEGORY]- Log category (ACTIONS, TRANSITIONS, etc.)LEVEL- Log level (INFO, WARN, ERROR, DEBUG)Message- Custom or automatic log message[ACTION->TARGET]- Action type and target objectโ/โ- Success/failure symbol(XX%)- Similarity score (for pattern matching)(X.XXXs)- Duration in seconds@(x,y)- Location coordinates (if applicable)
When to Useโ
- During development
- Manual debugging sessions
- Quick console monitoring
- Local testing
STRUCTURED Formatโ
Key-value format for log aggregation tools.
Configurationโ
brobot.logging.output.format=STRUCTURED
brobot.logging.output.include-timestamp=true
brobot.logging.output.include-correlation-id=true
Example Outputโ
timestamp=2024-01-15T10:30:45.123Z category=ACTIONS level=INFO thread=main correlation=a1b2c3d4 message="Searching for login button..." action.type=FIND action.target=submitButton
timestamp=2024-01-15T10:30:45.148Z category=ACTIONS level=INFO thread=main correlation=a1b2c3d4 message="Login button found!" action.type=FIND action.target=submitButton action.success=true timing.duration=0.025s match.similarity=95% location.x=100 location.y=200
timestamp=2024-01-15T10:30:45.163Z category=ACTIONS level=INFO thread=main correlation=a1b2c3d4 message="Clicked submit button" action.type=CLICK action.target=submitButton action.success=true timing.duration=0.015s
timestamp=2024-01-15T10:30:45.313Z category=TRANSITIONS level=INFO thread=main correlation=a1b2c3d4 message="Navigated to Settings" state.from=MainMenu state.to=Settings action.success=true timing.duration=0.150s
Format Breakdown:
- Pure space-separated
key=valuepairs - Nested properties use dot notation:
action.type,timing.duration,location.x - String values with spaces are quoted:
message="..." - Timestamps in ISO-8601 format
- Consistent field ordering: timestamp, category, level, thread, correlation, message, then contextual fields
Key-Value Pairsโ
- Easy to parse with tools like grep, awk, sed
- Compatible with log aggregation systems (Splunk, ELK)
- Maintains readability while being machine-parseable
- Grep-friendly:
grep 'action.type=FIND' logs.txt
When to Useโ
- Test environments
- Log aggregation with tools like Splunk, ELK
- When you need both human and machine readability
- Debugging with correlation tracking
JSON Formatโ
Machine-readable format for automated processing and monitoring.
Configurationโ
brobot.logging.output.format=JSON
brobot.logging.output.include-timestamp=true
brobot.logging.output.include-correlation-id=true
brobot.logging.output.include-state-context=true
Example Outputโ
{
"@timestamp": "2024-01-15T10:30:45.148Z",
"@version": "1",
"category": "ACTIONS",
"level": "INFO",
"message": "Login button found!",
"thread": "main",
"correlation": {
"id": "a1b2c3d4",
"session": "session_12345",
"operation": "user-login"
},
"action": {
"type": "FIND",
"target": "submitButton",
"success": true
},
"timing": {
"duration": 25,
"durationFormatted": "0.025s"
},
"match": {
"similarity": 0.95,
"similarityPercent": "95%"
},
"location": {
"x": 100,
"y": 200
},
"state": {
"current": "MainMenu"
}
}
Format Breakdown:
@timestamp,@version- ELK Stack standard fields- Nested objects for logical grouping:
correlation,action,timing,match,location,state - camelCase naming convention for fields
- Both numeric and formatted values (e.g.,
duration: 25anddurationFormatted: "0.025s") - Hierarchical structure for easy querying in JSON-aware tools
Complex Event Exampleโ
{
"@timestamp": "2024-01-15T10:30:50.456Z",
"@version": "1",
"category": "PERFORMANCE",
"level": "INFO",
"message": "Batch processing completed",
"thread": "worker-pool-1",
"correlation": {
"id": "a1b2c3d4",
"session": "session_12345",
"operation": "batch_process"
},
"timing": {
"duration": 5000,
"durationFormatted": "5.000s",
"breakdown": {
"initialization": 100,
"processing": 4500,
"cleanup": 400
}
},
"performance": {
"itemsProcessed": 150,
"throughput": 30.0,
"memoryUsedBytes": 52428800,
"peakMemoryMb": 75
}
}
When to Useโ
- Production environments
- Integration with monitoring tools (Datadog, New Relic, CloudWatch)
- Automated log analysis
- Metrics collection and alerting
- Long-term log storage
Visual Symbols and Colorsโ
Brobot uses Unicode symbols and ANSI colors for clear, visually-appealing console output through the AnsiColor utility class.
Symbol Referenceโ
The following symbols are available in io.github.jspinak.brobot.debug.AnsiColor:
| Symbol | Unicode | Constant | Common Usage |
|---|---|---|---|
| โ | Check mark | AnsiColor.CHECK | Success indicators |
| โ | X mark | AnsiColor.CROSS | Failure indicators |
| โ | Right arrow | AnsiColor.ARROW_RIGHT | Action progression, transitions |
| โ | Left arrow | AnsiColor.ARROW_LEFT | Backward navigation |
| โ | Up arrow | AnsiColor.ARROW_UP | Scroll up, priority increase |
| โ | Down arrow | AnsiColor.ARROW_DOWN | Scroll down, priority decrease |
| โข | Bullet | AnsiColor.BULLET | List items |
| โ | Star | AnsiColor.STAR | Important items |
| โ | Warning | AnsiColor.WARNING_SIGN | Warnings, cautions |
| โน | Info | AnsiColor.INFO_SIGN | Informational messages |
| โณ | Hourglass | AnsiColor.HOURGLASS | Wait operations |
| ๐ | Clock | AnsiColor.CLOCK | Timing information |
Color Codesโ
Colors are automatically enabled via the Jansi library, which provides ANSI support on all platforms including Windows.
Standard Colors:
import io.github.jspinak.brobot.debug.AnsiColor;
// Available standard color constants
AnsiColor.RED // \u001B[31m
AnsiColor.GREEN // \u001B[32m
AnsiColor.YELLOW // \u001B[33m
AnsiColor.BLUE // \u001B[34m
AnsiColor.MAGENTA // \u001B[35m
AnsiColor.CYAN // \u001B[36m
// Example usage
System.out.println(AnsiColor.RED + "Red text" + AnsiColor.RESET);
System.out.println(AnsiColor.GREEN + "Green text" + AnsiColor.RESET);
Semantic Colors (Recommended):
import io.github.jspinak.brobot.debug.AnsiColor;
// Semantic color constants (recommended for logging)
AnsiColor.SUCCESS // Bright green - successful operations
AnsiColor.ERROR // Bright red - errors and failures
AnsiColor.WARNING // Bright yellow - warnings
AnsiColor.INFO // Bright cyan - informational messages
AnsiColor.DEBUG // Bright magenta - debug information
AnsiColor.HEADER // Bold bright blue - section headers
AnsiColor.DIMMED // Bright black/gray - secondary info
// Example usage with helper methods
System.out.println(AnsiColor.success("Operation completed successfully"));
System.out.println(AnsiColor.error("Critical error occurred"));
System.out.println(AnsiColor.warning("Warning: threshold exceeded"));
System.out.println(AnsiColor.info("Information: process started"));
Platform Supportโ
Cross-Platform Compatibility:
- Windows: Full Unicode and ANSI support via Jansi library
- Mac/Linux: Native terminal support
- WSL: Full support when using Windows Terminal
- CI/CD: Works in most modern CI environments (GitHub Actions, GitLab CI, Jenkins)
Terminal Detection: AnsiColor automatically initializes Jansi on Windows:
import org.fusesource.jansi.AnsiConsole;
/**
* This is a code snippet from io.github.jspinak.brobot.debug.AnsiColor
* showing how Jansi is automatically initialized on Windows platforms.
*
* This code is for reference only - it runs automatically when AnsiColor is loaded.
* You don't need to include this in your code.
*/
static {
AnsiConsole.systemInstall();
String os = System.getProperty("os.name").toLowerCase();
if (os.contains("win")) {
System.out.println("[Brobot Debug] Windows detected - ANSI colors enabled via Jansi");
}
}
๐ก Note: There is NO automatic fallback to ASCII (
[OK],[FAIL], etc.). Brobot uses Unicode symbols consistently across all platforms. If symbols don't display correctly, upgrade your terminal rather than expecting ASCII fallbacks.
Usage Examplesโ
Basic Colorization:
import io.github.jspinak.brobot.debug.AnsiColor;
// Simple colored text
System.out.println(AnsiColor.success("Operation completed!"));
System.out.println(AnsiColor.error("Failed to connect"));
System.out.println(AnsiColor.warning("Connection timeout approaching"));
// Custom color
String message = AnsiColor.colorize("Custom message", AnsiColor.CYAN);
Symbols in Log Messages:
import io.github.jspinak.brobot.debug.AnsiColor;
public class SymbolsExample {
public void demonstrateSymbols() {
// Success/failure indicators
System.out.println(AnsiColor.CHECK + " Test passed");
System.out.println(AnsiColor.CROSS + " Test failed");
// Action progression
System.out.println(AnsiColor.ARROW_RIGHT + " Processing next item");
// Warnings
System.out.println(AnsiColor.WARNING_SIGN + " Low memory warning");
}
}
Formatted Boxes:
import io.github.jspinak.brobot.debug.AnsiColor;
public class BoxesExample {
public void demonstrateBoxes() {
String boxContent = AnsiColor.box(
"Test Results",
"Passed: 45\nFailed: 2\nSkipped: 3",
AnsiColor.SUCCESS
);
System.out.println(boxContent);
}
}
Combined Usage:
import io.github.jspinak.brobot.debug.AnsiColor;
public class CombinedUsageExample {
public void demonstrateActionLogging() {
// Action logging pattern - before action
System.out.println(
AnsiColor.ARROW_RIGHT + " " +
AnsiColor.info("CLICK") + " " +
"submitButton"
);
// Action logging pattern - after successful action
System.out.println(
AnsiColor.CHECK + " " +
AnsiColor.success("CLICK") + " " +
"submitButton | loc:(245,180) | 32ms"
);
}
}
Box Drawing Charactersโ
Available for creating visual structures:
| Character | Constant | Unicode |
|---|---|---|
| โ | BOX_TOP_LEFT | Double line |
| โ | BOX_TOP_RIGHT | Double line |
| โ | BOX_BOTTOM_LEFT | Double line |
| โ | BOX_BOTTOM_RIGHT | Double line |
| โ | BOX_HORIZONTAL | Double line |
| โ | BOX_VERTICAL | Double line |
| โ | BOX_HORIZONTAL_LIGHT | Single line |
Troubleshooting Display Issuesโ
Symbols Not Displaying:
- Windows: Use Windows Terminal instead of legacy Command Prompt
- WSL: Set
TERM=xterm-256colorin your shell - IDE: Most modern IDEs support Unicode (IntelliJ IDEA, VS Code, Eclipse)
- SSH: Ensure your SSH client supports UTF-8 (PuTTY requires configuration)
Colors Not Showing:
- Jansi should handle this automatically on all platforms
- If colors still don't work, check terminal's ANSI support
- Colors are automatically disabled if terminal doesn't support ANSI
Missing Jansi Dependency:
If you see [Brobot Debug] Windows detected - ANSI colors enabled via Jansi at startup, colors are working.
If this message doesn't appear on Windows, verify Jansi is in your dependencies:
implementation 'org.fusesource.jansi:jansi:2.4.0'
Format Comparisonโ
| Feature | SIMPLE | STRUCTURED | JSON |
|---|---|---|---|
| Human Readable | โ Excellent | โ Good | โ ๏ธ Moderate |
| Machine Parseable | โ Poor | โ Good | โ Excellent |
| Storage Efficiency | โ High | โ ๏ธ Medium | โ Low |
| Tool Compatibility | โ Limited | โ Good | โ Excellent |
| Debugging Ease | โ Excellent | โ Good | โ ๏ธ Moderate |
| Production Ready | โ No | โ Yes | โ Yes |
Custom Formattingโ
You can implement custom formatters by implementing the LogFormatter interface.
LogEntry Fieldsโ
The LogEntry class provides extensive data for custom formatting:
Core Fields:
timestamp,category,level,messagethreadName,correlationId,sessionId,operationName
Action Fields:
actionType,actionTarget,successsimilarity(for pattern matching actions)location(x, y coordinates)
Performance Fields:
duration,operationStartTime,operationDepthmemoryUsage,operationCount
Error Fields:
error(Throwable),errorMessage
State Fields:
currentState,targetState
Metadata:
metadata(Map<String, Object>) for custom key-value data
Custom Formatter Implementationโ
You can implement custom formatters by implementing the LogFormatter interface:
package com.example.brobot.logging;
import org.springframework.stereotype.Component;
import io.github.jspinak.brobot.logging.LogFormatter;
import io.github.jspinak.brobot.logging.LogEntry;
/**
* Example custom formatter implementation.
* Implements the LogFormatter interface to provide custom log formatting.
*/
@Component
public class CustomFormatter implements LogFormatter {
@Override
public String format(LogEntry entry) {
// Custom formatting logic
return String.format("[%s] %s: %s",
entry.getCategory(),
entry.getLevel(),
entry.getMessage());
}
}
Register your custom formatter in the configuration:
package com.example.brobot.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Autowired;
import io.github.jspinak.brobot.logging.BrobotLogger;
import io.github.jspinak.brobot.logging.BrobotLoggerImpl;
import io.github.jspinak.brobot.logging.LogFormatter;
import io.github.jspinak.brobot.logging.LoggingConfiguration;
import io.github.jspinak.brobot.logging.CorrelationContext;
/**
* Example configuration class showing how to register a custom formatter.
*/
@Configuration
public class CustomFormatterConfiguration {
@Autowired
private CorrelationContext correlationContext;
@Bean
public BrobotLogger brobotLogger(LoggingConfiguration config) {
LogFormatter formatter = new CustomFormatter();
return new BrobotLoggerImpl(config, formatter, correlationContext);
}
}
Output Examples by Categoryโ
Actions Categoryโ
# SIMPLE
[ACTIONS] INFO CLICK loginButton โ SUCCESS [15ms] loc:(500,300)
# STRUCTURED
[ACTIONS] CLICK loginButton | success=true duration=15 location=(500,300)
# JSON
{"category":"ACTIONS","level":"INFO","action_type":"CLICK","target":"loginButton","success":true,"duration_ms":15}
Transitions Categoryโ
# SIMPLE
[TRANSITIONS] INFO MainMenu โ Settings SUCCESS [200ms]
# STRUCTURED
[TRANSITIONS] state_change | from=MainMenu to=Settings success=true duration=200
# JSON
{"category":"TRANSITIONS","from":"MainMenu","to":"Settings","success":true,"duration_ms":200}
Performance Categoryโ
# SIMPLE
[PERFORMANCE] INFO batch_process [5000ms] items:150 throughput:30/s
# STRUCTURED
[PERFORMANCE] batch_process | duration=5000 items=150 throughput=30
# JSON
{"category":"PERFORMANCE","operation":"batch_process","duration_ms":5000,"items":150,"throughput":30}
Related Documentationโ
Logging System Overviewโ
- Logging Overview - Introduction to Brobot's transparent, configuration-driven logging system
- Logging Configuration Guide - Comprehensive configuration options for output formats and enrichment
- Logging Usage Guide - How to use custom logging with ActionConfig methods
- Logging Performance Guide - Performance impact and optimization strategies for different output formats
Configuration & Propertiesโ
- Properties Reference - Complete reference for all
brobot.logging.output.*properties - BrobotProperties Usage Guide - How to access logging properties programmatically
- Auto-Configuration Guide - Spring Boot auto-configuration of logging system
- Headless Configuration - Output format considerations in headless environments
ActionConfig & Custom Loggingโ
- ActionConfig Overview - ActionConfig logging methods (withBeforeActionLog, withSuccessLog, withFailureLog)
- ActionConfig Examples - Practical examples of ActionConfig with custom logging messages
- Convenience Methods - Automatic logging via action convenience methods
Testing & Debuggingโ
- Testing Introduction - Testing approaches and output format recommendations for test environments
- Mock Mode Guide - Using output formats in mock mode testing
- Profile-Based Testing - Configure output formats per test profile
- Image Find Debugging - Comprehensive debugging system using AnsiColor visual symbols
Getting Startedโ
- Quick Start Guide - Getting started with Brobot logging
- Installation Guide - Installing Brobot with Jansi library for ANSI color support
Integration & Advancedโ
- Integrations Overview - Using JSON output format with integration platforms and monitoring tools
External Referencesโ
- Jansi Library - ANSI color library providing Windows support
- SLF4J Documentation - Logging facade used by Brobot
- Logback Documentation - Logging implementation configuration
- Spring Boot Logging - Spring Boot logging framework reference