Skip to content

Commit cd6e7dd

Browse files
mrz1836mrz1836
committed
feat: more upgrades
1 parent 93e521f commit cd6e7dd

46 files changed

Lines changed: 8616 additions & 182 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.golangci.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,6 @@
7777
"misspell",
7878
"musttag",
7979
"nakedret",
80-
"nestif",
8180
"nilerr",
8281
"nilnesserr",
8382
"nilnil",
@@ -107,7 +106,8 @@
107106
"wsl_v5",
108107
"gocognit",
109108
"exhaustive",
110-
"gocyclo"
109+
"gocyclo",
110+
"nestif"
111111
],
112112
"settings": {
113113
"funcorder": {

‎LICENSE‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2021 @MrZ1836
3+
Copyright (c) 2025 @MrZ1836
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1818
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1919
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
21+
SOFTWARE.

‎README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@
8484
* [Quick Start](#-quick-start)
8585
* [How It Works](#-how-it-works)
8686
* [Usage Examples](#-usage-examples)
87+
* [Logging and Debugging](#-logging-and-debugging)
8788
* [Documentation](#-documentation)
8889
* [Examples & Tests](#-examples--tests)
8990
* [Benchmarks](#-benchmarks)
@@ -312,6 +313,141 @@ targets:
312313
313314
<br/>
314315
316+
## 🔍 Logging and Debugging
317+
318+
go-broadcast provides comprehensive logging capabilities designed for debugging, monitoring, and troubleshooting. The logging system features intuitive verbose flags, component-specific debug modes, and automatic sensitive data redaction.
319+
320+
### Quick Start
321+
322+
```bash
323+
# Basic verbose output (-v for debug, -vv for trace, -vvv for trace with line numbers)
324+
go-broadcast sync -v # Debug level logging
325+
go-broadcast sync -vv # Trace level logging
326+
go-broadcast sync -vvv # Trace with caller info
327+
328+
# Component-specific debugging
329+
go-broadcast sync --debug-git # Show git command details
330+
go-broadcast sync --debug-api # Show GitHub API requests/responses
331+
go-broadcast sync --debug-transform # Show file transformation details
332+
go-broadcast sync --debug-config # Show configuration validation
333+
go-broadcast sync --debug-state # Show state discovery process
334+
335+
# Combine for comprehensive debugging
336+
go-broadcast sync -vv --debug-git --debug-api
337+
338+
# JSON output for log aggregation
339+
go-broadcast sync --log-format json
340+
341+
# Collect diagnostic information
342+
go-broadcast diagnose > diagnostics.json
343+
```
344+
345+
### Log Levels
346+
347+
- **ERROR**: Critical failures that prevent operation
348+
- **WARN**: Important issues that don't stop execution
349+
- **INFO**: High-level operation progress (default)
350+
- **DEBUG**: Detailed operation information (`-v`)
351+
- **TRACE**: Very detailed debugging information (`-vv`)
352+
353+
### Advanced Logging Features
354+
355+
#### Performance Monitoring
356+
All operations are timed automatically. Look for `duration_ms` in logs:
357+
```bash
358+
# Find slow operations
359+
go-broadcast sync --log-format json 2>&1 | \
360+
jq -r 'select(.duration_ms > 5000) | "\(.operation): \(.duration_ms)ms"'
361+
```
362+
363+
#### Security and Compliance
364+
- All tokens and secrets are automatically redacted
365+
- Audit trail for configuration changes and repository access
366+
- No sensitive data is ever logged
367+
368+
#### Troubleshooting Common Issues
369+
370+
**Git Authentication Issues**
371+
```bash
372+
# Debug git authentication problems
373+
go-broadcast sync -v --debug-git
374+
375+
# Common indicators:
376+
# - "Authentication failed" in git output
377+
# - "Permission denied" errors
378+
# - Check GH_TOKEN or GITHUB_TOKEN environment variables
379+
```
380+
381+
**API Rate Limiting**
382+
```bash
383+
# Monitor API usage
384+
go-broadcast sync --debug-api --log-format json 2>&1 | \
385+
jq 'select(.component=="github-api") | {operation, duration_ms, error}'
386+
```
387+
388+
**File Transformation Issues**
389+
```bash
390+
# Debug variable replacements and transformations
391+
go-broadcast sync -vv --debug-transform
392+
393+
# Shows:
394+
# - Variables being replaced
395+
# - File size changes
396+
# - Before/after content for small files (with -vvv)
397+
```
398+
399+
**State Discovery Problems**
400+
```bash
401+
# Understand what go-broadcast sees in repositories
402+
go-broadcast sync --debug-state
403+
404+
# Shows:
405+
# - Source repository state
406+
# - Target repository states
407+
# - Existing PR detection
408+
# - File discovery process
409+
```
410+
411+
### Log Management
412+
413+
#### Structured Logging
414+
JSON format is ideal for log aggregation systems:
415+
```bash
416+
# Send to log aggregation
417+
go-broadcast sync --log-format json 2>&1 | fluentd
418+
419+
# Parse with jq
420+
go-broadcast sync --log-format json 2>&1 | jq '.level="error"'
421+
422+
# Save debug session
423+
go-broadcast sync -vvv --debug-git 2> debug-$(date +%Y%m%d-%H%M%S).log
424+
```
425+
426+
#### Performance Analysis
427+
```bash
428+
# Find slowest operations
429+
go-broadcast sync --log-format json 2>&1 | \
430+
jq -r 'select(.duration_ms) | "\(.duration_ms)ms \(.operation)"' | \
431+
sort -rn | head -20
432+
433+
# Monitor memory usage (if implemented)
434+
go-broadcast sync --log-format json 2>&1 | \
435+
jq 'select(.memory_mb) | {operation, memory_mb}'
436+
```
437+
438+
### Environment Variables
439+
440+
| Variable | Description | Example |
441+
|---------------------------|------------------------|---------|
442+
| `GO_BROADCAST_LOG_LEVEL` | Default log level | `debug` |
443+
| `GO_BROADCAST_LOG_FORMAT` | Default log format | `json` |
444+
| `GO_BROADCAST_DEBUG` | Enable all debug flags | `true` |
445+
| `NO_COLOR` | Disable colored output | `1` |
446+
447+
For more detailed information, see the [comprehensive logging guide](docs/logging.md) and [troubleshooting runbook](docs/troubleshooting-runbook.md).
448+
449+
<br/>
450+
315451
## 📚 Documentation
316452

317453
- **Quick Start** – Get up and running in 5 minutes with the [Quick Start guide](#-quick-start)

‎docs/logging-quick-ref.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# go-broadcast Logging Quick Reference
2+
3+
## 🚀 Essential Commands
4+
5+
```bash
6+
# Basic verbose output
7+
go-broadcast sync -v # Debug level
8+
go-broadcast sync -vv # Trace level
9+
go-broadcast sync -vvv # Trace with caller info
10+
11+
# Component debugging
12+
go-broadcast sync --debug-git # Git commands
13+
go-broadcast sync --debug-api # GitHub API
14+
go-broadcast sync --debug-transform # File transformations
15+
go-broadcast sync --debug-config # Configuration validation
16+
go-broadcast sync --debug-state # State discovery
17+
18+
# JSON output
19+
go-broadcast sync --json -v # Structured JSON output
20+
go-broadcast sync --log-format json # Alternative syntax
21+
22+
# System diagnostics
23+
go-broadcast diagnose # Collect system info
24+
```
25+
26+
## 📋 Flag Reference
27+
28+
| Flag | Description | Output Level |
29+
|------|-------------|--------------|
30+
| `-v` | Debug level logging | DEBUG |
31+
| `-vv` | Trace level logging | TRACE |
32+
| `-vvv` | Trace with file:line info | TRACE + caller |
33+
| `--debug-git` | Git command details | DEBUG/TRACE |
34+
| `--debug-api` | GitHub API requests/responses | DEBUG/TRACE |
35+
| `--debug-transform` | File transformation details | DEBUG/TRACE |
36+
| `--debug-config` | Configuration validation | DEBUG/TRACE |
37+
| `--debug-state` | State discovery process | DEBUG/TRACE |
38+
| `--json` | JSON structured output | All levels |
39+
| `--log-format json` | JSON output (alternative) | All levels |
40+
41+
## 🔧 Common Troubleshooting
42+
43+
```bash
44+
# Authentication issues
45+
go-broadcast sync --debug-git -v
46+
echo $GITHUB_TOKEN | cut -c1-10 # Check token
47+
gh auth status # Test GitHub CLI
48+
49+
# Performance analysis
50+
go-broadcast sync --log-format json 2>&1 | \
51+
jq -r 'select(.duration_ms > 1000) | "\(.duration_ms)ms \(.operation)"'
52+
53+
# Find errors in logs
54+
go-broadcast sync --json 2>&1 | jq 'select(.level=="error")'
55+
56+
# Save debug session
57+
go-broadcast sync -vvv --debug-git 2> debug-$(date +%Y%m%d-%H%M%S).log
58+
59+
# Memory/performance monitoring
60+
go-broadcast sync --json --debug-api 2>&1 | \
61+
jq 'select(.component=="github-api") | {operation, duration_ms, error}'
62+
```
63+
64+
## 🌍 Environment Variables
65+
66+
| Variable | Default | Description |
67+
|----------|---------|-------------|
68+
| `GO_BROADCAST_LOG_LEVEL` | `info` | Default log level |
69+
| `GO_BROADCAST_LOG_FORMAT` | `text` | Default output format |
70+
| `GO_BROADCAST_DEBUG` | `false` | Enable all debug flags |
71+
| `NO_COLOR` | - | Disable colored output |
72+
| `GITHUB_TOKEN` | - | GitHub authentication token |
73+
74+
## 📄 Output Examples
75+
76+
### Text Format (Default)
77+
```
78+
15:04:05 INFO Starting broadcast sync version=1.2.3
79+
15:04:05 DEBUG Config loaded successfully path=.broadcast.yaml targets=3
80+
15:04:06 WARN Rate limit approaching remaining=100
81+
```
82+
83+
### JSON Format
84+
```json
85+
{
86+
"@timestamp": "2024-01-15T15:04:05.123Z",
87+
"level": "info",
88+
"message": "Starting broadcast sync",
89+
"component": "cli",
90+
"version": "1.2.3",
91+
"correlation_id": "a1b2c3d4"
92+
}
93+
```
94+
95+
## 🚨 Quick Diagnostics
96+
97+
```bash
98+
# System info for support
99+
go-broadcast diagnose > diagnostics.json
100+
101+
# Check configuration
102+
go-broadcast validate --debug-config -v
103+
104+
# Test connectivity
105+
gh api user # GitHub API access
106+
git --version # Git availability
107+
108+
# Log analysis pipeline
109+
go-broadcast sync --json 2>&1 | \
110+
jq 'select(.duration_ms) | {operation, duration_ms}' | \
111+
sort_by(.duration_ms) | reverse
112+
```
113+
114+
## 🎯 Debug Combinations
115+
116+
```bash
117+
# Full debugging (maximum verbosity)
118+
go-broadcast sync -vvv --debug-git --debug-api --debug-transform --debug-config --debug-state
119+
120+
# Performance focus
121+
go-broadcast sync --json --debug-api 2>&1 | jq 'select(.duration_ms > 5000)'
122+
123+
# Security audit
124+
go-broadcast sync --json 2>&1 | jq 'select(.component=="audit")'
125+
126+
# Git troubleshooting
127+
go-broadcast sync --debug-git -vv 2>&1 | grep -E "(git|clone|push|branch)"
128+
129+
# API rate limiting
130+
go-broadcast sync --debug-api --json 2>&1 | jq 'select(.rate_limit_remaining)'
131+
```
132+
133+
## 🔍 Log Analysis Tips
134+
135+
### Find Bottlenecks
136+
```bash
137+
# Operations taking >5 seconds
138+
jq 'select(.duration_ms > 5000) | {operation, duration_ms, repo}' < logs.json
139+
140+
# Most common operations
141+
jq -r 'select(.duration_ms) | .operation' < logs.json | sort | uniq -c | sort -rn
142+
```
143+
144+
### Error Analysis
145+
```bash
146+
# All errors with context
147+
jq 'select(.level=="error") | {message, component, operation, error}' < logs.json
148+
149+
# Failed operations with timing
150+
jq 'select(.status=="failed") | {operation, duration_ms, error}' < logs.json
151+
```
152+
153+
### Security Monitoring
154+
```bash
155+
# Authentication events
156+
jq 'select(.component=="audit" and .event=="authentication")' < logs.json
157+
158+
# Repository access
159+
jq 'select(.event=="repo_access") | {repo, action, user}' < logs.json
160+
```
161+
162+
## 📚 See Also
163+
164+
- **Comprehensive Guide**: [docs/logging.md](logging.md)
165+
- **Troubleshooting**: [docs/troubleshooting-runbook.md](troubleshooting-runbook.md)
166+
- **Main Documentation**: [README.md](../README.md#-logging-and-debugging)
167+
168+
---
169+
170+
**💡 Pro Tip**: Start with `-v` for basic debugging, then add specific `--debug-*` flags for targeted investigation. Use `--json` when piping to analysis tools.

0 commit comments

Comments
 (0)