• What This Skill Does - Intelligent OpenTelemetry log analysis with trace reconstruction
• When to Use This Skill - Trigger phrases and common scenarios
• Quick Start - Most common usage for quick health checks
• Analysis Workflow - Complete step-by-step implementation guide
  • Step 1: Determine User's Need - Identify analysis type (health check, error investigation, trace debugging)
  • Step 2: Choose Analysis Mode - 6 modes: Summary, Error Detail, Trace Analysis, File Filter, Fast Parsing, Real-Time
  • Step 3: Execute Analysis - Running commands with Bash tool
  • Step 4: Interpret Results - Understanding summary tables, detailed output, AI analysis
  • Step 5: Report Findings - Communicating results to users
• Command Reference - All analyzer commands with examples
  • Basic Commands (summary, markdown, JSON)
  • Filtering Commands (--error-id, --trace, --file)
  • Performance Commands (--no-ai, --output, tail)
• Understanding the Output - Log format, summary tables, trace execution
• Best Practices - 7 essential practices for effective log analysis
• Common Scenarios - Real-world examples with commands
• Integration with CLAUDE.md - How this skill implements CLAUDE.md conventions

• Troubleshooting - Common issues and fixes
• Advanced Usage - Custom scripts, programmatic access, budget tracking
• Expected Outcomes - Success criteria and common results
• Requirements - Tools, files, dependencies, verification

• Technical Reference - OpenTelemetry format, data models, parsing logic, AI configuration
• Response Templates - 8 response templates for different contexts
• Related Documentation - Tool implementation, usage examples, LangChain client
• Quick Reference Card - One-line command cheatsheet

• Parse OpenTelemetry-formatted logs with trace/span IDs
• Reconstruct complete execution traces
• Extract errors with full call chain context
• AI-powered root cause analysis
• Multiple output formats (summary, markdown, JSON)
• Advanced filtering (by error ID, trace ID, file)

• "check the logs"
• "look at the logs"
• "analyze errors"
• "what's failing?"
• "debug this issue"
• "show me the traces"
• "investigate the error"
• "view log file"
• Any mention of project log files ({{LOG_DIR}}/{{LOG_FILE}}.log)

• User asks: "Are there any errors?" or "What's happening in the logs?"
• Action: Run summary mode (default)

• User mentions specific error or asks for details
• Action: Get error ID from summary, then use --error-id

• User asks "what led to this error?" or wants execution flow
• Action: Use --trace with trace ID

• User mentions specific file or module
• Action: Use --file filter

• User wants to watch logs as they happen
• Action: Use tail -f

python3 .claude/tools/utils/log_analyzer.py {{LOG_DIR}}/{{LOG_FILE}}.log

• Initial investigation
• Quick health check
• Getting error IDs for deeper analysis
• User asks "what errors do we have?"

python3 .claude/tools/utils/log_analyzer.py --error-id 1 --format markdown

• User asks about specific error from summary
• Need full error message (summary truncates)
• Want to see complete stack trace
• Investigating single failure

python3 .claude/tools/utils/log_analyzer.py --trace TRACE_ID --format markdown

• Multiple related errors in same trace
• Need to understand execution sequence
• Debugging distributed operations
• User asks "what happened in this execution?"

python3 .claude/tools/utils/log_analyzer.py --file database.py --format markdown

• User mentions specific file
• Investigating module-specific issues
• Finding patterns in one component

python3 .claude/tools/utils/log_analyzer.py --no-ai

• Quick checks during development
• Want to avoid LLM costs
• Just need parsed errors without analysis
• Automated scripts or frequent polling

tail -f {{LOG_DIR}}/{{LOG_FILE}}.log

• Watching logs during testing
• Monitoring server startup
• Debugging in real-time
• User runs operations and wants to see results

1. Check "Total errors" count
2. Scan error table for patterns (same file, same trace)
3. Note error IDs for deeper investigation
4. Use provided Quick Commands to drill down

1. Read Full Message (not truncated)
2. Review Call Chain (execution flow leading to error)
3. Check Related Errors (other failures in same trace)
4. Examine Stack Trace (if available)
5. Look for Recovery Attempts (logs after error)

1. Read Root Causes section
2. Check Patterns (recurring issues)
3. Review Priority (what to fix first)
4. Follow Fixes (specific file:line changes)
5. Consider Systemic Issues (larger architectural problems)

1. Summary of error count and severity
2. Most critical issues (from AI analysis or your judgment)
3. Specific file:line references for user to investigate
4. Suggested next steps or commands to run

Found 5 errors in the logs:

Critical Issues:
1. Neo4j connection failure in database.py:123 (trace: abc123)
   - Appears 3 times across different operations
   - Root cause: Connection timeout after 5s

2. Invalid config in settings.py:45 (trace: def456)
   - Missing required parameter 'api_key'

