voyageai-cli
Version:
CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search
291 lines (214 loc) • 6.28 kB
Markdown
# Debugging Techniques
Effective debugging requires systematic approaches and proper tooling. This guide covers debugging strategies for API integrations.
## Request/Response Logging
Log all HTTP interactions:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True
response = requests.get('https://api.example.com/users')
```
Output:
```
DEBUG:urllib3.connectionpool: Starting new HTTPS connection (1): api.example.com
DEBUG:urllib3.connectionpool: "GET /users HTTP/1.1" 200 1024
```
## Using cURL for Testing
Test API endpoints with cURL:
```bash
# Simple GET
curl https://api.example.com/users/user_123
# With authentication
curl -H "Authorization: Bearer token" https://api.example.com/users
# POST with data
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'
# Verbose output (headers and body)
curl -v https://api.example.com/users
# Save response to file
curl https://api.example.com/users > response.json
```
## HTTP Inspection Tools
Use tools to inspect requests/responses:
**Postman**: GUI tool for testing APIs
- Save requests for reuse
- Organize into collections
- Tests and assertions
- Environment variables
**Insomnia**: Lightweight REST client
- Code generation
- Plugin system
- Open source
**VS Code REST Client**: Inline in editor
```
GET https://api.example.com/users HTTP/1.1
Authorization: Bearer token
Content-Type: application/json
```
## Network Tracing
Capture network traffic with tcpdump:
```bash
# Capture traffic on port 443 (HTTPS)
sudo tcpdump -i en0 'port 443' -w api.pcap
# Read captured traffic
tcpdump -r api.pcap
# Decode with Wireshark (GUI)
wireshark api.pcap
```
Useful for low-level debugging; HTTPS is encrypted so limited visibility.
## SDK Debug Mode
Enable SDK debugging:
**JavaScript**:
```javascript
const client = new SaaS.Client({
apiKey: 'sk_live_abc123',
logger: (method, url, body, response) => {
console.log(`${method} ${url}`, response.status);
}
});
```
**Python**:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
client = SaaS.Client(api_key='sk_live_abc123')
```
**Go**:
```go
client := sdk.NewClient("sk_live_abc123")
client.Debug = true
```
## Request ID Tracing
Use request IDs to track requests through logs:
```python
import uuid
request_id = str(uuid.uuid4())
response = client.users.get('user_123', headers={
'X-Request-ID': request_id
})
# Later, search logs for this request
logs | grep request_id
```
## Reproducing Issues
Isolate and reproduce problems:
```python
# Minimal reproduction
import saasplatform
client = saasplatform.Client(api_key='sk_live_abc123')
try:
user = client.users.get('user_123')
print(user)
except Exception as e:
print(f"Error: {e}")
import traceback
traceback.print_exc()
```
Share minimal repro with support for faster debugging.
## Breakpoint Debugging
Use debuggers to step through code:
**Python (pdb)**:
```python
import pdb
def process_user(user_id):
user = client.users.get(user_id)
pdb.set_trace() # Execution pauses here
# Inspect variables: user, user_id, etc.
# Step through code
```
**JavaScript (Node.js)**:
```bash
node --inspect app.js
# Open chrome://inspect in Chrome
# Set breakpoints and step through
```
**VS Code Debug**:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Python",
"type": "python",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal"
}
]
}
```
## Comparing Requests
Debug by comparing working and broken requests:
```bash
# Working request (from logs)
curl -X GET https://api.example.com/users/user_123 \
-H "Authorization: Bearer token_good"
# Broken request
curl -X GET https://api.example.com/users/user_999 \
-H "Authorization: Bearer token_expired"
# Differences:
# 1. Different user ID
# 2. Expired token
# 3. Different header (maybe)
Test each change individually to isolate the issue
```
## Performance Profiling
Identify slow operations:
**Python (cProfile)**:
```python
import cProfile
cProfile.run('client.users.list(per_page=1000)')
# Output:
# ncalls tottime cumtime filename:lineno(function)
# 1 0.001 0.250 api_client.py:45(list)
# 1 0.200 0.200 requests.py:89(get)
```
**JavaScript (Node.js profiler)**:
```bash
node --prof app.js
node --prof-process isolate-*.log > profile.txt
```
## Sandbox Testing
Use sandbox environment for testing:
```python
client = SaaS.Client(
api_key='sk_test_sandbox_key',
environment='sandbox'
)
# Test safely without affecting production
user = client.users.create(name='Test User')
```
Sandbox data is reset daily/weekly; safe for experiments.
## Crash Logs and Stack Traces
When errors occur, capture full context:
```python
import sys
import traceback
try:
api_call()
except Exception as e:
tb_lines = traceback.format_exception(type(e), e, e.__traceback__)
print(''.join(tb_lines))
# Log for support
logger.error('API call failed', exc_info=True)
```
Stack traces show exact line where error occurred.
## Checklist for Debugging
1. **Understand the error**: What's the error message/code?
2. **Check logs**: Search for relevant log entries
3. **Verify prerequisites**: Is authentication correct? Is service available?
4. **Isolate**: Reproduce with minimal code
5. **Compare**: Working vs. broken requests
6. **Step through**: Use debugger to understand flow
7. **Check assumptions**: Are parameters what you think?
8. **Test in sandbox**: Confirm issue isn't production-specific
9. **Share details**: For support tickets, include request ID, error, logs
## Common Debugging Mistakes
1. **Assuming the error message**: Dig deeper; root cause may differ
2. **Testing in production**: Always test in sandbox first
3. **Forgetting to refresh**: Token expired? Refresh or re-authenticate
4. **Ignoring warnings**: Deprecation warnings indicate upcoming changes
5. **Not capturing request ID**: Impossible to trace later without it
See [Error Handling](error-handling.md) for recovery strategies.