loghawk_claude.xml

<?xml version="1.0" encoding="UTF-8"?>
<loghawk-integration>
  <description>
    <purpose>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.</purpose>
    <use-cases>Debug applications, monitor systems, analyze user behavior, and identify issues across full-stack applications.</use-cases>
    <key-capabilities>Multi-technology filtering, regex pattern matching, preset configurations, persistent path management, browser log capture integration.</key-capabilities>
  </description>

  <connection>
    <http-endpoint recommended="true">http://127.0.0.1:8765</http-endpoint>
    <https-endpoint warning="WebFetch rejects self-signed certs">https://127.0.0.1:8766</https-endpoint>
    <recommended-method>Always use curl due to WebFetch SSL compatibility issues</recommended-method>
    <example>curl "http://127.0.0.1:8765/api/logs"</example>
  </connection>

  <essential-workflow>
    <step number="1" priority="critical">
      <description>Check current paths FIRST (paths may be user-configured)</description>
      <command>curl "http://127.0.0.1:8765/api/paths"</command>
    </step>
    <step number="2" priority="default">
      <description>Use current paths by default (only change if user specifies different directories)</description>
      <command>curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web"</command>
    </step>
    <step number="3" priority="conditional">
      <description>Update paths only when user requests different directories</description>
      <command>curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./user_specified_path"</command>
    </step>
  </essential-workflow>

  <endpoints>
    <path-management>
      <endpoint method="GET" path="/api/paths" description="Check current backend/frontend paths"/>
      <endpoint method="POST" path="/api/paths" description="Update paths (JSON or form data)"/>
    </path-management>
    <log-analysis description="Uses configured paths">
      <endpoint method="GET" path="/api/logs" description="Both backend &amp; frontend logs"/>
      <endpoint method="GET" path="/api/logs/backend" description="Backend only"/>
      <endpoint method="GET" path="/api/logs/frontend" description="Frontend only"/>
      <endpoint method="GET" path="/api/browse" description="Browse directories" example="?path=./logs"/>
    </log-analysis>
  </endpoints>

  <parameters>
    <categories>core_levels, user_interactions, frontend_react, backend_python, backend_java, backend_nodejs, backend_other, infrastructure</categories>
    <presets>debug_user_clicks, react_debugging, api_testing, full_stack_web, infrastructure_monitoring</presets>
    <custom-keywords format="comma-separated">error,timeout,failed</custom-keywords>
    <use-regex>true for pattern matching</use-regex>
    <max-files default="3">increase for broader search</max-files>
    <max-lines default="1000">0 for unlimited</max-lines>
  </parameters>

  <examples>
    <technology-debugging>
      <react-frontend>curl "http://127.0.0.1:8765/api/logs?categories=frontend_react,user_interactions&amp;max_lines=2000"</react-frontend>
      <python-backend>curl "http://127.0.0.1:8765/api/logs/backend?categories=backend_python,core_levels"</python-backend>
    </technology-debugging>
    
    <preset-usage>
      <react-debugging>curl "http://127.0.0.1:8765/api/logs?preset=react_debugging"</react-debugging>
      <full-stack-unlimited>curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web&amp;max_lines=0"</full-stack-unlimited>
    </preset-usage>
    
    <pattern-matching>
      <basic-regex>curl "http://127.0.0.1:8765/api/logs?custom_keywords=error.*timeout,failed.*connection&amp;use_regex=true"</basic-regex>
      <complex-patterns>curl "http://127.0.0.1:8765/api/logs?custom_keywords=TypeError.*useState,Exception.*line\s+\d+&amp;use_regex=true"</complex-patterns>
      <multi-technology>curl "http://127.0.0.1:8765/api/logs?categories=frontend_react,backend_python&amp;custom_keywords=Hook.*error|Traceback.*line&amp;use_regex=true"</multi-technology>
      <infrastructure-thresholds>curl "http://127.0.0.1:8765/api/logs?custom_keywords=memory.*([89]\d|100)%,cpu.*([89]\d|100)%&amp;use_regex=true"</infrastructure-thresholds>
      <user-interaction-analysis>curl "http://127.0.0.1:8765/api/logs?custom_keywords=click.*button.*\w+Form,submit.*validation.*failed&amp;use_regex=true"</user-interaction-analysis>
    </pattern-matching>
    
    <multi-environment>
      <switch-to-prod>curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./prod_logs"</switch-to-prod>
      <analyze-prod>curl "http://127.0.0.1:8765/api/logs?preset=infrastructure_monitoring"</analyze-prod>
      <switch-to-dev>curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./dev_logs"</switch-to-dev>
    </multi-environment>
  </examples>

  <response-format>
    <structure>
      <backend-logs>filtered log content with statistics</backend-logs>
      <frontend-logs>filtered log content with statistics</frontend-logs>
      <folders>
        <backend>./current_path</backend>
        <frontend>./current_path</frontend>
      </folders>
      <filters>
        <categories>array of selected categories</categories>
        <preset>preset name if used</preset>
        <use-regex>boolean</use-regex>
      </filters>
      <limits>
        <max-files>number</max-files>
        <max-lines>number</max-lines>
      </limits>
    </structure>
  </response-format>

  <filter-categories total="197+ keywords across 8 categories">
    <core-levels count="11">
      <keywords>FATAL, ERROR, CRITICAL, WARN, WARNING, INFO, DEBUG, TRACE, EMERGENCY, ALERT, NOTICE</keywords>
    </core-levels>
    
    <user-interactions count="74">
      <click-events>click, mousedown, mouseup, dblclick, contextmenu, button, submit, form, input, change, focus, blur, keydown, keyup, keypress, scroll, resize, load, unload</click-events>
      <navigation>popstate, hashchange, beforeunload, pagehide, pageshow, navigation, router, route, navigate, redirect, history.push, location.href, window.location</navigation>
      <form-interactions>form submission, validation, input change, field focus, required field, invalid, valid, pattern mismatch, autocomplete, dropdown, select, checkbox, radio</form-interactions>
      <dom-events>addEventListener, removeEventListener, dispatchEvent, monitorEvents, getEventListeners, mutation observer, intersection observer, resize observer</dom-events>
      <ux-tracking>breadcrumb, user journey, session, page view, rage click, dead click, bounce, engagement, performance, loading, interactive, complete</ux-tracking>
    </user-interactions>
    
    <frontend-react count="40">
      <react-specific>componentDidCatch, Error Boundary, useEffect, useState, useCallback, useMemo, Hook, render, componentDidMount, componentWillUnmount, setState, props, state</react-specific>
      <javascript>TypeError, ReferenceError, SyntaxError, Promise, async, await, catch, throw, undefined, null, NaN, Infinity</javascript>
      <browser-network>NetworkError, CORS, 404, 500, timeout, fetch failed, XMLHttpRequest, AbortError</browser-network>
      <testing>userEvent, fireEvent, screen, getByRole, waitFor, jest, cypress, playwright</testing>
    </frontend-react>
    
    <backend-python count="16">
      <exceptions>Traceback, Exception, ImportError, AttributeError, KeyError, ValueError, TypeError, IndexError, NameError, FileNotFoundError, PermissionError, ConnectionError, TimeoutError</exceptions>
      <frameworks>django, flask, fastapi, sqlalchemy, pandas, numpy</frameworks>
    </backend-python>
    
    <backend-java count="8">
      <exceptions>NullPointerException, SQLException, RuntimeException, ClassNotFoundException, IOException</exceptions>
      <spring-framework>Bean, Autowired, Component, Service, Repository, Controller, SpringBoot, Hibernate</spring-framework>
    </backend-java>
    
    <backend-nodejs count="10">
      <nodejs-errors>ECONNREFUSED, ENOTFOUND, EADDRINUSE, EACCES, UnhandledPromiseRejection, process.exit</nodejs-errors>
      <frameworks>express, koa, nest, mongodb, mysql, redis, npm, yarn</frameworks>
    </backend-nodejs>
    
    <backend-other count="11">
      <csharp-dotnet>ArgumentException, InvalidOperationException, HttpRequestException, NullReferenceException</csharp-dotnet>
      <php-laravel>ParseError, FatalError, Notice, Artisan, Eloquent, Blade</php-laravel>
      <go>panic, defer, goroutine, channel closed, nil pointer</go>
    </backend-other>
    
    <infrastructure count="27">
      <database>slow query, connection timeout, deadlock, constraint violation, duplicate key, index, transaction, rollback, commit</database>
      <docker-kubernetes>container, image, volume, network, exit code, pod, service, deployment, crash, OOMKilled, ImagePullBackOff, CrashLoopBackOff</docker-kubernetes>
      <redis-cache>MISCONF, connection refused, memory usage, cache miss, cache hit</redis-cache>
      <general>load balancer, proxy, ssl, certificate, dns, firewall</general>
    </infrastructure>
  </filter-categories>

  <troubleshooting>
    <connection-issues>
      <problem>Connection refused</problem>
      <solution>Start server with `python run_loghawk.py`</solution>
    </connection-issues>
    <no-logs>
      <problem>No logs found</problem>
      <solution>Check paths with `curl "http://127.0.0.1:8765/api/paths"`</solution>
    </no-logs>
    <wrong-paths>
      <problem>Wrong paths configured</problem>
      <solution>Update with `curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./correct_path"`</solution>
    </wrong-paths>
    <no-matches>
      <problem>No matches found</problem>
      <solution>Try `preset=full_stack_web` or broader categories like `core_levels`</solution>
    </no-matches>
  </troubleshooting>

  <performance-optimization>
    <fast-filtering performance="optimal">
      <strategy>Use presets for optimal performance</strategy>
      <example>preset=react_debugging</example>
      <category-limit>1-2 relevant categories</category-limit>
      <keyword-strategy>Specific keywords over broad patterns</keyword-strategy>
    </fast-filtering>
    
    <medium-performance performance="balanced">
      <regex-complexity>Simple patterns like error.*timeout</regex-complexity>
      <category-usage>2-3 categories maximum</category-usage>
      <file-limits>Moderate limits like max_files=5</file-limits>
    </medium-performance>
    
    <slower-operations performance="comprehensive">
      <complex-regex>Lookaheads and complex patterns</complex-regex>
      <all-categories>Using all 8 technology categories</all-categories>
      <high-limits>max_files=20, max_lines=0 for complete analysis</high-limits>
    </slower-operations>
    
    <optimization-tips>
      <file-management>Default max_files=3 processes most recent files first</file-management>
      <line-limits>Use max_lines=1000 for quick overviews, max_lines=0 for complete analysis</line-limits>
      <technology-efficiency>Use presets instead of manual category combinations</technology-efficiency>
      <regex-performance>Simple patterns faster than complex ones</regex-performance>
      <fallback-behavior>Invalid regex automatically falls back to string matching</fallback-behavior>
    </optimization-tips>
  </performance-optimization>

  <key-behaviors>
    <path-persistence>Paths persist across API calls until changed or server restart</path-persistence>
    <default-paths>./logs for both backend/frontend if not configured</default-paths>
    <file-types>Supports .log, .txt, .json files</file-types>
    <sorting>Most recent files first, up to max_files limit</sorting>
    <regex-default>Regex option now selected by default in web interface</regex-default>
  </key-behaviors>
</loghawk-integration>