feat: add verbose request tracing and structured API error responses.

[zhang-minchao]

Description

This PR improves API request observability and makes HTTP error responses consistent across OpenAI-compatible and Anthropic-compatible endpoints.

Request tracing

• Add an opt-in asynchronous rotating-file logger for verbose request traces.
• Resolve one x-request-id for each request, preferring the client-provided x-request-id or x-ms-client-request-id header and generating an ID when neither is present.
• Reuse the resolved ID across API logs, verbose trace events, and engine request parameters, and return it in the HTTP response header for end-to-end correlation.
• Record request lifecycle events (request_received, request_completed, and request_error) with the HTTP status code.
• For early request failures, record the endpoint, status, reason, and up to 8 KiB of the raw request body in the verbose trace log.
• Keep the serving hot path lightweight: tracing costs one relaxed atomic load when disabled; when enabled, entries are assembled in a thread-local buffer and submitted to a non-blocking spdlog async queue. If the queue is full, the oldest queued entry is dropped rather than blocking request processing.

Verbose tracing is disabled by default and can be configured with:

Option	Default	Description
--enable_verbose_trace_log	false	Enable verbose request-trace logging.
--verbose_trace_log_path	log/verbose_trace.log	Output log path.
--verbose_trace_log_max_size_mb	1024	Maximum size of each rotated file.
--verbose_trace_log_max_files	100000	Maximum number of rotated files retained.

Structured API errors

• Centralize internal StatusCode to HTTP status and API error-type mapping.
• Return structured JSON errors with the appropriate HTTP status instead of relying on brpc::Controller::SetFailed, which can replace the custom response with a generic HTTP 500.
• Preserve the expected protocol-specific envelopes:
  • OpenAI-compatible endpoints return {"error":{"message":...,"type":...,"code":...,"param":null}}.
  • Anthropic-compatible endpoints return {"type":"error","error":{"type":...,"message":...}}.
• Emit terminal SSE error events for failures after a streaming response has already committed HTTP 200.
• Apply the shared error path to JSON parsing, unsupported endpoints, model/service lookup, profiling, and control APIs.

Build fixes

• Fix stopping_checker_test static-library link dependencies.
• Remove the unnecessary prefix_cache -> request dependency that introduced circular static-archive link ordering after rebasing onto the latest main.

Related Issues

N/A

Change Type

• Bug fix
• New feature
• Performance improvement
• Refactor
• Documentation
• Test
• Build or CI

Validation

• GitHub Actions format-check passed.
• GitHub Actions build jobs are still in progress.
• CUDA build and tests.
• NPU build and tests.
• MLU build and tests.

Pull Request Checklist

Thank you for contributing to xLLM. Before requesting review, please make sure the following items are complete.

PR Title and Commit Messages

• The PR title and each commit message follow the xLLM commit format: <type>: <subject>.

Allowed types: feat, bugfix, docs, test, refactor, chore, style, revert, perf, model, build, release.
The subject should use clear English, start with a verb, include at least 4 words, and end with ..

Pre-commit Checks

• I have installed pre-commit by running pip install pre-commit or an equivalent command.
• I have installed the hooks with pre-commit install.
• I have run pre-commit run --all-files and fixed any reported issues.

If you are unsure how to set up pre-commit, see the pre-commit documentation.

Self Review

• I have self-reviewed the code according to .agents/skills/code-review/references/custom-code-style.md, especially code written or assisted by AI.
• I have rebased this PR onto the latest main branch.

Build and Test Coverage

• Tests have been added or updated as needed.
• CUDA: python setup.py build test has passed on a CUDA machine.
• NPU: python setup.py build test has passed on an NPU machine.
• MLU: python setup.py build test has passed on an MLU machine.

Reviewer Notes

• Verbose tracing is disabled by default. When enabled, failed-request traces can contain up to 8 KiB of raw request content; deployments should protect the log path and choose retention settings appropriate for potentially sensitive data.
• Please focus on protocol compatibility of the OpenAI/Anthropic error envelopes, StatusCode to HTTP mappings, streaming terminal-error behavior, and the non-blocking logging path.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.