feat: add debug logging

[pnwpedro]

Description

• Adds debugging logging using standard logging package
  • Raw requests including body, but excluding the Authorization header are logged
  • Raw responses are logged

Enable debug logging with:

import logging
from fauna.client import Client
from fauna import fql

logging.basicConfig(
    level=logging.DEBUG
)
c = Client()
c.query(fql("42"))

Motivation and context

BT-5156

When users encounter unexpected behaviors they may need to inspect raw headers and data.

Why not a special env var named FAUNA_DEBUG? While we're doing this in other languages, it breaks a standard within Python that is intended to be configurable by logging namespace. Following the standard enables library consumers maximum control over logging within their applications without special treatment.

How was the change tested?

httpcore and httpx debug logs are excluded below for clarity.

DEBUG:fauna:query.request method=POST url=http://localhost:8443/query/1 headers=Headers({'host': 'localhost:8443', 'accept': '*/*', 'connection': 'keep-alive', 'user-agent': 'python-httpx/0.27.0', 'accept-encoding': 'gzip', 'content-type': 'application/json;charset=utf-8', 'x-driver': 'python', 'x-driver-env': 'driver=python-2.2.0; runtime=python-3.11.7-final env=unknown; os=darwin-23.6.0', 'x-format': 'tagged', 'x-query-timeout-ms': '5000', 'content-length': '79'}) data={'query': {'fql': ["Collection.byName('Product')?.delete()"]}, 'arguments': {}}

DEBUG:fauna:query.response status_code=200 headers=Headers({'x-faunadb-build': '24.09.04-1d6ea0d', 'connection': 'keep-alive', 'traceparent': '00-4ddb9c1b995a45dcda7a4f23d04a7608-3e6c82a6b607df94-00', 'content-length': '340', 'content-type': 'application/json;charset=utf-8'}) data={"data":{"@ref":{"name":"Product","coll":{"@mod":"Collection"},"exists":false,"cause":"deleted"}},"summary":"","txn_ts":1728562773960000,"stats":{"compute_ops":1,"read_ops":1,"write_ops":2,"query_time_ms":52,"contention_retries":0,"storage_bytes_read":2870,"storage_bytes_write":1099,"rate_limits_hit":[]},"schema_version":1728562581620000}

DEBUG:fauna:query.request method=POST url=http://localhost:8443/query/1 headers=Headers({'host': 'localhost:8443', 'accept': '*/*', 'connection': 'keep-alive', 'user-agent': 'python-httpx/0.27.0', 'accept-encoding': 'gzip', 'content-type': 'application/json;charset=utf-8', 'x-driver': 'python', 'x-driver-env': 'driver=python-2.2.0; runtime=python-3.11.7-final env=unknown; os=darwin-23.6.0', 'x-format': 'tagged', 'x-query-timeout-ms': '5000', 'x-last-txn-ts': '1728562773960000', 'content-length': '76'}) data={'query': {'fql': ["Collection.create({name:'Product'})"]}, 'arguments': {}}

DEBUG:fauna:query.response status_code=200 headers=Headers({'x-faunadb-build': '24.09.04-1d6ea0d', 'connection': 'keep-alive', 'traceparent': '00-4408756b7a30e8ef30de8129bd743573-2c94a65e80d073e2-00', 'content-length': '407', 'content-type': 'application/json;charset=utf-8'}) data={"data":{"@doc":{"name":"Product","coll":{"@mod":"Collection"},"ts":{"@time":"2024-10-10T12:19:34.030Z"},"indexes":{},"constraints":[],"history_days":{"@int":"0"}}},"summary":"","txn_ts":1728562774030000,"stats":{"compute_ops":1,"read_ops":0,"write_ops":2,"query_time_ms":66,"contention_retries":1,"storage_bytes_read":4452,"storage_bytes_write":1089,"rate_limits_hit":[]},"schema_version":1728562773960000}

DEBUG:fauna:query.request method=POST url=http://localhost:8443/query/1 headers=Headers({'host': 'localhost:8443', 'accept': '*/*', 'connection': 'keep-alive', 'user-agent': 'python-httpx/0.27.0', 'accept-encoding': 'gzip', 'content-type': 'application/json;charset=utf-8', 'x-driver': 'python', 'x-driver-env': 'driver=python-2.2.0; runtime=python-3.11.7-final env=unknown; os=darwin-23.6.0', 'x-format': 'tagged', 'x-query-timeout-ms': '5000', 'x-last-txn-ts': '1728562774030000', 'content-length': '65'}) data={'query': {'fql': ['Product.all().toStream()']}, 'arguments': {}}

