feat: add client library debug logging

[SamuelSchaub]

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> ☕️

If you write sample code, please follow the samples format.

[michaelpri10]

/gcbrun

[michaelpri10]

A few higher level comments:

• In all places where they are applicable, we should be logging the message ID (seems to be in place already), the ordering key, and whether exactly-once delivery is enabled for subscriptions. Additionally, while it's not explicitly state in the design document, I think we should log ack IDs where applicable as well.
• I don't think we are doing the sub-systems correctly here. I think we want to be creating java.util.logging.Logger objects with names that correspond to the sub-systems. For example, we have our MessageDispatcher.logger object [here](

  java-pubsub/google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/MessageDispatcher.java

  Line 61 in 1676abc

  private static final Logger logger = Logger.getLogger(MessageDispatcher.class.getName());

  instantiated with the name of the MessageDispatcher class. We can create new loggers for each sub-system.

I think that the Python debug logging implementation is good framework for what we want the logging here to look like.

[michaelpri10]

/gcbrun

[michaelpri10]

Update year to 2026.

[michaelpri10]

Since the loggers already have sub-systems attached, we don't need the pubsub:slow-ack prefix on the log. Same for other log calls.

[michaelpri10]

Additionally, we should have messages with more info. Here would be something like {LOG_PREFIX}: Message ack duration of {ack duration} is higher than the p99 ack duration

[michaelpri10]

Is the use of isLoggable here to avoid allocating and concatenating strings for logging when we don't need them?

[michaelpri10]

Use a more descriptive log like Ack called on message. Same below.

[michaelpri10]

Should this be ackRequestDataReceipts?

[michaelpri10]

nit: getSubcriberLogPrefix to differentiate better from getPublisherLogPrefix

[michaelpri10]

I think we should have the prefix always be the first part of the logs. Wrapping in in parentheses or square brackets would probably be the best option for formatting.

[michaelpri10]

This isn't necessary to do but a potential improvement to help improve readability could be to use this helper class to actually make the log calls. For example, you could create a helper method that takes in the subsystem, the log level, and the arguments needed for the log prefix. This would then get the logger, check isLoggable, create the prefix, and make the actual log call.

Note the getLogger may can either create or return an existing logger with a given name. It is probably worth instantiating each of the loggers within this class and then having an instance of LoggingUtil instantiated within MessageDispatcher and StreamingSubscriberConnection in order to ensure there are strong references to the logger objects.