drtrace 0.3.0 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ This runs an interactive setup wizard that creates the `_drtrace/` configuration
 - Configuration guide (`README.md`)
 - Default agent specification
 
-### Manual Client Integration
+### Node.js Usage
 
 ```typescript
 import { DrTrace } from 'drtrace';
@@ -39,7 +39,6 @@ const client = DrTrace.init();
 //   flushIntervalMs: 1000,
 //   maxRetries: 3,
 //   maxQueueSize: 10000,
-//   timeoutMs: 5000,
 // });
 
 // Attach to console
@@ -50,6 +49,48 @@ console.log('This is captured by DrTrace');
 console.error('Errors are also captured');
 ```
 
+### Browser Usage (React, Vue, etc.)
+
+In browser environments, you must provide `applicationId` and `daemonUrl` explicitly since the browser cannot read config files from the filesystem.
+
+```typescript
+import { DrTrace } from 'drtrace';  // Auto-selects browser entry point
+
+// Browser requires explicit options (no config file loading)
+const client = DrTrace.init({
+  applicationId: 'my-react-app',
+  daemonUrl: 'http://localhost:8001',
+  moduleName: 'frontend',  // Optional: helps identify log source
+  batchSize: 50,
+  flushIntervalMs: 1000,
+});
+
+// Attach to console
+client.attachToConsole();
+
+// Objects are serialized properly
+console.log({ user: 'john', action: 'login' });  // Logs as JSON
+console.error('Something went wrong', new Error('Details'));
+```
+
+**Important for Browser:**
+- `applicationId` is **required** - throws error if missing
+- `daemonUrl` is **required** - throws error if missing
+- CORS must be enabled on the daemon (enabled by default)
+- Objects and errors are automatically serialized to JSON
+
+#### CORS Configuration
+
+The DrTrace daemon allows all origins by default. To restrict origins:
+
+```bash
+# Allow specific origins
+export DRTRACE_CORS_ORIGINS="http://localhost:3000,https://myapp.com"
+
+# Start daemon
+uvicorn drtrace_service.api:app --host localhost --port 8001
+```
+
 ## Starting the DrTrace Daemon
 
 **Important**: The DrTrace daemon must be running before your application can send logs.
@@ -155,13 +196,13 @@ Create a new DrTrace client instance.
 
 **Options:**
 - `applicationId` (required) - Unique application identifier
-- `daemonUrl` (optional) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `daemonUrl` (required in browser, optional in Node.js) - DrTrace daemon URL (default: `http://localhost:8001`)
+- `moduleName` (optional) - Module/component name for log grouping (default: `'default'`)
 - `enabled` (optional) - Enable/disable DrTrace (default: `true`)
 - `batchSize` (optional) - Batch size for log batching (default: `50`)
 - `flushIntervalMs` (optional) - Flush interval in milliseconds (default: `1000`)
 - `maxRetries` (optional) - Retry attempts for failed sends with exponential backoff (default: `3`)
 - `maxQueueSize` (optional) - Maximum queued log entries before oldest entries are dropped (default: `10000`)
-- `timeoutMs` (optional) - Request timeout per batch in milliseconds (default: `5000`)
 
 ### `client.attachToConsole()`
 

package/agents/daemon-method-selection.md

@@ -1,83 +1,97 @@
 # Daemon Method Selection Guide
-
 **Purpose**: Guide for AI agents to choose the right method for daemon interaction.
+**Key Principle**: For AI agents, prefer interaction with daemon in this order (most preferred to least, if a method is unavailable, fall back to the next):
+- **CLI**: if available on client machine (check `## CLI Approach` below).
+- **HTTP/curl**: for complex interactions without dependencies (check `## HTTP/curl Approach` below).
+- **Python code**: when rich queries are needed (check `## Python code Approach` below).
+## CLI Approach
+If `drtrace` CLI is installed on the client machine:
+- Check with: `drtrace --version`
+- Prefer CLI commands: `drtrace grep`, `drtrace tail`, `drtrace status`
+- Benefit: no HTTP overhead and faster queries
+### Query Filter Rule: Mutually Exclusive
+When querying logs, use **either** `message_contains` **or** `message_regex`, **NOT both**.
+
+| Filter             | Use Case         | Example                                       |
+| ------------------ | ---------------- | --------------------------------------------- |
+| `message_contains` | Substring search | "timeout" matches "Connection timeout error"  |
+| `message_regex`    | Regex patterns   | "(db\|cache).*timeout" matches service errors |
+**Error if both used**: API returns 400 "Cannot use both filters".
+### Examples
+**CLI - Substring Search**:
+```bash
+drtrace grep "timeout" --since 1h
+```
+**CLI - Regex Search** (with `-E`):
+```bash
+drtrace grep -E "(db|cache).*timeout" --since 1h
+```
+## HTTP/curl Approach
+### Check Daemon Status
 
