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](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration#logging-config-fields) options in your `google-ads.yaml` file or environment variables.
- **Programmatically with Python:** Use Python's built-in [`logging`](https://docs.python.org/3/library/logging.html) framework for direct control.

> [!CAUTION]
> **Caution:** Setting the log level to `DEBUG` logs full API request and response payloads, which may contain sensitive account information or personal data. Don't leave `DEBUG` logging enabled in production environments.

## 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](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration#logging-config-fields).
- Passes those settings to Python's built-in [`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#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`](https://docs.python.org/3/library/logging.html#logging.Logger.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:

| Level | Successful request | Failed request |
|---|---|---|
| `DEBUG` | A detailed log with complete request and response objects as JSON. | A detailed log with complete request and exception objects as JSON. |
| `INFO` | A concise summary with specific request and response fields. | A detailed log with complete request and exception objects as JSON. |
| `WARNING` | None | A concise summary with specific request information, the exception state, and the error message. |

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`](https://github.com/googleads/google-ads-python/blob/HEAD/examples/basic_operations/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](https://grpc.io/blog/grpc-web-interceptor) 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](https://developers.google.com/google-ads/api/docs/productionize/logging#option-4-implement-a-custom-grpc-logging-interceptor) for more details and an example of a
custom logging interceptor.