2.7 KiB
ADR-001: Do Not Use PGO (Profile-Guided Optimization)
Status
Accepted
Background
During the code modernization review on 2026-04-16, it was suggested to add -pgo=auto to the build for performance improvement.
Decision
Do not use PGO, and explicitly prohibit its reintroduction in the future without first obtaining representative profiling data.
Reasons
1. Tool Characteristics Are Not Suitable for PGO
searxng-mcp-go is an MCP server / CLI tool:
- Each execution is short-lived (request → response → exit)
- Cannot continuously collect profiling data like a long-running HTTP server
- Profiling data is written to disk after each process exit, making it impossible to accumulate meaningful hot-path information across processes
2. No Representative Profiling Data
The core prerequisite of PGO is: profiling data must represent real workloads.
| Data Source | Problem |
|---|---|
| A few manual executions | Insufficient samples, one-sided path coverage |
| Benchmark script | Artificially constructed workloads cannot represent real usage scenarios |
| Accumulated personal usage | Low query diversity, cannot cover most code paths |
PGO without representative data may actually degrade performance (the compiler optimizes for incorrect hot paths).
3. Bottleneck Is Not Local Compute
For the SearXNG MCP server:
- The real bottleneck is network latency (time spent calling the external SearXNG API)
- Local CPU computation accounts for a very small proportion
- Even if PGO delivers a 5–15% local compute improvement, the overall end-to-end latency improvement would be negligible
4. Cost-Benefit Ratio Is Too Low
Implementing PGO requires:
- Researching how to collect profiling data
- Designing representative benchmarks
- Maintaining
.pgofiles and keeping them updated
The time investment far outweighs the actual benefit.
Alternative Optimization Directions
If performance improvements are needed in the future, the following directions are more effective:
- Result caching — return the previous result directly for identical queries (requires a separate mechanism; not recommended for now)
- Reduce network latency — use a closer SearXNG instance
- Concurrent queries — query multiple engines simultaneously without waiting for all results
- Response compression — reduce transmitted data volume
Conditions for Reconsideration
If any of the following occur in the future, PGO can be re-evaluated:
- searxng-mcp-go evolves into a long-running MCP server deployment
- Sufficient real production profiling data has been accumulated
- There is a clear benchmark proving PGO delivers quantifiable improvements
Effective Date
2026-04-16