chore(Pubsub): Add adhoc debug logging

[cy-yun]

https://docs.google.com/document/d/1R5UNVksMGCsN-KOthICr8-McrLmlN9F0XP99AKp6plY/edit?tab=t.s19hlulorz61
https://buganizer.corp.google.com/issues/427197812

[feywind]

Looks fine from a logging perspective, just wondering about the histogram class comment.

[cy-yun]

The acceptance tests pass locally. They can be flakey when running on Kokoro. Acceptance test failures are unrelated to my changes.

[aandreassa]

I had a change to look into this a bit more. I think the approach we want to take it is along the lines of:

1. Allow configuration of logger in lib/google/cloud/pubsub.rb. I was thinking something like here, with 3 options.
2. Once we have it there, we can pass it to Service to use downstream.
3. Logs should happen via Message from google-logging-utils:

@logger&.info do
    # This block is only executed if INFO level is enabled, making it efficient.
    Google::Logging::Message.new(....)
  end

This logic should be able to handle instances of a default Ruby logger (e.g. stdin/out) or Google::Logging::StructuredFormatter, which you can use for testing.

[cy-yun]

I had a change to look into this a bit more. I think the approach we want to take it is along the lines of:

1. Allow configuration of logger in lib/google/cloud/pubsub.rb. I was thinking something like here, with 3 options.
2. Once we have it there, we can pass it to Service to use downstream.
3. Logs should happen via Message from google-logging-utils:

@logger&.info do
    # This block is only executed if INFO level is enabled, making it efficient.
    Google::Logging::Message.new(....)
  end

This logic should be able to handle instances of a default Ruby logger (e.g. stdin/out) or Google::Logging::StructuredFormatter, which you can use for testing.

HI @aandreassa . Thanks for your feedback.

1. The logger is configurable. README instructs how.

You can programmatically configure a custom logger:

require "google/cloud/pubsub"
require "logger"

# Configure a logger for the pubsub library
Google::Cloud.configure.pubsub.logger = Logger.new "my-app.log"

If the custom logger is not configured, it will default to a standard stdout logger.

2. Could you provide more clarity on what "Downstream" means here? Do you mean the GAPIC layer?

3. I can investigate the Message class to understand how to make it work.

Talk tomorrow!

[cy-yun]

These two pull requests introduce a standardized and dynamically configurable debug logging framework for Google Cloud Ruby clients and implement it in the Pub/Sub library.

The primary goal was to enable on-demand debug logging that could be controlled by the developer via configuring a custom logger and controlling an environment variable to turn logs on/off. This required passing a logger from the handwritten client (google-cloud-pubsub) down to the underlying GAPIC client (google-cloud-pubsub-v1). I needed to build a wrapper around the logger (creating a logger duck-type) that will evaluate the environment variable before emitting logs.

The Solution:

• https://github.com/googleapis/ruby-core-libraries/pull/49/files creates the core component, GoogleSdkLoggerDelegator in google-logging-util gem. This class acts as a "duck-type" for a standard Ruby logger. Its key function is to wrap a real logger and check the GOOGLE_SDK_RUBY_LOGGING_GEMS environment variable before passing a log message through. If the variable isn't set for the specific gem, the delegator simply does nothing. This provides a reusable, centralized way to control logging across all Google Cloud Ruby libraries.

• https://github.com/googleapis/google-cloud-ruby/pull/32136/files implements this framework in the Pub/Sub library. It modifies the handwritten google-cloud-pubsub client to accept a logger, wraps it with the GoogleSdkLoggerDelegator, and emits debug logs requested by the Pub/Sub team. It also includes an .owlbot.rb file which will trigger a post-processing code change in the GAPIC-layer which will allow the GAPIC clients to accept both Logger type and GoogleSdkLoggerDelegator type. The github workflows are failing because I set the version of google-logging-util gem to currently-non-existent, future version, 0.3.0 . The current latest version of google-logging-util gem is 0.2.0 . The version with the release of GoogleSdkLoggerDelegator would be 0.3.0 (correct me if I'm wrong).

Once the first 2 PRs are approved, I will create a new PR that passes the GoogleSdkLoggerDelegator down to the GAPIC layer (google-cloud-pubsub-v1).