Enable logging

Page Summary

outlined_flag

• The library offers logging for Google Ads API interactions, capturing both detailed request/response information and concise summaries.

• Logging settings can be controlled via client library configuration options or programmatically using Python's logging framework.

• Automatic logging configuration occurs upon GoogleAdsClient initialization, reading settings and activating them with Python's logging.config.dictConfig.

• When used as a package, you must add a logging handler to the library's logger instance to direct where log messages are sent.

• Log levels like DEBUG, INFO, and WARNING control the verbosity and type of messages displayed for successful or failed requests.

The library provides versatile logging for Google Ads API interactions. You can capture:

• Detailed information: Full requests sent to the API and responses received.
• Concise summaries: High-level overviews of API interactions.

You can control these logging settings in two ways:

• Client library configuration: Use the library's specific configuration options in your google-ads.yaml file or environment variables.
• Programmatically with Python: Use Python's built-in logging framework for direct control.

Configure through google-ads.yaml

Logging is configured automatically when a GoogleAdsClient instance is initialized (for example, when you call load_from_storage). At initialization, the library:

• Reads your specified logging settings from its configuration.
• Passes those settings to Python's built-in logging.config.dictConfig to activate them.

For example, you can add a logging section to your google-ads.yaml file:

logging:
  version: 1
  disable_existing_loggers: false
  formatters:
    default_fmt:
      format: '[%(asctime)s - %(levelname)s] %(message).5000s'
      datefmt: '%Y-%m-%d %H:%M:%S'
  handlers:
    default_handler:
      class: logging.StreamHandler
      formatter: default_fmt
  loggers:
    '':
      handlers: [default_handler]
      level: INFO

Configure programmatically

When using the library as an installed package without a logging section in your configuration file, you can integrate its logging with your application's logging setup programmatically. Attach a logging handler to the library's logger instance (google.ads.googleads.client) using addHandler and set the target log level:

import logging
import sys

# Retrieve the library's logger instance.
logger = logging.getLogger("google.ads.googleads.client")

# Direct logs to standard output (stdout).
logger.addHandler(logging.StreamHandler(sys.stdout))

# Set the log level to DEBUG to view detailed messages.
logger.setLevel(logging.DEBUG)

If you prefer to send logs to standard error (stderr), which is often used for error messages and warnings, pass sys.stderr to logging.StreamHandler:

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.addHandler(logging.StreamHandler(sys.stderr))
logger.setLevel(logging.WARNING)

Log levels

The client generates logs at several severity levels, and you can configure the logger to see some or all of the following:

Because the Python logging framework ignores log messages that are less severe than the configured level, setting the level to WARNING shows only concise messages for failed requests, whereas setting the level to DEBUG shows all log types in the table.

Log to a file

You can write logs to a file either programmatically in Python or by redirecting output from the command line.

Log to a file in Python

To write logs directly to a file from Python, attach a logging.FileHandler to the client logger:

import logging

logger = logging.getLogger("google.ads.googleads.client")
file_handler = logging.FileHandler("google_ads.log")
logger.addHandler(file_handler)
logger.setLevel(logging.INFO)

Redirect output using the shell

When you run example scripts like get_campaigns.py from the command line, you can redirect console log output to a file using your operating system's shell.

To save standard output to a file (overwriting any existing file):

python get_campaigns.py -c $CUSTOMER_ID > campaign_logs.txt

To append standard output to an existing file:

python get_campaigns.py -c $CUSTOMER_ID >> campaign_logs.txt

To save both standard output and standard error (for errors and warnings) to the same file:

python get_campaigns.py -c $CUSTOMER_ID > all_logs.txt 2>&1

Or, on Bash 4+:

python get_campaigns.py -c $CUSTOMER_ID &> all_logs.txt

Custom gRPC interceptors

The Python client library uses gRPC interceptors to access and log request and response details. You can set up your own custom logging by creating a gRPC interceptor with custom logic. See the Logging guide for more details and an example of a custom logging interceptor.