To investigate further:
- View error 1 details: python3 .claude/tools/utils/log_analyzer.py --error-id 1 --format markdown
- See all Neo4j errors: python3 .claude/tools/utils/log_analyzer.py --file database.py --format markdown

2025-10-16 14:32:15 - [trace:abc123 | span:def456] - module.name - ERROR - [file.py:123] - function() - Error message

• timestamp: When the log occurred
• trace: Unique ID for entire execution (groups related logs)
• span: Unique ID for operation within trace
• module: Python module path
• level: ERROR, WARNING, INFO, DEBUG
• file:line: Source location
• function: Function name
• message: Log message

ID   | Trace      | File:Line              | Function    | Message
-----|------------|------------------------|-------------|------------------
1    | abc123     | database.py:45         | connect     | Connection failed
2    | abc123     | database.py:67         | query       | No active connection

• ID: Error number (use with --error-id)
• Trace: First 8 chars of trace ID (same trace = related errors)
• File:Line: Where error occurred
• Function: Function that logged error
• Message: Preview (truncated, use --error-id for full message)

• Starts at entry point (e.g., MCP tool call)
• Includes all operations in that execution
• Ends when execution completes
• Multiple errors in same trace are related

Trace abc123:
  1. automatic_indexing() [deprecated] called
  2. connect_to_neo4j() called
  3. ERROR: Connection timeout
  4. retry_connection() called
  5. ERROR: Retry failed

abc123

1. Run summary to see current state
2. Identify error patterns
3. Then make code changes
4. Re-run summary to verify fix

When users say "Logs", analyze

{{LOG_DIR}}/{{LOG_FILE}}.log

from your project

1. Automatic log file location
2. Multiple analysis modes
3. AI-powered diagnosis
4. Trace reconstruction
5. Interactive debugging workflow

1. User says "Logs" → Run this skill
2. Start with summary mode
3. Identify critical errors
4. Drill down with --error-id or --trace
5. Report findings with file:line references

• <5 second analysis time - Fast log parsing and error extraction
• 100% trace reconstruction - All related errors grouped by trace
• 90% root cause accuracy - AI-powered diagnosis with high confidence
• Markdown/JSON export - Automated report generation
• Zero manual log parsing - Automated OpenTelemetry parsing

• Parse logs manually with grep/sed (use analyzer tool)
• Ignore trace IDs (they group related errors)
• Look at single error in isolation (check full trace)
• Skip AI analysis when investigating production issues
• Assume errors are unrelated (verify with trace grouping)
• Make changes without seeing actual log output

• Always start with summary mode
• Use error IDs for detailed investigation
• Group errors by trace ID
• Use --no-ai for quick checks, AI for production debugging
• Generate markdown reports for documentation
• Combine with real-time monitoring (tail -f)

1. Basic log analysis with default settings and LangChain client
2. Custom LLM client with budget tracking (monthly/daily limits)
3. Parsing only (no LLM) - faster, free error extraction
4. Filtering specific errors - finding Neo4j-related issues
5. Trace-based analysis - grouping errors by execution trace

undefined

• Python 3.12+ (already in project)
• Log analyzer tool:

  .claude/tools/utils/log_analyzer.py

  (bundled)
• LangChain client:

  .claude/tools/langchain_client.py

  (bundled)

• Default location:

  {{LOG_DIR}}/{{LOG_FILE}}.log

  (customize for your project)
• Generated by running your project's server startup script (e.g.,

  ./run-server.sh

  )

• Standard library modules (no additional installation needed)
• LangChain client uses project's existing dependencies

undefined

• references/reference.md - Technical documentation:
  • OpenTelemetry log format specification
  • Data models (LogEntry, TraceExecution, ErrorContext)
  • Parsing logic and trace reconstruction algorithm
  • AI analysis configuration and cost tracking
  • Performance characteristics and scaling limits
• references/log-rotation-guide.md - Log rotation configuration and management
• references/log-rotation-analysis.md - Log rotation analysis and patterns
• references/logging-and-rotation-guide.md - Complete logging and rotation guide
• templates/response-template.md - Response formatting:
  • 8 response templates for different contexts
  • Summary, detailed error, trace analysis, file-specific
  • AI-powered pattern analysis, real-time monitoring
  • No errors found, before/after comparison

• No errors found: "✓ HEALTHY - Analyzed 1,234 entries, no errors found"
• Configuration issues: Clear error with fix steps (e.g., "Start Neo4j:

  neo4j start

  ")
• Test failures: Trace showing execution flow to failure with root cause
• Production issues: AI analysis with priority ranking and systemic issues

• Tool implementation:

  .claude/tools/utils/log_analyzer.py

• Usage examples:

  .claude/tools/utils/example_usage.py

• LangChain client:

  .claude/tools/langchain_client.py

• CLAUDE.md conventions:

  CLAUDE.md

  (section on "Logs")
• Log file location:

  {{LOG_DIR}}/{{LOG_FILE}}.log