drtrace 0.2.0 → 0.4.0

package/agents/daemon-method-selection.md

@@ -0,0 +1,370 @@
+# Daemon Method Selection Guide
+
+**Purpose**: Guide for AI agents to choose the right method for daemon interaction.
+
+**Key Principle**: For AI agents, prefer **HTTP/curl first** (simpler, no dependencies), then Python, then CLI.
+
+---
+
+## Priority Order for AI Agents
+
+| Priority | Method | When to Use |
+|----------|--------|-------------|
+| **1st** | HTTP/curl | Default - works without dependencies |
+| **2nd** | Python code | When rich SDK features needed |
+| **3rd** | CLI commands | Last resort - requires subprocess |
+
+### Why HTTP-First for AI Agents?
+
+- **No dependencies**: Just HTTP requests - works in any environment
+- **Simpler**: curl commands are self-contained and portable
+- **Faster**: No import overhead or Python interpreter startup
+- **Universal**: Works from any language or tool
+
+---
+
+## Discovery First: OpenAPI Schema
+
+**CRITICAL**: Before making any API call, fetch `/openapi.json` to discover:
+- Available endpoints
+- Correct field names (e.g., `ts` not `timestamp`)
+- Request/response schemas
+
+```bash
+# Always fetch schema first
+curl http://localhost:8001/openapi.json
+```
+
+```python
+import requests
+
+base_url = "http://localhost:8001"
+
+# Fetch schema to discover endpoints and field names
+schema = requests.get(f"{base_url}/openapi.json", timeout=5).json()
+paths = schema.get("paths", {})
+components = schema.get("components", {}).get("schemas", {})
+
+# Use discovered field names, not hardcoded ones
+```
+
+**Why this matters**: API field names can change between versions. Using OpenAPI ensures compatibility.
+
+---
+
+## Method 1: HTTP/curl (Preferred)
+
+### Check Daemon Status
+
+```bash
+curl http://localhost:8001/status
+```
+
+### Query Logs
+
+```bash
+# Get logs from last 5 minutes
+START_TS=$(python3 -c "import time; print(time.time() - 300)")
+END_TS=$(python3 -c "import time; print(time.time())")
+
+curl "http://localhost:8001/logs/query?start_ts=${START_TS}&end_ts=${END_TS}&application_id=myapp&limit=100"
+```
+
+### Root Cause Analysis
+
+```bash
+curl "http://localhost:8001/analysis/why?application_id=myapp&start_ts=${START_TS}&end_ts=${END_TS}&min_level=ERROR"
+```
+
+### Python requests (HTTP method)
+
+```python
+import requests
+import time
+
+base_url = "http://localhost:8001"
+
+# Step 1: Check daemon status
+try:
+    status = requests.get(f"{base_url}/status", timeout=2)
+    if status.status_code != 200:
+        print("Daemon not available")
+except requests.exceptions.RequestException:
+    print("Daemon not reachable")
+
+# Step 2: Query logs
+now = time.time()
+params = {
+    "start_ts": now - 300,  # 5 minutes ago
+    "end_ts": now,
+    "application_id": "myapp",
+    "limit": 100
+}
+response = requests.get(f"{base_url}/logs/query", params=params, timeout=10)
+logs = response.json().get("results", [])
+
+# Step 3: Process using field names from OpenAPI schema
+for log in logs:
+    ts = log.get("ts")  # Use 'ts' not 'timestamp' (from schema)
+    level = log.get("level")
+    message = log.get("message")
+```
+
+---
+
+## Method 2: Python Code (Fallback)
+
+Use when you need rich SDK features or the HTTP method fails.
+
+### Log Analysis
+
+```python
+from drtrace_service.agent_interface import process_agent_query, check_daemon_status
+import asyncio
+
+# Check daemon first
+status = await check_daemon_status()
+if not status.get("available"):
+    print("Daemon not available")
+
+# Process query - returns formatted markdown
+response = await process_agent_query("explain error from 9:00 to 10:00 for app myapp")
+print(response)
+
+# Non-async context
+response = asyncio.run(process_agent_query("show logs from last 5 minutes"))
+```
+
+### Setup Help
+
+```python
+from drtrace_service.help_agent_interface import (
+    start_setup_guide,
+    get_current_step,
+    complete_step,
+    troubleshoot,
+)
+from pathlib import Path
+import asyncio
+
+project_root = Path(".")
+
+# Start setup guide
+guide = await start_setup_guide(language="python", project_root=project_root)
+
+# Get current step
+current = await get_current_step(project_root=project_root)
+
+# Mark step complete
+next_step = await complete_step(step_number=1, project_root=project_root)
+
+# Troubleshoot
+help_text = await troubleshoot("daemon not connecting", project_root=project_root)
+```
+
+### Setup Suggestions
+
+```python
+from drtrace_service.setup_agent_interface import analyze_and_suggest, suggest_for_language
+from pathlib import Path
+import asyncio
+
+project_root = Path(".")
+
+# Get setup suggestions
+suggestions = await analyze_and_suggest(project_root)
+
+# Language-specific suggestions
+python_suggestions = await suggest_for_language("python", project_root)
+cpp_suggestions = await suggest_for_language("cpp", project_root)
+```
+
+---
+
+## Method 3: CLI Commands (Last Resort)
+
+Use only when HTTP and Python methods are unavailable.
+
+### Check Status
+
+```bash
+python -m drtrace_service status
+```
+
+### Analyze Errors
+
+```bash
+python -m drtrace_service why --application-id myapp --since 5m --min-level ERROR
+```
+
+### Setup Help
+
+```bash
+python -m drtrace_service help guide start --language python --project-root /path/to/project
+python -m drtrace_service help guide current --project-root /path/to/project
+```
+
+---
+
+## Error Handling and Fallback Chain
+
+```python
+import requests
+
+def interact_with_daemon(query: str) -> str:
+    """Try methods in order: HTTP -> Python -> CLI"""
+    base_url = "http://localhost:8001"
+
+    # Method 1: HTTP (Preferred)
+    try:
+        # Check status first
+        status = requests.get(f"{base_url}/status", timeout=2)
+        if status.status_code == 200:
+            # Make actual request...
+            return "Success via HTTP"
+    except requests.exceptions.RequestException:
+        pass  # Fall through to Python
+
+    # Method 2: Python (Fallback)
+    try:
+        from drtrace_service.agent_interface import process_agent_query
+        import asyncio
+        response = asyncio.run(process_agent_query(query))
+        return response
+    except ImportError:
+        pass  # Fall through to CLI
+
+    # Method 3: CLI (Last Resort)
+    import subprocess
+    result = subprocess.run(
+        ["python", "-m", "drtrace_service", "status"],
+        capture_output=True,
+        text=True
+    )
+    if result.returncode == 0:
+        return result.stdout
+
+    # All methods failed
+    return """
+    Daemon is not available.
+
+    Next Steps:
+    1. Start daemon: python -m drtrace_service
+    2. Verify: curl http://localhost:8001/status
+    """
+```
+
+---
+
+## When to Use Each Method
+
+| Scenario | Recommended Method |
+|----------|-------------------|
+| Simple queries (status, logs) | HTTP/curl |
+| Complex analysis | HTTP or Python |
+| Rich markdown output needed | Python SDK |
+| Running outside Python | HTTP/curl |
+| Setup guide interaction | Python SDK |
+| Debugging integration | CLI commands |
+| Script automation | HTTP/curl |
+
+---
+
+## Quick Reference: Common Endpoints
+
+**Note**: Always verify via `/openapi.json` - this list is for reference only.
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/status` | GET | Health check |
+| `/openapi.json` | GET | API schema |
+| `/logs/query` | GET | Query logs |
+| `/logs/ingest` | POST | Ingest logs |
+| `/analysis/why` | GET | Root cause analysis |
+| `/analysis/time-range` | GET | Time range analysis |
+| `/help/guide/start` | POST | Start setup guide |
+| `/help/guide/current` | GET | Current setup step |
+| `/help/troubleshoot` | POST | Troubleshooting help |
+
+---
+
+## Important: Timestamps Are UTC
+
+All timestamps in DrTrace API are **UTC Unix timestamps**:
+
+| Field/Param | Format | Timezone |
+|-------------|--------|----------|
+| `ts` (in logs) | Unix float | UTC |
+| `start_ts`, `end_ts` | Unix float | UTC |
+| `since`, `until` | Relative or ISO 8601 | UTC |
+
+**Key Rules**:
+- ISO 8601 without timezone (e.g., `2025-12-31T02:44:03`) is interpreted as **UTC**, not local time
+- Relative times (`5m`, `1h`) are relative to server's current UTC time
+- To query with local time, include timezone offset: `2025-12-31T09:44:03+07:00`
+
+### Converting Local Time to UTC
+
+**Python:**
+```python
+from datetime import datetime, timezone, timedelta
+
+# Local time (e.g., 2025-12-31 09:44:03 in GMT+7)
+local_time = datetime(2025, 12, 31, 9, 44, 3)
+
+# Method 1: If you know your timezone offset
+local_tz = timezone(timedelta(hours=7))  # GMT+7
+local_aware = local_time.replace(tzinfo=local_tz)
+utc_time = local_aware.astimezone(timezone.utc)
+unix_ts = utc_time.timestamp()
+print(f"UTC Unix timestamp: {unix_ts}")
+
+# Method 2: Using system timezone
+import time
+unix_ts = time.mktime(local_time.timetuple())
+```
+
+**Bash:**
+```bash
+# Convert local time to Unix timestamp
+date -d "2025-12-31 09:44:03" +%s
+
+# Convert with explicit timezone
+TZ=UTC date -d "2025-12-31T02:44:03" +%s
+```
+
+### API Query Examples with Timezone
+
+```bash
+# Option 1: Include timezone in ISO 8601 (recommended for local time)
+curl "http://localhost:8001/logs/query?since=2025-12-31T09:44:03%2B07:00"
+
+# Option 2: Use relative time (always relative to server UTC time)
+curl "http://localhost:8001/logs/query?since=5m"
+
+# Option 3: Convert to UTC Unix timestamp first
+UTC_TS=$(TZ=UTC date -d "2025-12-31T02:44:03" +%s)
+curl "http://localhost:8001/logs/query?start_ts=$UTC_TS"
+
+# Option 4: Use ISO 8601 in UTC (note: no timezone = UTC)
+curl "http://localhost:8001/logs/query?since=2025-12-31T02:44:03"
+```
+
+### Common Timezone Pitfalls
+
+1. **ISO 8601 Without Timezone**: Interpreted as UTC, not local time. If you pass `2025-12-31T09:44:03` thinking it's local 9:44 AM, it will be treated as 9:44 AM UTC.
+
+2. **Server vs Client Timezone**: If your server is in a different timezone than your client, always use explicit UTC timestamps or include timezone offsets.
+
+3. **Relative Times**: `since=5m` means 5 minutes before server's current UTC time, regardless of your local timezone.
+
+---
+
+## Related Documentation
+
+- `docs/daemon-interaction-guide.md` - OpenAPI discovery details
+- `docs/api-reference.md` - Complete API reference
+
+---
+
+**Last Updated**: 2025-12-31

package/agents/integration-guides/cpp-best-practices.md

@@ -0,0 +1,218 @@
+# C++ DrTrace Best Practices
+
+This guide provides best practices for configuring DrTrace in C++ applications.
+
+## Crash-Safe Logging
+
+For applications where crash logs are critical (robotics, autonomous systems, safety-critical software):
+
+### Configuration Options
+
+| Configuration | Crash Safety | Network Overhead | Use Case |
+|---------------|--------------|------------------|----------|
+| `batch_size=1` | Highest | Highest | Safety-critical systems |
+| `batch_size=5`, `flush=1s` | Medium | Medium | Important crash debugging |
+| `batch_size=10`, `flush=5s` (default) | Lower | Lowest | General applications |
+
+### Example: Safety-Critical Configuration
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// For safety-critical applications: immediate send
+config.batch_size = 1;  // Each log sent immediately
+```
+
+### Example: Balanced Configuration
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// Balanced approach
+config.batch_size = 5;
+config.flush_interval = std::chrono::milliseconds(1000);  // 1 second
+```
+
+### Recommendation
+
+For most applications, the default configuration is appropriate. Only reduce batch size if:
+- Crash debugging is a primary concern
+- You're willing to accept higher network overhead
+- The application is safety-critical
+
+**Note:** Signal handlers are inherently unsafe in C++. Rather than implementing partial solutions, we recommend configuring `batch_size=1` for applications where crash logs are critical.
+
+## Log Level Filtering
+
+Filter logs at the client to reduce network overhead in production:
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// Only send WARN and above in production
+config.min_level = drtrace::core::LogLevel::WARN;
+```
+
+Or via environment variable:
+```bash
+export DRTRACE_MIN_LEVEL=warn
+```
+
+### Available Levels
+
+| Level | Value | Description |
+|-------|-------|-------------|
+| DEBUG | 0 | Detailed debugging information |
+| INFO | 1 | General operational messages |
+| WARN | 2 | Warning conditions |
+| ERROR | 3 | Error conditions |
+| CRITICAL | 4 | Critical failures |
+
+## Buffer Size Limits
+
+Prevent memory issues when daemon is unavailable:
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// Limit buffer to 10000 logs (drop oldest when full)
+config.max_buffer_size = 10000;
+```
+
+Or via environment variable:
+```bash
+export DRTRACE_MAX_BUFFER_SIZE=10000
+```
+
+### Behavior
+
+- When buffer is full, **oldest logs are dropped** to make room for new ones
+- Set to `0` for unlimited buffer (not recommended for production)
+- Default: 10000 logs
+
+### Memory Estimation
+
+Each log record is approximately 200-500 bytes in memory. With default 10000 buffer:
+- Minimum: ~2 MB
+- Maximum: ~5 MB
+
+## Circuit Breaker Behavior
+
+The DrTrace client uses a circuit breaker pattern to maintain consistent performance:
+
+### How It Works
+
+```
+CLOSED (normal) ──[failure]──> OPEN (fast-fail)
+     ^                              │
+     │                    [cooldown expires]
+     │                              v
+     └────[success]───────── HALF-OPEN (probe)
+```
+
+- **CLOSED**: Normal operation, requests go through
+- **OPEN**: After failure, all requests fast-fail (< 1us) for 30 seconds
+- **HALF-OPEN**: After cooldown, one probe request to check recovery
+
+### Configuration
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// Probe every 60 seconds instead of default 30
+config.circuit_reset_interval = std::chrono::milliseconds(60000);
+```
+
+Or via environment variable:
+```bash
+export DRTRACE_CIRCUIT_RESET_MS=60000
+```
+
+### Performance Impact
+
+| Scenario | Network Calls | Latency |
+|----------|---------------|---------|
+| Daemon UP | 1 (normal) | ~10ms |
+| Daemon DOWN (circuit open) | 0 | < 1us |
+| Daemon DOWN (probe) | 1-3 | ~3s |
+
+This ensures your application's logging performance is not affected by daemon availability.
+
+## Configurable Timeouts
+
+Fine-tune network behavior for your environment:
+
+```cpp
+drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+// Increase timeout for slow networks
+config.http_timeout = std::chrono::milliseconds(5000);  // 5 seconds
+
+// Increase backoff for high-latency networks
+config.retry_backoff = std::chrono::milliseconds(500);  // 500ms base
+
+// Reduce retries for faster failure detection
+config.max_retries = 2;
+```
+
+### Environment Variables
+
+```bash
+export DRTRACE_HTTP_TIMEOUT_MS=5000
+export DRTRACE_RETRY_BACKOFF_MS=500
+export DRTRACE_MAX_RETRIES=2
+```
+
+### Defaults
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `http_timeout` | 1000ms | HTTP request timeout |
+| `retry_backoff` | 100ms | Base backoff between retries |
+| `max_retries` | 3 | Maximum retry attempts |
+
+### Retry Behavior
+
+Total worst-case delay = `http_timeout * max_retries + backoff * (1+2+...+(max_retries-1))`
+
+With defaults: `1000*3 + 100*(1+2)` = 3300ms per batch
+
+## Complete Configuration Example
+
+```cpp
+#include "drtrace_sink.hpp"
+
+int main() {
+    // Load from environment with overrides
+    drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+    // Safety-critical application settings
+    config.batch_size = 1;
+    config.min_level = drtrace::core::LogLevel::INFO;
+    config.max_buffer_size = 5000;
+    config.circuit_reset_interval = std::chrono::milliseconds(10000);
+    config.http_timeout = std::chrono::milliseconds(2000);
+    config.max_retries = 2;
+
+    drtrace::DrtraceClient client(config);
+
+    client.info("Application started");
+    // ... application code ...
+
+    return 0;
+}
+```
+
+## Environment Variable Reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DRTRACE_ENABLED` | true | Enable/disable logging |
+| `DRTRACE_DAEMON_URL` | http://localhost:8001/logs/ingest | Daemon endpoint |
+| `DRTRACE_APPLICATION_ID` | my-app | Application identifier |
+| `DRTRACE_MIN_LEVEL` | debug | Minimum log level |
+| `DRTRACE_MAX_BUFFER_SIZE` | 10000 | Maximum buffer size |
+| `DRTRACE_CIRCUIT_RESET_MS` | 30000 | Circuit breaker reset interval |
+| `DRTRACE_HTTP_TIMEOUT_MS` | 1000 | HTTP request timeout |
+| `DRTRACE_RETRY_BACKOFF_MS` | 100 | Base retry backoff |
+| `DRTRACE_MAX_RETRIES` | 3 | Maximum retry attempts |

