Skip to content

Conversation

@skytin1004
Copy link
Collaborator

@skytin1004 skytin1004 commented Sep 15, 2025

Purpose

Add a reusable, cross-platform logging capability to the CLI that allows users to persist DEBUG-level logs to files with a simple flag.

Description

This change introduces a shared logging utility and wires a new --save-logs flag (with short form -s) into all CLI commands. When enabled, logs are written to files under the project’s --root-dir at DEBUG level, while console verbosity remains controlled by -d.

  • Introduce reusable logging utility: src/co_op_translator/utils/common/logging_utils.py
    • setup_logging(root_dir, debug, save_logs, command_name)
    • Console: CRITICAL by default, DEBUG with -d
    • File: when --save-logs is set, always write DEBUG logs
    • Create logs/ under the provided --root-dir
    • Generate timestamped file: co-op-translator_YYYYMMDD_HHMMSS+TZ_pid{PID}_levelDEBUG.log
    • Maintain logs/latest.log (overwritten each run; Windows-friendly, no symlinks)
  • Add short flag -s for --save-logs across commands
  • Keep -d for console verbosity; file logs remain DEBUG with --save-logs
  • Improve cross-platform behavior (Windows/Linux):
    • Use pathlib for paths and utf-8 file handlers
    • Remove unreliable os.access permission checks
    • Use %z for TZ offset in filenames

Examples:

  • translate -l ko --save-logs
  • translate -l ko -d -s

No breaking changes.

Related Issue

N/A

Does this introduce a breaking change?

When developers merge from main and run the server, azd up, or azd deploy, will this produce an error?
If you're not sure, try it out on an old environment.

  • Yes
  • No

Type of change

  • Bugfix
  • Feature
  • Code style update (e.g., formatting, local variables)
  • Refactoring (no functional or API changes)
  • Documentation content changes
  • Other... Please describe:

Checklist

Before submitting your pull request, please confirm the following:

  • I have thoroughly tested my changes: I ran the CLI locally (Windows) and verified files are generated under <root>/logs/ and contain DEBUG output.
  • All existing tests pass: I did not run the full test suite in this PR.
  • I have added new tests (if applicable): Logging behavior tests (e.g., via CliRunner) can be added in a follow-up.
  • I have followed the Co-op Translator’s coding conventions: Code formatted (black), imports at top, shared utility introduced.
  • I have documented my changes (if applicable).

Additional context

  • The latest.log file is provided as a convenience for quickly inspecting the most recent run without needing to find the timestamped file.
  • File names avoid reserved characters to be Windows-safe.
  • This design keeps console output quiet by default while enabling detailed file logs for debugging and CI usage.

- Introduce reusable logging utility: utils/common/logging_utils.py
  - setup_logging(root_dir, debug, save_logs, command_name)
  - Console: CRITICAL by default, DEBUG with -d
  - File: when --save-logs is set, always write DEBUG logs
  - Create logs/ under the provided --root-dir
  - Generate timestamped file: co-op-translator_YYYYMMDD_HHMMSS+TZ_pid{PID}_levelDEBUG.log
  - Maintain logs/latest.log (overwritten each run; Windows-friendly, no symlinks)

- Apply to all CLI commands:
  - translate (src/co_op_translator/cli/translate.py)
  - evaluate (src/co_op_translator/cli/evaluate.py)
  - migrate-links (src/co_op_translator/cli/migrate_links.py)

- Add short flag -s for --save-logs across commands
- Keep -d for console verbosity; file logs remain DEBUG with --save-logs
- Improve cross-platform behavior (Windows/Linux):
  - Use pathlib for paths, utf-8 file handlers
  - Remove unreliable os.access permission checks
  - Use %z for TZ offset in filenames

Example:
- translate -l ko --save-logs
- translate -l ko -d -s

No breaking changes.
@skytin1004 skytin1004 marked this pull request as ready for review September 15, 2025 04:35
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Sep 15, 2025
@skytin1004
Copy link
Collaborator Author

I have reviewed the changes and everything looks good.

@skytin1004 skytin1004 merged commit a6f715b into Azure:main Sep 15, 2025
2 checks passed
@skytin1004 skytin1004 deleted the log-saving branch September 15, 2025 04:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant