Skip to content

Commit 521f96f

Browse files
DannylSyph3rDannylSyph3r
committed
Added Agent TOML/YAML, Template JSON and README
1 parent 8fbedb2 commit 521f96f

File tree

19 files changed

+8342
-0
lines changed

19 files changed

+8342
-0
lines changed

‎agents/tracehound/README.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
# TraceHound - Observability Enforcement Agent
2+
3+
Language-agnostic observability enforcement agent that verifies critical API paths have proper logging, tracing, error handling, and metrics collection.
4+
5+
## Overview
6+
7+
TraceHound is an observability guard agent that enforces observability contracts across backend API code. It verifies that critical API endpoints have proper observability signals at every step of a request's code flow, helping you identify missing instrumentation before it becomes a production problem.
8+
9+
## Features
10+
11+
- **Multi-Language Support**: Built-in patterns for TypeScript, JavaScript, Python, Java, Go, Rust, and C#
12+
- **Contract-Based Verification**: Define observability contracts for your critical API endpoints
13+
- **Code Flow Analysis**: Traces request paths through multiple layers (controllers, services, DAL, middleware)
14+
- **Pattern Detection**: Automatically detects logging, tracing, error handling, and metrics instrumentation
15+
- **Actionable Reports**: Generates detailed violation reports with specific recommendations
16+
- **Configurable Severity**: Filter violations by severity level (CRITICAL, HIGH, MEDIUM, LOW)
17+
- **Safe Analysis**: Read-only static analysis that never modifies your code
18+
- **Auto-Configuration**: Creates template config file if none exists
19+
20+
## Quick Start
21+
22+
### First Run - Create Config
23+
24+
```bash
25+
# Run the agent - it will create observe-config.json template
26+
qodo tracehound
27+
# Output: ✅ Created observe-config.json - Please edit it to define your API monitoring contracts and re-run the agent.
28+
```
29+
30+
### Edit Config
31+
32+
Open `observe-config.json` and define your critical API endpoints:
33+
34+
```json
35+
{
36+
"metadata": {
37+
"language": "typescript"
38+
},
39+
"contracts": [
40+
{
41+
"id": "create-order",
42+
"name": "POST /api/orders - Create Order",
43+
"enabled": true,
44+
"code_flow": [
45+
{
46+
"layer": "controller",
47+
"file_pattern": "src/api/orders.ts",
48+
"signals": ["logging", "error_handling"]
49+
},
50+
{
51+
"layer": "service",
52+
"file_pattern": "src/services/orderService.ts",
53+
"signals": ["logging", "error_handling", "metrics"]
54+
},
55+
{
56+
"layer": "dal",
57+
"file_pattern": "src/dal/orders.ts",
58+
"signals": ["logging", "error_handling"]
59+
}
60+
]
61+
}
62+
]
63+
}
64+
```
65+
66+
### Run Analysis
67+
68+
```bash
69+
# Run with default settings (TypeScript, MEDIUM threshold, fail on violations)
70+
qodo tracehound
71+
72+
# Analyze Python project
73+
qodo tracehound --language=python
74+
75+
# Only show HIGH and CRITICAL violations
76+
qodo tracehound --severity_threshold=HIGH
77+
78+
# Run without failing the build
79+
qodo tracehound --fail_on_violations=false
80+
81+
# Combine options
82+
qodo tracehound --language=java --severity_threshold=CRITICAL --fail_on_violations=true
83+
```
84+
85+
## Configuration
86+
87+
### Agent Arguments
88+
89+
| Parameter | Type | Default | Description |
90+
|-----------|------|---------|-------------|
91+
| `language` | string | typescript | Primary language to analyze (typescript, python, java, go, rust, csharp) |
92+
| `severity_threshold` | string | MEDIUM | Minimum violation severity to report (CRITICAL, HIGH, MEDIUM, LOW) |
93+
| `fail_on_violations` | boolean | true | Exit with code 1 if violations found |
94+
95+
### Config File Structure
96+
97+
The `observe-config.json` file defines your observability contracts:
98+
99+
```json
100+
{
101+
"metadata": {
102+
"language": "typescript"
103+
},
104+
"contracts": [
105+
{
106+
"id": "unique-contract-id",
107+
"name": "Descriptive Name",
108+
"enabled": true,
109+
"code_flow": [
110+
{
111+
"layer": "controller|service|dal|middleware",
112+
"file_pattern": "path/to/file.ts",
113+
"signals": ["logging", "error_handling", "tracing", "metrics"]
114+
}
115+
]
116+
}
117+
]
118+
}
119+
```
120+
121+
## How It Works
122+
123+
### Execution Flow
124+
125+
**PHASE 1: CONFIG VALIDATION**
126+
1. Checks if `observe-config.json` exists
127+
2. If not found, creates template config from `observability-template.json`
128+
3. Validates config structure and required fields
129+
4. Validates language is supported
130+
5. Parses and stores contracts
131+
132+
**PHASE 2: PATTERN INITIALIZATION**
133+
134+
Initializes language-specific observability patterns based on the configured language. The agent has built-in knowledge of logging, error handling, tracing, and metrics patterns for each supported language.
135+
136+
**PHASE 3: CONTRACT VERIFICATION**
137+
138+
For each enabled contract:
139+
1. Verifies each code flow layer exists
140+
2. Reads file content once per layer
141+
3. Scans for all required observability signals
142+
4. Flags missing signals as violations
143+
5. Assigns severity based on layer criticality
144+
145+
**PHASE 4: REPORT GENERATION**
146+
1. Aggregates all violations
147+
2. Calculates compliance score
148+
3. Generates prioritized recommendations
149+
4. Outputs structured JSON report
150+
151+
## Use Cases
152+
153+
### Pre-Deployment Checks
154+
Verify observability coverage before deploying to production. Catch missing instrumentation in CI/CD.
155+
156+
### API Monitoring Standards
157+
Enforce organization-wide observability standards for critical API endpoints.
158+
159+
### Incident Prevention
160+
Identify gaps in logging and error handling before they cause blind spots in production.
161+
162+
### Refactoring Validation
163+
Ensure observability isn't lost during code refactoring or feature additions.
164+
165+
### Team Onboarding
166+
Help new team members understand what observability signals are expected in the codebase.
167+
168+
## Tools Used
169+
170+
- **Filesystem**: Config loading and file content reading
171+
- **Ripgrep**: Efficient pattern matching for signal detection
172+
- **Git**: Repository context and file discovery
173+
174+
## Severity Levels
175+
176+
Violations are assigned severity based on the layer and missing signal type:
177+
178+
- **CRITICAL**: Missing error handling in any layer, missing logging in DAL
179+
- **HIGH**: Missing logging in controller/service, missing metrics in service
180+
- **MEDIUM**: Missing tracing in any layer, missing metrics in controller
181+
- **LOW**: Optional signals or less critical combinations
182+
183+
## Output Format
184+
185+
The agent outputs a structured JSON report:
186+
187+
```json
188+
{
189+
"report_metadata": {
190+
"generated_at": "2025-10-17T10:30:00Z",
191+
"project_root": "/path/to/project",
192+
"language": "typescript",
193+
"config_file": "observe-config.json",
194+
"execution_time_ms": 1234
195+
},
196+
"summary": {
197+
"total_contracts_analyzed": 3,
198+
"total_endpoints_verified": 3,
199+
"overall_compliance_score": 85.5,
200+
"violations_by_severity": {
201+
"CRITICAL": 0,
202+
"HIGH": 2,
203+
"MEDIUM": 4,
204+
"LOW": 1
205+
}
206+
},
207+
"violations": [
208+
{
209+
"contract_id": "create-order",
210+
"contract_name": "POST /api/orders",
211+
"severity": "HIGH",
212+
"layer": "service",
213+
"file_pattern": "src/services/orderService.ts",
214+
"signal_type": "logging",
215+
"file": "src/services/orderService.ts",
216+
"line": 45,
217+
"issue": "Missing logging in orderService.ts service layer",
218+
"recommendation": "Add logger.info() or logger.error() calls to track order processing"
219+
}
220+
],
221+
"recommendations": [
222+
{
223+
"priority": 1,
224+
"type": "critical_gap",
225+
"target": "Error Handling",
226+
"recommendation": "Add try-catch blocks in all service layers",
227+
"impact": "Prevents silent failures and improves debugging"
228+
}
229+
],
230+
"warnings": [],
231+
"success": true
232+
}
233+
```
234+
235+
## Error Handling
236+
237+
TraceHound handles errors gracefully:
238+
- Continues analysis if config file has warnings
239+
- Logs tool failures as warnings
240+
- Proceeds with partial results if some contracts fail
241+
- Returns success with warnings rather than failing entirely
242+
- Creates helpful template if config is missing
243+
244+
## Integration
245+
246+
### GitHub Actions
247+
248+
```yaml
249+
- name: Check Observability
250+
run: |
251+
npm install -g @qodo/command
252+
qodo tracehound --severity_threshold=HIGH
253+
```
254+
255+
### GitLab CI
256+
257+
```yaml
258+
observability-check:
259+
script:
260+
- npm install -g @qodo/command
261+
- qodo tracehound --language=typescript
262+
```
263+
264+
### Jenkins
265+
266+
```groovy
267+
stage('Observability') {
268+
steps {
269+
sh 'qodo tracehound --fail_on_violations=true'
270+
}
271+
}
272+
```
273+
274+
## Support
275+
276+
For issues or questions about the TraceHound agent, please refer to the project documentation or create an issue in the repository.

0 commit comments

Comments
 (0)