package/agents/integration-guides/cpp-ros-integration.md

@@ -0,0 +1,88 @@
+# C++ ROS Integration Guide
+
+This guide shows how to integrate DrTrace with ROS (Robot Operating System) projects using Pattern 2 (Direct API).
+
+## Overview
+
+DrTrace Direct API works alongside ROS logging without requiring spdlog. This allows you to:
+- Keep using ROS logging (`ROS_INFO`, `ROS_ERROR`, etc.) for ROS-specific messages
+- Use DrTrace for application-level structured logging
+- No need to add spdlog or create bridges/adapters
+
+## Integration Pattern
+
+**Pattern Used:** Pattern 2 (Direct API - no spdlog required)
+
+### CMake Setup
+
+```cmake
+# Add after cmake_minimum_required and project(...) definition.
+# Header file should already be copied to third_party/drtrace/drtrace_sink.hpp
+
+# Include the third_party/drtrace directory so the header can be found:
+target_include_directories(your_target PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/third_party/drtrace
+)
+
+# spdlog NOT detected - using direct API (no spdlog required):
+# Link required dependencies:
+#   - CURL::libcurl (system dependency - must be installed)
+target_link_libraries(your_target PRIVATE
+    CURL::libcurl
+)
+```
+
+**Note:** No spdlog setup needed - only `CURL::libcurl` is required.
+
+### C++ Code Integration
+
+```cpp
+#include "third_party/drtrace/drtrace_sink.hpp"
+#include <ros/ros.h>
+#include <cstdlib>
+
+int main(int argc, char** argv) {
+    ros::init(argc, argv, "my_ros_node");
+    ros::NodeHandle nh;
+
+    // Load configuration from environment (reads DRTRACE_APPLICATION_ID or _drtrace/config.json)
+    drtrace::DrtraceConfig config = drtrace::DrtraceConfig::from_env();
+
+    // Create DrTrace client (no spdlog required - works alongside ROS logging)
+    drtrace::DrtraceClient drtrace_client(config, "my_ros_node");
+
+    // Use ROS logging for ROS-specific messages
+    ROS_INFO("ROS node starting");
+    ROS_DEBUG("Debug information");
+
+    // Use DrTrace client for application-level logging
+    drtrace_client.info("Application starting with DrTrace");
+    drtrace_client.error("Error occurred", __FILE__, __LINE__);
+
+    // Both logging systems work independently
+    ros::spin();
+    return 0;
+}
+```
+
+## Key Points
+
+1. **No spdlog required**: DrTrace Direct API works without spdlog
+2. **Coexistence**: ROS logging and DrTrace logging work side-by-side
+3. **No bridges needed**: No need to create adapters between ROS and spdlog
+4. **Simple setup**: Only requires `CURL::libcurl` in CMake
+
+## Detection
+
+The log-init agent will automatically detect ROS projects by looking for:
+- `#include <ros/ros.h>` in source files
+- ROS logging macros (`ROS_INFO`, `ROS_DEBUG`, `ROS_ERROR`, etc.)
+- `.launch` files in the project
+
+When ROS is detected and spdlog is not found, the agent will suggest Pattern 2 (Direct API).
+
+## Related Documentation
+
+- [C++ Client README](../../packages/cpp/drtrace-client/README.md): Complete C++ client documentation
+- [Log-Init Agent Guide](../../docs/log-init-agent-guide.md): How to use the log-init agent for setup suggestions
+