Stop Drowning in Logs: Analyze Log Durations Easily with DuckTrace

Tired of manually sifting through endless log files to pinpoint performance bottlenecks? Introducing DuckTrace, a simple, open-source Go tool designed to automatically analyze log file durations, identify specific events, and calculate their timing. Say goodbye to tedious manual calculations and hello to clear, color-coded insights.

Why Choose DuckTrace for Log Analysis?

• Save Time: Automate log parsing and duration calculation, freeing up valuable development time.
• Gain Clarity: Visualize event durations in a colorful, scannable format, making it easy to identify performance issues.
• Customize to Your Needs: Adapt to any log format using regular expressions and track user-defined significant events.

Meet Dax: Your Log Detective

Imagine a world where a dedicated detective wades through your logs, pulling out the crucial events and timing them for you. That's DuckTrace! Dax, the Detective Duck, quickly pinpoints the start and end of events, providing precise durations without the guesswork.

The Problem DuckTrace Solves: Taming the Log Jungle

Logs are often a chaotic mix of timestamps, levels, and messages. Manually determining the duration of processes within those logs is a time-consuming headache. Existing tools often fall short, being too complex or lacking the specific focus on event timing. DuckTrace was created from the ground up to solve these problems:

• Support for Any Log Format: Use regex to parse even the most custom log structures.
• User-Defined Event Tracking: Focus on the specific events that matter to your application (e.g., "backup start" to "backup end").
• Clear, Concise Output: View durations in a color-coded format for quick identification of issues.

How DuckTrace Works: A Step-by-Step Guide

DuckTrace streamlines log analysis with a simple yet effective process:

1. Configuration: You provide a log file and a TOML config file specifying your log format and the events to track.
2. Parsing: DuckTrace parses the log file using your defined regex pattern, extracting relevant data.
3. Matching: Start and end events are paired based on the regexes defined in your configuration.
4. Timing: Durations between the matched start and end events are calculated.
5. Output: A color-coded summary is displayed, showing per-event durations and overall averages, ready for immediate analysis.

Getting Started: Installing and Running DuckTrace

Setting up DuckTrace is straightforward:

1. Prerequisites: Ensure you have Go 1.20 or newer installed.

2. Clone the Repository:

   git clone https://github.com/shrsv/ducktrace.git
   cd ducktrace
   

   Copy

3. Install Dependencies:

   go mod tidy
   

   Copy

4. Build the Tool:

   go build -o ducktrace ducktrace.go
   

   Copy

5. Run DuckTrace:

   ./ducktrace --config config.toml --log sample.log
   

   Copy

Configuring DuckTrace: Unleashing its Power

The config.toml file is the key to tailoring DuckTrace to your specific needs. It’s divided into two main sections: LogFormat and Events.

Example config.toml:

log_level = "debug"

[LogFormat]
  pattern = '^(?P<date>\d{4}-\d{2}-\d{2}) (?P<time>\d{2}:\d{2}:\d{2}) \[(?P<level>\w+)\] (?P<message>.*)$'

[Events.backup]
  start_regex = 'Backup job triggered'
  end_regex = 'Backup job completed'

[Events.backup_nightly]
  start_regex = 'Nightly .* started'
  end_regex = 'Nightly .* completed'

[Events.error_rollback]
  start_regex = 'Deployment failed'
  end_regex = 'Rollback completed'

• log_level: Set to "debug" for verbose output and detailed troubleshooting.
• [LogFormat].pattern: Define the regular expression used to parse your log lines. Crucially, use named capture groups (e.g., (?P<date>\d{4}-\d{2}-\d{2})) for date, time, level, and message.
• [Events.<name>]: Define the events you want to track. Each event requires a start_regex and an end_regex to identify the beginning and end of the event.

Tip: Use a tool like regex101.com to test and refine your regular expressions.

Real-World Examples: Putting DuckTrace to Work

Let’s explore how DuckTrace can be used in different scenarios.

Analyzing a Backup Log:

• backup.log:

  2025-04-25 10:00:00 [INFO] Backup job triggered
  2025-04-25 10:00:05 [INFO] Backup job completed
  2025-04-25 22:00:00 [INFO] Nightly backup started
  2025-04-25 22:00:10 [INFO] Nightly backup completed
  

• Run:

  ./ducktrace --config config.toml --log backup.log
  

  Copy

Handling Complex Logs (e.g., Deployment Pipelines):

• deploy.log:

  2025-04-25 09:00:00 [ERROR] Deployment failed for app v1.2.3
  2025-04-25 09:00:10 [INFO] Rollback completed for app v1.2.3
  2025-04-25 10:00:00 [ERROR] Deployment failed for app v1.2.4
  2025-04-25 10:00:15 [INFO] Rollback completed for app v1.2.4
  

• Updated config.toml:

  log_level = "debug"
  
  [LogFormat]
      pattern = '^(?P<date>\d{4}-\d{2}-\d{2}) (?P<time>\d{2}:\d{2}:\d{2}) \[(?P<level>\w+)\] (?P<message>.*)$'
  
  [Events.rollback]
      start_regex = 'Deployment failed for app'
      end_regex = 'Rollback completed for app'
  

  Copy

• Run:

  ./ducktrace --config config.toml --log deploy.log
  

  Copy

  Important: Notice how the regexes match across different app versions! DuckTrace intelligently pairs each "Deployment failed" with the next "Rollback completed."

Extending DuckTrace: Make it Your Own

DuckTrace is designed to be extensible. You can easily adapt it to new scenarios by:

• Adding New Events: Simply create new [Events.<name>] sections in your config.toml.
• Tweaking Regexes: Adjust the start_regex and end_regex to precisely match your log entries.
• Changing Log Formats: Modify the [LogFormat].pattern to accommodate different log structures.

Example: Tracking Database Migrations:

To track database migrations, add the following to your config.toml:

[Events.migration]
    start_regex = 'Starting migration for table'
    end_regex = 'Completed migration for table'

Limitations and Future Development

DuckTrace, while powerful, has some limitations:

• Single-Line Logs: Currently, it assumes each event occurs on a single line.
• Basic Pairing: It matches a start event with the next end event, which may not be suitable for nested events.
• Static Analysis: It processes log files, not live log streams.

Future development plans include:

• Multi-line log support.
• More advanced event pairing logic.
• Live log monitoring with a --watch mode.

Dive In: Get Started with DuckTrace Today!

DuckTrace simplifies the often-challenging task of log analysis, offering a practical solution for identifying and addressing performance bottlenecks. Clone the repository, tweak the configuration, and see how it fits your specific logging needs.

Share your feedback and suggestions on the GitHub Issues page – your input helps shape the future of DuckTrace!