Skip to content

loghawk_claude.md

Latest commit

 

History

History
213 lines (154 loc) · 9.96 KB

loghawk_claude.md

File metadata and controls

213 lines (154 loc) · 9.96 KB

LogHawk Integration Guide for Claude Code

What is LogHawk?

LogHawk is an intelligent log analysis platform that filters and analyzes logs from multiple technologies (React, Python, Java, Node.js, infrastructure). It reads log files from configured directories and provides smart filtering by error types, user interactions, technology-specific patterns, and custom keywords. Use it to debug applications, monitor systems, analyze user behavior, and identify issues across full-stack applications.

Key capabilities: Multi-technology filtering, regex pattern matching, preset configurations, persistent path management, browser log capture integration.

Connection & Compatibility

  • HTTP: http://127.0.0.1:8765 ✅ Use this - WebFetch has SSL issues
  • HTTPS: https://127.0.0.1:8766 ⚠️ WebFetch rejects self-signed certs

✅ Always use curl: curl "http://127.0.0.1:8765/api/logs"

Essential Workflow

1. Check current paths FIRST (paths may be user-configured):

curl "http://127.0.0.1:8765/api/paths"

2. Use current paths by default (only change if user specifies different directories):

curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web"

3. Update paths only when user requests different directories:

curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./user_specified_path"

Core Endpoints

Path Management

GET  /api/paths                    # Check current backend/frontend paths
POST /api/paths                    # Update paths (JSON or form data)

Log Analysis (uses configured paths)

GET /api/logs                      # Both backend & frontend logs
GET /api/logs/backend              # Backend only  
GET /api/logs/frontend             # Frontend only
GET /api/browse?path=./logs        # Browse directories

Key Parameters

  • categories: core_levels, user_interactions, frontend_react, backend_python, backend_java, backend_nodejs, backend_other, infrastructure
  • preset: debug_user_clicks, react_debugging, api_testing, full_stack_web, infrastructure_monitoring
  • custom_keywords: error,timeout,failed (comma-separated)
  • use_regex: true for pattern matching
  • max_files: 3 (default), increase for broader search
  • max_lines: 1000 (default), 0 for unlimited

Quick Reference Examples

Technology-specific debugging:

curl "http://127.0.0.1:8765/api/logs?categories=frontend_react,user_interactions&max_lines=2000"
curl "http://127.0.0.1:8765/api/logs/backend?categories=backend_python,core_levels"

Using presets:

curl "http://127.0.0.1:8765/api/logs?preset=react_debugging"
curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web&max_lines=0"

Pattern matching:

curl "http://127.0.0.1:8765/api/logs?custom_keywords=error.*timeout,failed.*connection&use_regex=true"

Advanced regex patterns:

# Complex error patterns with context
curl "http://127.0.0.1:8765/api/logs?custom_keywords=TypeError.*useState,Exception.*line\s+\d+&use_regex=true"

# Multi-technology debugging (React + Python errors)
curl "http://127.0.0.1:8765/api/logs?categories=frontend_react,backend_python&custom_keywords=Hook.*error|Traceback.*line&use_regex=true"

# Infrastructure monitoring with thresholds
curl "http://127.0.0.1:8765/api/logs?custom_keywords=memory.*([89]\d|100)%,cpu.*([89]\d|100)%&use_regex=true"

# User interaction analysis
curl "http://127.0.0.1:8765/api/logs?custom_keywords=click.*button.*\w+Form,submit.*validation.*failed&use_regex=true"

Multi-environment workflow:

# Switch to production logs
curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./prod_logs"
curl "http://127.0.0.1:8765/api/logs?preset=infrastructure_monitoring"

# Switch back to dev logs  
curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./dev_logs"

Response Format

{
  "backend_logs": "filtered log content with statistics",
  "frontend_logs": "filtered log content with statistics", 
  "folders": {"backend": "./current_path", "frontend": "./current_path"},
  "filters": {"categories": [...], "preset": "...", "use_regex": false},
  "limits": {"max_files": 3, "max_lines": 1000}
}

Filter Categories & Keywords (Complete Reference - 150+ Keywords)

Core Log Levels (11 keywords)

FATAL, ERROR, CRITICAL, WARN, WARNING, INFO, DEBUG, TRACE, EMERGENCY, ALERT, NOTICE

User Interactions & Events (74 keywords)

Click Events & User Actions: click, mousedown, mouseup, dblclick, contextmenu, button, submit, form, input, change, focus, blur, keydown, keyup, keypress, scroll, resize, load, unload

Navigation & Routing: popstate, hashchange, beforeunload, pagehide, pageshow, navigation, router, route, navigate, redirect, history.push, location.href, window.location

