debugging

Diagnose host service connectivity and data loading issues using Grafana dashboards and Jaeger traces.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/kpiteira/ktrdr --skill debugging-kpiteira
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debugging
Source: https://github.com/kpiteira/ktrdr/tree/main/.claude/skills/debugging
Command: npx skills add https://github.com/kpiteira/ktrdr --skill debugging-kpiteira

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a structured, prioritized approach to troubleshoot common issues in the KTRDR system, from host service connectivity and data loading to worker registration and async problems, minimizing downtime and frustration.

Core Features & Use Cases

  • Prioritized Diagnostics: Guides you to start with high-level Grafana dashboards, then Jaeger (for operation-specific issues, see observability skill), and finally detailed logs.
  • Common Issue Playbooks: Offers specific checks and fixes for frequent problems like host service failures, environment variable misconfigurations, progress tracking stalls, data loading errors, and worker registration issues.
  • Async/Await Troubleshooting: Helps identify and resolve common pitfalls and errors in asynchronous Python code, ensuring smooth operation of concurrent tasks.
  • Use Case: If a data download operation is failing, use this skill to systematically check IB Gateway status, IB Host Service connectivity, symbol formats, and local data ranges to quickly pinpoint the root cause and apply a fix.

Quick Start

My backtest operation is stuck. Use the debugging skill to help me diagnose why it's not progressing.

Frequently Asked Questions about debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot a stuck backtest or data loading operation?

Troubleshoot stuck operations systematically by checking Grafana dashboards for host service connectivity, verifying Jaeger traces for operation-specific failures, and reviewing logs for environment variable misconfigurations or data loading errors. Start with high-level dashboard health, then drill into service-specific traces and detailed logs to identify root causes like symbol format issues or local data range gaps.

How do I diagnose host service connectivity and worker registration issues?

Diagnose connectivity issues by validating service health in Grafana dashboards, querying Jaeger traces for operation details, and analyzing logs for connection failures. Check environment variables, IB Gateway and IB Host Service status, symbol formats, and worker registration state to pinpoint misconfigurations or network problems causing registration delays.

Can I use Grafana and Jaeger together to debug distributed system issues?

Yes. Grafana provides high-level system health monitoring via dashboards, while Jaeger enables operation-specific tracing across distributed services. Use Grafana first to identify affected areas, then query Jaeger traces for detailed latency and error context, and finally review service logs for configuration or data issues.

What's the best way to resolve async and await errors in Python?

Debug asynchronous Python code by reviewing logs for error messages, checking Jaeger traces for operation timing and failures, and validating environment configuration. Identify common async pitfalls like missing await keywords, race conditions, or timeout issues by correlating trace latency with error logs.

Why is my data download operation failing in a distributed system?

Data download failures stem from host service unavailability, connectivity issues, symbol format mismatches, or misconfigured local data ranges. Use Grafana to check service health, Jaeger to trace the operation path and identify where it stalls, and logs to confirm environment variables, gateway status, and data range settings.

Do I need observability tools like Grafana and Jaeger to use this troubleshooting approach?

Yes. This structured diagnostic workflow requires Grafana dashboards for system health monitoring and Jaeger for operation-level tracing. These tools provide the visibility needed to prioritize issues and isolate root causes across host connectivity, service configuration, and data loading stages.