feat: add --log-file flag to write JSON request logs to a file

[jishanahmed-shaikh]

Summary

Add a --log-file flag that writes all request logs to a file in addition to (or instead of) stderr. This is useful for auditing token usage over time or debugging issues after the fact.

Proposed behaviour

tokenproxy start --max-tokens-per-request 4096 --log-file proxy.log

Each log line should be a JSON object for easy parsing:

{"ts": "2026-04-28T14:32:01", "level": "INFO", "path": "/v1/chat/completions", "prompt_tokens": 312, "max_output_tokens": 512, "blocked": false}
{"ts": "2026-04-28T14:32:05", "level": "BLOCK", "path": "/v1/chat/completions", "prompt_tokens": 4200, "max_output_tokens": 1024, "blocked": true, "reason": "exceeds per-request limit"}

Implementation hints

• Add --log-file argument to the start subparser in cli.py
• Pass the file path to ProxyServer and open it in append mode
• In _log(), write to both stderr and the log file when a path is configured
• Use threading.Lock to make file writes thread-safe

Acceptance criteria

• --log-file proxy.log creates the file and writes JSON log lines
• Log file is appended to (not overwritten) on restart
• Stderr output is unchanged when --log-file is used
• File writes are thread-safe

[LikhinMN]

Hi! I'd like to work on this issue. Could you please assign it to me?

[jishanahmed-shaikh]

Hi! I'd like to work on this issue. Could you please assign it to me?

Can you please share your approach before I assign it to you?, I would love to share thoughts before we get into implementation.

[LikhinMN]

Hi @jishanahmed-shaikh, thanks! Here is my proposed approach for implementing the --log-file feature:

1. Update CLI Parsing (tokenproxy/cli.py)

• Add the --log-file argument to the start subparser using argparse.
• Pass the parsed args.log_file to the ProxyServer constructor inside cmd_start().

2. Configure the Server (tokenproxy/server.py)

• Update ProxyServer.__init__ to accept:

log_file: str | None = None

• Initialize a thread lock:

self._log_lock = threading.Lock()

• Store the log_file path on the server instance.
• When injecting dependencies into _ProxyHandler in ProxyServer.start(), pass down the log_file and _log_lock (or alternatively a bound logging method) so the request handler can use them.

3. Refactor _log() for JSON Support

Currently, _log() is a module-level function that only takes a formatted string. Since it needs access to the file and lock, we have two options:

1. Preferred: Move _log() to be a method of ProxyServer and inject self.log into _ProxyHandler.
2. Set up global _LOG_FILE and _LOG_LOCK variables in server.py when the server starts.

Inside the logging function/method:

• Modify it to optionally accept structured data:

req_data: dict | None = None

• Continue printing the existing formatted string to sys.stderr to preserve current behavior.

• If a log file is configured and req_data is provided:

  • Acquire the lock.
  • Open the file in append mode ("a").
  • Write:

json.dumps(req_data) + "\n"

• Close the file.

Opening the file on each write ensures logs are appended safely without keeping file descriptors open unnecessarily.

4. Construct JSON in the Request Handler

In _ProxyHandler._handle_request:

• Capture the current timestamp in ISO 8601 format:

datetime.now(timezone.utc).isoformat()

• Construct a log_data dictionary containing:

  • ts
  • level
  • path
  • prompt_tokens
  • max_output_tokens
  • blocked
  • reason (when applicable)

• Pass this dictionary to the updated logging method alongside the existing formatted log message.

Let me know what you think of this plan. If it looks good, I can go ahead and open a PR.

[jishanahmed-shaikh]

Looks Solid, Please go ahead