Form Interactions: form submission, validation, input change, field focus, required field, invalid, valid, pattern mismatch, autocomplete, dropdown, select, checkbox, radio

DOM Events & Debugging: addEventListener, removeEventListener, dispatchEvent, monitorEvents, getEventListeners, mutation observer, intersection observer, resize observer

User Experience Tracking: breadcrumb, user journey, session, page view, rage click, dead click, bounce, engagement, performance, loading, interactive, complete

Frontend - React/JS/TS (40 keywords)

React Specific: componentDidCatch, Error Boundary, useEffect, useState, useCallback, useMemo, Hook, render, componentDidMount, componentWillUnmount, setState, props, state

JavaScript/TypeScript: TypeError, ReferenceError, SyntaxError, Promise, async, await, catch, throw, undefined, null, NaN, Infinity

Browser/Network: NetworkError, CORS, 404, 500, timeout, fetch failed, XMLHttpRequest, AbortError

Testing: userEvent, fireEvent, screen, getByRole, waitFor, jest, cypress, playwright

Backend - Python (16 keywords)

Exceptions: Traceback, Exception, ImportError, AttributeError, KeyError, ValueError, TypeError, IndexError, NameError, FileNotFoundError, PermissionError, ConnectionError, TimeoutError

Frameworks: django, flask, fastapi, sqlalchemy, pandas, numpy

Backend - Java/Spring (8 keywords)

Exceptions: NullPointerException, SQLException, RuntimeException, ClassNotFoundException, IOException

Spring Framework: Bean, Autowired, Component, Service, Repository, Controller, SpringBoot, Hibernate

Backend - Node.js (10 keywords)

Node.js Errors: ECONNREFUSED, ENOTFOUND, EADDRINUSE, EACCES, UnhandledPromiseRejection, process.exit

Frameworks: express, koa, nest, mongodb, mysql, redis, npm, yarn

Backend - Other Languages (11 keywords)

C#/.NET: ArgumentException, InvalidOperationException, HttpRequestException, NullReferenceException

PHP/Laravel: ParseError, FatalError, Notice, Artisan, Eloquent, Blade

Go: panic, defer, goroutine, channel closed, nil pointer

Infrastructure & DevOps (27 keywords)

Database: slow query, connection timeout, deadlock, constraint violation, duplicate key, index, transaction, rollback, commit

Docker/Kubernetes: container, image, volume, network, exit code, pod, service, deployment, crash, OOMKilled, ImagePullBackOff, CrashLoopBackOff

Redis/Cache: MISCONF, connection refused, memory usage, cache miss, cache hit

General Infrastructure: load balancer, proxy, ssl, certificate, dns, firewall

Performance Optimization Guide

Filtering Strategy (Performance Impact)

🚀 Fast Filtering:

  • Use presets for optimal performance: preset=react_debugging
  • Limit categories to 1-2 relevant ones: categories=core_levels,backend_python
  • Use specific keywords over broad patterns: custom_keywords=ERROR,Traceback

⚡ Medium Performance:

  • Simple regex patterns: custom_keywords=error.*timeout&use_regex=true
  • Multiple categories: categories=frontend_react,backend_python,user_interactions
  • Moderate file limits: max_files=5

🐌 Slower Operations:

  • Complex regex with lookaheads: custom_keywords=(?=.*error)(?=.*timeout)
  • All categories: categories=core_levels,user_interactions,frontend_react,backend_python,backend_java,backend_nodejs,backend_other,infrastructure
  • High file/line limits: max_files=20&max_lines=0

Optimization Tips

File Management:

  • Default max_files=3 processes most recent files first
  • Use max_lines=1000 for quick overviews, max_lines=0 for complete analysis
  • LogHawk sorts by modification time - recent issues appear first

Technology-Specific Efficiency:

  • React debugging: Use preset=react_debugging instead of manual categories
  • Infrastructure monitoring: Use preset=infrastructure_monitoring for curated keywords
  • Full-stack debugging: Use preset=full_stack_web for balanced performance

Regex Performance:

  • Simple patterns (error.*timeout) are faster than complex ones
  • Case-insensitive string matching is faster than regex for simple keywords
  • LogHawk automatically falls back to string matching for invalid regex patterns

Troubleshooting

Connection: Start server with python run_loghawk.py No logs: Check paths with curl "http://127.0.0.1:8765/api/paths" Wrong paths: Update with curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./correct_path" No matches: Try preset=full_stack_web or broader categories like core_levels

Key Behaviors

  • Path Persistence: Paths persist across API calls until changed or server restart
  • Default Paths: ./logs for both backend/frontend if not configured
  • File Types: Supports .log, .txt, .json files
  • Sorting: Most recent files first, up to max_files limit