DEBUG:fauna:query.response status_code=200 headers=Headers({'x-faunadb-build': '24.09.04-1d6ea0d', 'connection': 'keep-alive', 'traceparent': '00-a17d66773d3a8d2b2a1a49ef497ae9db-6b831e8dd7e423c1-00', 'content-length': '455', 'content-type': 'application/json;charset=utf-8'}) data={"data":{"@stream":"g9WD1YPGgmdQcm9kdWN0gwAAZipudWxsKoHKhoMAAGYqbnVsbCqCY2FsbIMAAGYqbnVsbCqA9PaDAABmKm51bGwqgwAAZipudWxsKoHKhoMAAGYqbnVsbCqCaHRvU3RyZWFtgwAAZipudWxsKoD09oMAAGYqbnVsbCqDAABmKm51bGwqgILBghpnB8ZWGgNHO8AA"},"summary":"","txn_ts":1728562774055000,"stats":{"compute_ops":1,"read_ops":0,"write_ops":0,"query_time_ms":17,"contention_retries":1,"storage_bytes_read":0,"storage_bytes_write":0,"rate_limits_hit":[]},"schema_version":1728562774030000}

DEBUG:fauna:stream.request method=POST url=http://localhost:8443/stream/1 headers=Headers({'host': 'localhost:8443', 'accept': '*/*', 'connection': 'keep-alive', 'user-agent': 'python-httpx/0.27.0', 'accept-encoding': 'gzip', 'content-type': 'application/json;charset=utf-8', 'x-driver': 'python', 'x-driver-env': 'driver=python-2.2.0; runtime=python-3.11.7-final env=unknown; os=darwin-23.6.0', 'x-format': 'tagged', 'content-length': '209'}) data={'token': 'g9WD1YPGgmdQcm9kdWN0gwAAZipudWxsKoHKhoMAAGYqbnVsbCqCY2FsbIMAAGYqbnVsbCqA9PaDAABmKm51bGwqgwAAZipudWxsKoHKhoMAAGYqbnVsbCqCaHRvU3RyZWFtgwAAZipudWxsKoD09oMAAGYqbnVsbCqDAABmKm51bGwqgILBghpnB8ZWGgNHO8AA'}

DEBUG:fauna:stream.data data={'type': 'status', 'txn_ts': 1728562774055000, 'cursor': 'gsGCGmcHxlYaA0c7wAA=', 'stats': {'read_ops': 8, 'storage_bytes_read': 144, 'compute_ops': 1, 'processing_time_ms': 1, 'rate_limits_hit': []}}

DEBUG:fauna:stream.data data={'type': 'add', 'data': {'@doc': {'id': '411360488987820544', 'coll': {'@mod': 'Product'}, 'ts': {'@time': '2024-10-10T12:19:43.140Z'}}}, 'txn_ts': 1728562783140000, 'cursor': 'gsGCGmcHxl8aCFg7AAA=', 'stats': {'read_ops': 1, 'storage_bytes_read': 51, 'compute_ops': 1, 'processing_time_ms': 5, 'rate_limits_hit': []}}

DEBUG:fauna:stream.data data={'type': 'add', 'data': {'@doc': {'id': '411360490832265728', 'coll': {'@mod': 'Product'}, 'ts': {'@time': '2024-10-10T12:19:44.890Z'}}}, 'txn_ts': 1728562784890000, 'cursor': 'gsGCGmcHxmAaNQxSgAA=', 'stats': {'read_ops': 1, 'storage_bytes_read': 51, 'compute_ops': 1, 'processing_time_ms': 12, 'rate_limits_hit': []}}

Screenshots (if appropriate):

Change types

• • Bug fix (non-breaking change that fixes an issue)
• • New feature (non-breaking change that adds functionality)
• • Breaking change (backwards-incompatible fix or feature)

Checklist:

• • My code follows the code style of this project.
• • My change requires a change to Fauna documentation.
• • My change requires a change to the README, and I have updated it accordingly.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[jrodewig]

README looks good aside from a minor typo (in under).

I left some other suggestions but feel free to take or leave those as you see fit. Thanks!

[jrodewig]

Narrow +1 on the README.

[findgriffin]

IMO if we're going to exclude auth headers, we should do it consistently across all the drivers.

[cynicaljoy]

I'm good with it, but want to make sure @findgriffin has a chance to ACK too since there's an open discussion going on.

[findgriffin]

Approving with reservations :)