-**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
-
+```bash
+curl http://localhost:8001/status
+```
+### Discovery API via 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
+### Common Endpoints (for Quick Reference)
+**Note**: Always verify via `/openapi.json` - this list is for reference only (*API field names can change between versions. Using OpenAPI ensures compatibility*).
+
+| 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 |
+### Examples
+**HTTP - Substring Search**:
+```bash
+curl "http://localhost:8001/logs/query?message_contains=timeout&since=1h"
 ```
-
-**Why this matters**: API field names can change between versions. Using OpenAPI ensures compatibility.
-
----
-
-## Method 1: HTTP/curl (Preferred)
-
-### Check Daemon Status
-
+**HTTP - Regex Search**:
 ```bash
-curl http://localhost:8001/status
+curl "http://localhost:8001/logs/query?message_regex=(db|cache).*timeout&since=1h"
 ```
-
-### Query Logs
-
+**HTTP - 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
-
+**HTTP - Query with filter**:
 ```bash
 curl "http://localhost:8001/analysis/why?application_id=myapp&start_ts=${START_TS}&end_ts=${END_TS}&min_level=ERROR"
 ```
+## Python code Approach
+Use when you need rich SDK features or the HTTP method fails.
+### Examples
+**Get OpenAPI json for API information**
+```python
+import requests
 
-### Python requests (HTTP method)
+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
+```
+**Python requests (HTTP method)**
 ```python
 import requests
 import time
@@ -109,190 +123,75 @@ for log in logs:
     level = log.get("level")
     message = log.get("message")
 ```
+## When to Use Each Method
 
----
-
-## 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
-
+| Scenario                      | Recommended Method |
+| ----------------------------- | ------------------ |
+| Simple queries (status, logs) | CLI, HTTP/curl     |
+| Complex analysis              | HTTP or Python     |
+| Rich markdown output needed   | Python SDK         |
+| Running outside Python        | CLI, HTTP/curl     |
+| Setup guide interaction       | Python SDK         |
+| Debugging integration         | CLI commands       |
+| Script automation             | CLI, HTTP/curl     |
+## Important Notes
+### 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 drtrace_service.setup_agent_interface import analyze_and_suggest, suggest_for_language
-from pathlib import Path
-import asyncio
+from datetime import datetime, timezone, timedelta
 
-project_root = Path(".")
+# Local time (e.g., 2025-12-31 09:44:03 in GMT+7)
+local_time = datetime(2025, 12, 31, 9, 44, 3)
 
-# Get setup suggestions
-suggestions = await analyze_and_suggest(project_root)
+# 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}")
 
-# Language-specific suggestions
-python_suggestions = await suggest_for_language("python", project_root)
-cpp_suggestions = await suggest_for_language("cpp", project_root)
+# Method 2: Using system timezone
+import time
+unix_ts = time.mktime(local_time.timetuple())
 ```
-
----
-
-## Method 3: CLI Commands (Last Resort)
-
-Use only when HTTP and Python methods are unavailable.
-
-### Check Status
-
+**Bash:**
 ```bash
-python -m drtrace_service status
-```
-
-### Analyze Errors
+# Convert local time to Unix timestamp
+date -d "2025-12-31 09:44:03" +%s
 
-```bash
-python -m drtrace_service why --application-id myapp --since 5m --min-level ERROR
+# Convert with explicit timezone
+TZ=UTC date -d "2025-12-31T02:44:03" +%s
 ```
-
-### Setup Help
-
+#### API Query Examples with Timezone
 ```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
-```
+# 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"
 
----
-
-## Error Handling and Fallback Chain
+# Option 2: Use relative time (always relative to server UTC time)
+curl "http://localhost:8001/logs/query?since=5m"
 
-```python
-import requests
+# 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"
 
