feat: add opt-in structured HTTP request logging via tracing

[jpoehnelt]

Summary

Add PII-free structured logging for all HTTP requests using tracing. Logging is completely silent by default (zero overhead) and controlled by two environment variables:

Variable	Output	Format
GOOGLE_WORKSPACE_CLI_LOG	stderr	Human-readable (compact)
GOOGLE_WORKSPACE_CLI_LOG_FILE	File (daily rotation)	JSON-line

What's logged

Only non-PII metadata: API method ID, HTTP method, status code, latency, content-type. No query parameters, tokens, bodies, or project IDs.

Instrumented sites

• executor.rs — API request/response with latency
• client.rs — 429 rate-limit retry events
• discovery.rs — cache hit vs network fetch

Example

# Stderr logging
GOOGLE_WORKSPACE_CLI_LOG=gws=debug gws schema drive.files.list
# 2026-03-13T21:13:11Z DEBUG Discovery cache hit service=drive version=v3

# File logging (JSON-line, daily rotation)
GOOGLE_WORKSPACE_CLI_LOG_FILE=/tmp/gws-logs gws schema drive.files.list
cat /tmp/gws-logs/gws.log.2026-03-13
# {"timestamp":"...","level":"DEBUG","fields":{"message":"Discovery cache hit","service":"drive","version":"v3"}}

Dependencies added

• tracing (MIT) — instrumentation
• tracing-subscriber (MIT) — stderr + file layers
• tracing-appender (MIT) — daily rotating file writer

All maintained by the Tokio team, MIT-licensed (compatible with Apache-2.0).

[changeset-bot]

🦋 Changeset detected

Latest commit: 65e6bf9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the observability of the CLI by integrating a structured, opt-in logging system. It allows users to gain insights into HTTP request flows, rate-limiting events, and API discovery mechanisms without exposing sensitive information. The design prioritizes performance, ensuring that logging incurs no overhead unless explicitly enabled, and provides flexible output options for both human-readable and machine-parseable formats.

Highlights

• Opt-in Structured Logging: Introduced opt-in structured HTTP request logging using the tracing crate, providing enhanced observability for CLI operations.
• Zero Overhead by Default: Implemented logging with zero overhead by default, activating only when specific environment variables are set.
• PII-Free Metadata: Ensured that only PII-free metadata, such as API method ID, HTTP method, status code, latency, and content-type, is logged.
• Configurable Output: Provided flexible output options via environment variables: GOOGLE_WORKSPACE_CLI_LOG for human-readable stderr output and GOOGLE_WORKSPACE_CLI_LOG_FILE for JSON-line logs with daily rotation to a specified directory.
• Key Instrumentation Points: Instrumented critical areas including API request/response handling in executor.rs, 429 rate-limit retries in client.rs, and discovery document cache behavior in discovery.rs.
• New Dependencies: Added tracing, tracing-subscriber, and tracing-appender as new dependencies to support the logging infrastructure.

Changelog

• .changeset/add-structured-logging.md
  • Documented the addition of structured logging and associated environment variables.
• AGENTS.md
  • Updated the documentation to include the new src/logging.rs module and details about the logging environment variables.
• Cargo.lock
  • Synchronized the lock file to include new tracing related dependencies and their transitive requirements.
• Cargo.toml
  • Added tracing, tracing-subscriber, and tracing-appender crates as dependencies.
• README.md
  • Updated the environment variables section to list GOOGLE_WORKSPACE_CLI_LOG and GOOGLE_WORKSPACE_CLI_LOG_FILE.
• src/client.rs
  • Added debug logging for rate-limited retry attempts.
• src/discovery.rs
  • Introduced debug logging to indicate discovery document cache hits and network fetches.
• src/executor.rs
  • Implemented detailed debug logging for successful API requests and warning logs for API errors, capturing method, status, and latency.
• src/logging.rs
  • Created a new module responsible for initializing the tracing subscriber based on environment variables, supporting both stderr and daily rotating JSON file output.
• src/main.rs
  • Integrated the init_logging function call at application startup.
  • Updated the print_usage help message with new logging environment variables.

Activity

• No human activity (comments, reviews, etc.) has occurred on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov]

Codecov Report

❌ Patch coverage is 26.31579% with 42 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.67%. Comparing base (945ac91) to head (65e6bf9).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/logging.rs	34.88%	28 Missing ⚠️
src/executor.rs	0.00%	7 Missing ⚠️
src/main.rs	0.00%	3 Missing ⚠️
src/client.rs	0.00%	2 Missing ⚠️
src/discovery.rs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #478      +/-   ##
==========================================
- Coverage   67.81%   67.67%   -0.14%     
==========================================
  Files          38       39       +1     
  Lines       17136    17193      +57     
==========================================
+ Hits        11621    11636      +15     
- Misses       5515     5557      +42     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request introduces an opt-in structured logging feature using the tracing ecosystem, which is a great addition for observability. The implementation is well-structured, with logging configuration neatly encapsulated in a new logging module. Logging is instrumented at key points for HTTP requests, rate-limit retries, and discovery cache events. Overall, this is a solid feature addition.