-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
-    """
+# 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.
 ---
-
-## 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 |
-
----
-
-## Related Documentation
-
-- `docs/daemon-interaction-guide.md` - OpenAPI discovery details
-- `docs/api-reference.md` - Complete API reference
-
----
-
-**Last Updated**: 2025-12-29
+**Last Updated**: 2026-01-06

package/agents/log-analysis.md

@@ -11,26 +11,7 @@ You must fully embody this agent's persona and follow all activation instruction
   <step n="1">Load persona from this current agent file (already in context)</step>
   <step n="2">Remember: You are a Log Analysis Specialist</step>
   <step n="3">READ the entire story file BEFORE any analysis - understand the query parsing rules</step>
-  <step n="4">When processing a user query, try methods in this order:
-    
-    **Method 1 (Preferred)**: Python code
-    - Try: `from drtrace_service.agent_interface import process_agent_query, check_daemon_status`
-    - If import succeeds: Use `response = await process_agent_query(user_query)` or `asyncio.run(process_agent_query(user_query))`
-    - Return the response string directly (it's already formatted markdown)
-    
-    **Method 2 (Fallback)**: HTTP API
-    - If Python import fails: Use HTTP requests to call DrTrace API endpoints
-    - **CRITICAL**: First fetch `/openapi.json` to discover field names (e.g., timestamp is `ts`, NOT `timestamp`)
-    - Check status: `GET http://localhost:8001/status`
-    - For analysis: `GET http://localhost:8001/analysis/why?application_id=X&start_ts=Y&end_ts=Z`
-    - Parse the JSON response using field names from OpenAPI schema
-    
-    **Method 3 (Last resort)**: CLI commands
-    - If both Python and HTTP fail: Execute `python -m drtrace_service why --application-id X --since 5m`
-    - Parse the CLI output and format for the user
-    
-    **Important**: Always check daemon status first. If daemon is unavailable, return clear error message with next steps.
-  </step>
+  <step n="4">When processing a user query, check `agents/daemon-method-selection.md` for details.</step>
   <step n="5">If information is missing, ask the user for clarification with helpful suggestions</step>
   <step n="6">If daemon is unavailable, provide clear error message and next steps</step>
   <step n="7">Show greeting, then display numbered list of ALL menu items from menu section</step>
@@ -65,77 +46,12 @@ You must fully embody this agent's persona and follow all activation instruction
 
 **Priority Order**: HTTP/curl (preferred) → Python SDK → CLI (last resort)
 
-### Quick Reference: Analysis API Operations
-
-| Operation | HTTP (Preferred) | Python SDK |
-|-----------|------------------|------------|
-| Query logs | `GET /logs/query` | `process_agent_query("show logs...")` |
-| Root cause | `GET /analysis/why` | `process_agent_query("explain error...")` |
-| Check status | `GET /status` | `check_daemon_status()` |
-
-### HTTP/curl Examples (Preferred)
-
-```bash
-# Check daemon status
-curl http://localhost:8001/status
-
-# Query 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
-curl "http://localhost:8001/analysis/why?application_id=myapp&start_ts=${START_TS}&end_ts=${END_TS}&min_level=ERROR"
-```
-
-### Python SDK Examples (Fallback)
-
-```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")
-
-# Non-async context
-response = asyncio.run(process_agent_query("show logs from last 5 minutes"))
-```
-
 **Key Points:**
 - **Package**: `drtrace_service` (NOT `drtrace_client`)
 - **Returns**: Formatted markdown string ready to display
 - **Async**: Functions are async, use `await` or `asyncio.run()`
 
-### Fallback Strategy
-
-1. **HTTP/curl (Preferred)**: Simple, no dependencies
-2. **Python SDK (Fallback)**: Rich async features when HTTP unavailable
-3. **CLI (Last Resort)**: `python -m drtrace_service why ...`
-
-**Important**: Always fetch `/openapi.json` first when using HTTP to discover correct field names (e.g., `ts` not `timestamp`).
-
-See `agents/daemon-method-selection.md` for complete fallback implementation.
-
-### Quick Reference: Endpoints
-
-| Endpoint | Purpose |
-|----------|---------|
-| `GET /status` | Health check |
-| `GET /logs/query` | Query logs |
-| `GET /analysis/why` | Root cause analysis |
-| `GET /analysis/time-range` | Time range analysis |
-| `GET /analysis/cross-module` | Cross-module analysis |
-
-**Parameters** (verify via `/openapi.json`):
-- `start_ts`, `end_ts`: Unix timestamps (floats)
-- `min_level`: DEBUG, INFO, WARN, ERROR, CRITICAL
-- `limit`: defaults to 100, max 1000
+**Best Practice**: See `docs/agent-design-best-practices.md` → "DrTrace Query Constraints" for detailed guidance.
 
 <menu>
   <item cmd="*analyze">[A] Analyze logs for a time range</item>
@@ -212,6 +128,4 @@ See `agents/daemon-method-selection.md` for complete fallback implementation.
 
 </capabilities>
 </agent>
-```
-
-
+```