cloudru-qa-grpc-client-structlog 1.0.0__py3-none-any.whl

cloudru_qa_grpc_client_structlog-1.0.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: cloudru-qa-grpc-client-structlog
+Version: 1.0.0
+Summary: Структурированные логи для gRPC-клиента
+Project-URL: Repository, https://github.com/cloud-ru-tech/qa-libraries
+Project-URL: Issues, https://github.com/cloud-ru-tech/qa-libraries/issues
+Author-email: Алексей Кирютин <ayukiryutin@cloud.ru>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: cloudru-qa-grpc-client<2,>=1.0.0
+Requires-Dist: structlog>=26.1.0
+Description-Content-Type: text/markdown
+
+# Structured logs for the gRPC client
+
+[![PyPI](https://img.shields.io/pypi/v/cloudru-qa-grpc-client-structlog)](https://pypi.org/project/cloudru-qa-grpc-client-structlog/)
+[![Python](https://img.shields.io/pypi/pyversions/cloudru-qa-grpc-client-structlog)](https://pypi.org/project/cloudru-qa-grpc-client-structlog/)
+[![License](https://img.shields.io/pypi/l/cloudru-qa-grpc-client-structlog)](https://github.com/cloud-ru-tech/qa-libraries/blob/master/LICENSE)
+
+English | [Русский](README.ru.md)
+
+The `with_structlogger` option for the [gRPC client](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/grpc-client)
+logs all requests and responses through [structlog](https://www.structlog.org/en/stable/index.html).
+
+The standard grpc-client logger puts the request in one text string. This option logs the method, body,
+metadata, and status as separate fields, visible in the console during debugging and available
+for searching and filtering in collected logs.
+
+- [Installation](#installation)
+- [Skills for AI agents](#skills-for-ai-agents)
+- [Usage](#usage)
+- [Asynchronous client](#asynchronous-client)
+- [Log fields](#log-fields)
+- [Masking secrets](#masking-secrets)
+- [Parameters](#parameters)
+- [Development](#development)
+
+## Installation
+
+Requires Python 3.13 or later.
+
+```shell
+pip install cloudru-qa-grpc-client-structlog
+```
+
+Import the library as `grpc_client_structlog`. A compatible version of
+[`cloudru-qa-grpc-client`](https://github.com/cloud-ru-tech/qa-libraries/tree/master/packages/grpc-client)
+is installed with it.
+
+## Skills for AI agents
+
+The package includes the [`grpc-client-structlog-usage`](https://github.com/cloud-ru-tech/qa-libraries/blob/master/.agents/skills/grpc-client-structlog-usage/SKILL.md) skill
+with examples and usage rules for AI agents. Install the library
+in your project environment, then run this from its root (requires [`uv`](https://docs.astral.sh/uv/)):
+
+```shell
+uvx library-skills install --skill grpc-client-structlog-usage --yes
+```
+
+For Claude Code, add `--claude`. The instructions are shipped with the library version.
+
+## Usage
+
+Pass the option to the client constructor; logging is then automatic:
+
+```python
+import structlog
+
+from grpc_client import GRPCClient
+from grpc_client_structlog import with_structlogger
+
+from api import orders_pb2, orders_pb2_grpc
+
+
+class OrdersClient(GRPCClient[orders_pb2_grpc.OrdersStub]):
+    @property
+    def stub_class(self):
+        return orders_pb2_grpc.OrdersStub
+
+    def get_order(self, order_id: str):
+        return self.send_unary_unary_request(orders_pb2.GetOrderRequest(id=order_id), self.stub.GetOrder)
+
+
+with OrdersClient.from_addr(
+    "orders.example.com:443",
+    with_structlogger(structlog.get_logger("orders")),
+) as client:
+    client.get_order("42")
+```
+
+The request is logged as a `grpc request sent` event, the response as `grpc response received`.
+A shared `trace_id` field links them.
+
+## Asynchronous client
+
+Use the same option without extra configuration: the interceptor is selected
+based on the client type:
+
+```python
+from grpc_client import AsyncGRPCClient
+
+
+class AsyncOrdersClient(AsyncGRPCClient[orders_pb2_grpc.OrdersStub]):
+    @property
+    def stub_class(self):
+        return orders_pb2_grpc.OrdersStub
+
+    async def get_order(self, order_id: str):
+        return await self.send_unary_unary_request(orders_pb2.GetOrderRequest(id=order_id), self.stub.GetOrder)
+
+
+async with AsyncOrdersClient.from_addr("orders.example.com:443", with_structlogger(logger)) as client:
+    await client.get_order("42")
+```
+
+The final response-stream record is written in a separate task, so close the asynchronous
+client: `close()` waits for these tasks.
+
+## Log fields
+
+Up to two records per call, linked by a shared `trace_id`: request and response.
+
+| Field | Event | Value |
+|---|---|---|
+| `method` | both | full method name such as `/package.Service/Method` |
+| `body` | both | message body as a JSON string; responses include it only for successful unary calls |
+| `metadata` | both | metadata as a JSON string; omitted if no metadata was present |
+| `status_code` | response | status code name: `OK`, `NOT_FOUND`, … |
+| `details` | response | service error text; present only for failed calls |
+| `messages_count` | response | number of messages received from the stream; present only for streaming calls |
+| `trace_id` | both | UUID4 generated per request |
+
+`status_code` contains the code **name**, not its number. Names are readable without a reference
+and easy to filter. Including the number would give the field two values and require
+substring searches for `5 (NOT_FOUND)`.
+
+Compound values, `body` and `metadata`, are serialized as JSON strings before logging,
+rather than nested structures, to avoid mixing their fields with application context fields.
+
+Neither request nor response stream bodies are logged: consuming a stream for logging would change
+call behavior. A streaming request uses `<streamed content>` in `body`, while a response stream
+logs its final status and `messages_count`.
+
+Long bodies are truncated at 4096 characters by default, followed by
+`... <обрезано>` in `body`. Set the limit with `payload_maxlength`. If preparing the body fails,
+for example because of an invalid glom path in `sanitize_keys`, `body` contains
+`<не удалось подготовить тело сообщения>`. The request still goes through: logging is designed
+to avoid breaking calls.
+
+## Masking secrets
+
+Fields with common secret names are masked **by default at every depth**, including
+nested messages and array items:
+
+`authorization`, `proxy-authorization`, `cookie`, `set-cookie`, `x-api-key`, `api-key`, `api_key`,
+`access_token`, `refresh_token`, `password`, `secret`, `token`.
+
+Names match across naming styles, so `accessToken` in a message body is also hidden.
+
+Add your own fields with `sanitize_keys`. A key without separators is treated as a field name
+and masked at every depth; a key with a dot, star, or brackets is treated as a path
+[glom](https://glom.readthedocs.io/en/latest/):
+
+```python
+with_structlogger(
+    logger,
+    sanitize_keys=["x-tenant-key", "user.internal_id", "items.*.card_number"],
+)
+```
+
+Disable the default list explicitly with `use_default_sanitize_keys=False`.
+
+Masking leaves the original message unchanged: `****` appears only in the log.
+
+The `details` field, containing service error text, is neither masked nor truncated: it is free text,
+while masking works with field names and paths. If the service puts confidential information
+in the status, it appears in the log unchanged. The standard `options.with_logger` behaves the same way.
+
+## Parameters
+
+| Parameter | Type | Purpose |
+|---|---|---|
+| `logger` | `BoundLogger \| FilteringBoundLogger` | where to write |
+| `sanitize_keys` | `Sequence[str] \| None` | field names and glom paths whose values are replaced with `****` |
+| `json_indent` | `int \| None` | indentation width for JSON properties |
+| `log_level` | `int \| None` | level for successful records; `INFO` by default |
+| `err_log_level` | `int \| None` | level for failed calls; `ERROR` by default |
+| `payload_maxlength` | `int \| None` | maximum logged body length; 4096 characters by default |
+| `use_default_sanitize_keys` | `bool` | mask common secrets at every depth; `True` by default |
+
+Set levels, indentation, and body length limits for the whole project with
+`grpc_client.configure_logging(...)`. Values passed to `with_structlogger` override shared settings.
+
+`GRPC_CLIENT_*` environment variables have no effect on their own: `configure_logging(...)` reads them
+when called. Without that call, the library defaults remain in effect.
+
+`log_level` and `err_log_level` accept only `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL`:
+structlog's bound logger selects a method by level name, and only these five names are available.
+An intermediate value such as `15` raises `ValueError` immediately, rather than on the first request.
+
+structlog filters levels itself: if the logger threshold is above `log_level`, the record does not
+reach the output and the option may appear broken.
+
+## Development
+
+The library is developed in the [qa-libraries](https://github.com/cloud-ru-tech/qa-libraries) monorepo
+alongside the other `cloudru-qa-*` libraries. You need [`uv`](https://docs.astral.sh/uv/), GNU Make,
+and [`checkmake`](https://github.com/checkmake/checkmake).
+Run commands from the repository root:
+
+```shell
+make sync                               # install dependencies for all libraries from uv.lock
+make test-grpc-client-structlog         # tests for this library
+make typecheck-grpc-client-structlog    # mypy for this library
+make check                              # formatting, ruff, mypy, and tests for the entire workspace
+```
+
+Tests require Docker running: the gRPC service starts in a container from `tests/docker-compose.yml`,
+and its image is built on the first run. If the service is already running, skip starting the container
+by passing its address:
+
+```shell
+uv run --no-sync python packages/grpc-client-structlog/tests/service.py &
+SERVICE_ADDR=localhost:50051 make test-grpc-client-structlog
+```
+
+Tests run on Python 3.13 and 3.14. Create a separate environment for another version:
+`make sync test-grpc-client-structlog PYTHON_VERSION=3.14`.
+
+Publish a release with the git tag `grpc-client-structlog/v<version>`. The tag version must match
+the version in `packages/grpc-client-structlog/pyproject.toml`.

cloudru_qa_grpc_client_structlog-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+grpc_client_structlog/__init__.py,sha256=JFrlU8OlVVPWgB-8J_Zv4m7oTWzWMBlv7q3GHBqpusU,71
+grpc_client_structlog/option.py,sha256=p_KehH3o0YV3o1VvhXIzY54iVMXo5CfcEgiAEFVbIio,3084
+grpc_client_structlog/parser.py,sha256=OH62a-fTJfcu1IVk9ydhxdkXe1SXS9KJxbcmvML1rcs,6201
+grpc_client_structlog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+grpc_client_structlog/sink.py,sha256=nuIUyI7z8FoLbqH1P_NaUH55LOO_WFt3PaKjihTEI7M,4251
+grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/SKILL.md,sha256=z2QNgfshblmWVg_36HxS6p0lpDwb7xcMTmAhkPVtssA,9250
+grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/references/fields.md,sha256=D5WeyqbIJ9UErXly-2dEW73EH_YQXVTepOWUgecEwog,7466
+grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/references/pitfalls.md,sha256=NRHOIKOB88Dv-Yn1VinP1TN0YqgBIO8jS-Jh1aNz_rM,9804
+cloudru_qa_grpc_client_structlog-1.0.0.dist-info/METADATA,sha256=pOgz1IrDDr8gtp7eWzA7JZeH-qnaJV6o3eXW1YKuZ24,10416
+cloudru_qa_grpc_client_structlog-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cloudru_qa_grpc_client_structlog-1.0.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cloudru_qa_grpc_client_structlog-1.0.0.dist-info/RECORD,,

cloudru_qa_grpc_client_structlog-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudru_qa_grpc_client_structlog-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: grpc-client-structlog-usage
+description: Structured request/response logging for the grpc_client library — the with_structlogger option that writes every gRPC call into structlog as separate fields instead of one text line, with secret masking on by default. Use when a project imports grpc_client_structlog, when wiring structlog into a gRPC client, or when the built-in options.with_logger crashes with "object has no attribute 'isEnabledFor'". Key names are with_structlogger, sanitize_keys, use_default_sanitize_keys, status_code, messages_count, trace_id.
+license: Apache-2.0
+metadata:
+  library-version: "1.0.0"
+  source: packages/grpc-client-structlog
+---
+
+# Structured logging for grpc_client
+
+The library exports exactly one name: `with_structlogger`. It is a `ClientOption` that replaces
+`grpc_client.options.with_logger`. Instead of one text line per call, every attribute — method, body,
+metadata, status — becomes its own [structlog](https://www.structlog.org) field, so logs can be
+filtered and searched by field rather than by substring.
+
+Everything else — building the client, stubs, timeouts, auth, streaming — is plain `grpc_client`.
+This library adds no client of its own and no way to log outside of the option.
+
+## Hard rules
+
+1. Install **one** logging option. `with_structlogger` and `options.with_logger` each add their own
+   interceptor; passing both logs every call twice, in two different formats.
+2. Pass it as a constructor option, exactly like the built-in ones. There is no post-construction setup.
+3. Put it **after** `options.with_auth(...)` so the log shows the request that actually goes out.
+4. The library plugs into `options.with_log_sink` and the record types of `grpc_client`; the matching
+   `cloudru-qa-grpc-client` is installed as a dependency.
+5. Do not name a structlog field `message` anywhere in the pipeline: this library calls the payload
+   `body` on purpose, because `EventRenamer("message")` would collide with it.
+6. Do not turn off `use_default_sanitize_keys` to "clean up" the log. It unmasks passwords and tokens.
+7. Levels are limited to `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. Anything else raises
+   `ValueError` when the client is built — structlog cannot write an unnamed level.
+
+Before debugging odd output, read `references/pitfalls.md` — it covers the non-obvious behaviour.
+
+## Why it exists
+
+`options.with_logger` takes a stdlib logger and writes one text line per call. Feeding it a structlog
+bound logger does not work: it checks the level with `logger.isEnabledFor(level)`, and a logger built
+by `structlog.make_filtering_bound_logger(...)` spells that method `is_enabled_for`, so every call dies
+with:
+
+```
+AttributeError: 'BoundLoggerFilteringAtDebug' object has no attribute 'isEnabledFor'.
+Did you mean: 'is_enabled_for'?
+```
+
+`with_structlogger` installs a `LogSink` instead — the public extension point of `grpc-client` 2.1.
+The client builds a `RequestRecord` / `ResponseRecord` and picks the level; the sink turns it into
+structlog fields. The level question goes through `is_enabled_for`, and a logger that cannot answer
+it — the method is missing, or it raises, as `structlog.stdlib.BoundLogger` over a
+`structlog.PrintLogger` does — counts as enabled. A question about the level must never take the
+call down.
+
+## Usage
+
+```python
+import structlog
+from api import orders_pb2, orders_pb2_grpc
+from grpc_client import GRPCClient
+from grpc_client_structlog import with_structlogger
+
+
+class OrdersClient(GRPCClient[orders_pb2_grpc.OrdersStub]):
+    @property
+    def stub_class(self) -> type[orders_pb2_grpc.OrdersStub]:
+        return orders_pb2_grpc.OrdersStub
+
+    def get_order(self, order_id: str):
+        return self.send_unary_unary_request(orders_pb2.GetOrderRequest(id=order_id), self.stub.GetOrder)
+
+
+with OrdersClient.from_addr(
+    "orders.example.com:443",
+    with_structlogger(structlog.get_logger("orders")),
+) as client:
+    client.get_order("42")
+```
+
+Combines with any other option:
+
+```python
+from grpc_client import options
+
+client = OrdersClient.from_addr(
+    "orders.example.com:443",
+    options.with_auth(auth),
+    options.with_timeout(30),
+    with_structlogger(logger, json_indent=2),
+)
+```
+
+## Async client
+
+Same option, same arguments. The sync or async interceptor is picked from the client type inside the
+option, so nothing extra is configured:
+
+```python
+from grpc_client import AsyncGRPCClient
+
+
+class AsyncOrdersClient(AsyncGRPCClient[orders_pb2_grpc.OrdersStub]):
+    @property
+    def stub_class(self) -> type[orders_pb2_grpc.OrdersStub]:
+        return orders_pb2_grpc.OrdersStub
+
+    async def get_order(self, order_id: str):
+        return await self.send_unary_unary_request(orders_pb2.GetOrderRequest(id=order_id), self.stub.GetOrder)
+
+
+async with AsyncOrdersClient.from_addr("orders.example.com:443", with_structlogger(logger)) as client:
+    await client.get_order("42")
+```
+
+The final record of a response stream is written by a separate task, so an async client must be
+closed — `close()` waits for those tasks. `async with` does it for you.
+
+## What lands in the log
+
+Up to two events per call, linked by `trace_id` — a level filtered out by structlog simply produces no
+record, so a call can end up with one or none:
+
+| Field | Event | Value |
+|---|---|---|
+| `event` | both | `grpc request sent` / `grpc response received` |
+| `method` | both | `/package.Service/Method` |
+| `body` | request always, response only on a successful unary answer | JSON string of the message; `<streamed content>` for a request stream |
+| `metadata` | both | JSON string; **absent** when the call carried no metadata |
+| `status_code` | response | status **name**: `OK`, `NOT_FOUND`, … |
+| `details` | response | the service's error text; present only on a failed call |
+| `messages_count` | response | number of messages read from a response stream |
+| `trace_id` | both | UUID4 generated per call |
+
+`status_code` holds the name, not the number: the name reads without a lookup table and filters
+cleanly, while `5 (NOT_FOUND)` would force substring queries. `messages_count` is the only integer
+field; other composite values are serialized to JSON strings. The full catalog is in
+`references/fields.md`.
+
+## Masking
+
+Fields whose **name** is a common secret — `authorization`, `cookie`, `token`, `password`, `api_key`
+and the rest of `grpc_client.utils.sanitizer.DEFAULT_SANITIZE_KEYS` — are replaced with `****` by
+default, **at any depth**, and regardless of naming style (`accessToken` matches `access_token`).
+
+Project-specific fields go into `sanitize_keys`. A key without separators is a **field name** masked
+at any depth; a key with a dot, a star or brackets is a [glom](https://glom.readthedocs.io/en/latest/)
+**path** applied as written:
+
+```python
+with_structlogger(logger, sanitize_keys=["x-tenant-key", "user.internal_id", "items.*.card_number"])
+```
+
+| Key | What it masks |
+|---|---|
+| `x-tenant-key` | a metadata key (metadata is flat, whole-key match, case-insensitive) |
+| `client_secret` | a body field with that name, at any depth |
+| `user.internal_id` | one nested body field |
+| `items.*.card_number` | a field in every array element |
+
+Masking never touches the message the caller receives — only the copy that goes into the log.
+
+## Parameters
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `logger` | `BoundLogger \| FilteringBoundLogger` | where to write |
+| `sanitize_keys` | `Sequence[str] \| None` | field names and glom paths replaced with `****` |
+| `json_indent` | `int \| None` | indent used when serializing JSON fields |
+| `log_level` | `int \| None` | level of a successful record, defaults to `INFO` |
+| `err_log_level` | `int \| None` | level of a failed record, defaults to `ERROR` |
+| `payload_maxlength` | `int \| None` | length limit for `body`, defaults to 4096 characters |
+| `use_default_sanitize_keys` | `bool` | mask common secret names at any depth, default `True` |
+
+Levels, indent and the body limit fall back to the global `grpc_client` settings when omitted — set
+them once for the whole project with `grpc_client.configure_logging(...)`. An argument passed to
+`with_structlogger` wins over the global value. The `GRPC_CLIENT_*` environment variables do nothing
+on their own: `configure_logging(...)` reads them when it is called, so a project that never calls it
+gets library defaults regardless of the environment.
+
+`log_level` and `err_log_level` accept **only** `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. A
+structlog bound logger picks its method by level name, and only those five have one. Anything else —
+including a value coming from `configure_logging(...)` — raises `ValueError` while the client is being
+built. The built-in `options.with_logger` accepts arbitrary integers; this is a deliberate divergence,
+because the alternative is a `KeyError` from inside structlog that also stops the request from going
+out at all.
+
+## References
+
+- `references/fields.md` — the field catalog, streaming behaviour, global defaults and env variables.
+- `references/pitfalls.md` — JSON strings vs nested values, the `message` field, level filtering,
+  typing of `logger`, and how the option plugs into `grpc-client`.

grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/references/fields.md

@@ -0,0 +1,161 @@
+# Field catalog and configuration
+
+Two records per gRPC call. Field sets differ; `method`, `metadata` and `trace_id` are shared.
+
+## Request — `grpc request sent`
+
+| Field | Type | Value |
+|---|---|---|
+| `method` | `str` | full method name, `/package.Service/Method` |
+| `body` | `str` | JSON object of the request message after masking |
+| `metadata` | `str` | JSON object of the request metadata; **absent** when there was none |
+| `trace_id` | `str` | UUID4 generated for this call |
+
+The record is written **before** the call goes out, so it exists even when the call never reaches the
+service.
+
+## Response — `grpc response received`
+
+The same event name covers a successful unary answer, a failed call, and the end of a response
+stream. Which fields appear tells them apart:
+
+| Field | Type | Present when |
+|---|---|---|
+| `method` | `str` | always |
+| `status_code` | `str` | always — the status **name**, e.g. `OK`, `DEADLINE_EXCEEDED` |
+| `body` | `str` | successful unary answer only |
+| `details` | `str` | failed call only; may be an empty string if the service said nothing |
+| `messages_count` | `int` | stream calls only, including a failed stream |
+| `metadata` | `str` | trailing metadata was non-empty |
+| `trace_id` | `str` | always — matches the request record |
+
+`messages_count` is the only integer field. Everything composite (`body`, `metadata`) is serialized
+into a JSON string, not passed as a nested dict.
+
+A successful record is written at `log_level` (default `INFO`), a failed one at `err_log_level`
+(default `ERROR`). "Failed" means any status other than `OK`, including `CANCELLED` after the caller
+cancelled the stream itself.
+
+## Streams
+
+The body of a stream never lands in the log — reading it for the sake of logging would change the
+behaviour of the call.
+
+| Call type | Request `body` | Response fields |
+|---|---|---|
+| unary-unary | the message | `body` |
+| unary-stream | the message | `messages_count` |
+| stream-unary | `<streamed content>` | `body` |
+| stream-stream | `<streamed content>` | `messages_count` |
+
+`messages_count` counts messages actually read by the caller. Two consequences:
+
+- a stream that is abandoned half-way logs the count read up to that point, with the status the call
+  ended on (usually `CANCELLED` or `DEADLINE_EXCEEDED`);
+- on the async client, messages taken with `call.read()` instead of async iteration bypass the
+  counter — `grpc.aio` reads them past the interceptor's wrapper. `AsyncGRPCStreamResponse` iterates,
+  so `collect()` and `async for` count correctly.
+
+The final stream record is written when the call finishes, not when the last message is read. On the
+async client that happens in a separate task, which `AsyncGRPCClient.close()` waits for.
+
+## Body rendering
+
+The message is converted with `MessageToDict(always_print_fields_with_no_presence=True)`, masked, and
+serialized with `ensure_ascii=False`. So field names appear in protobuf JSON style (`accessToken`, not
+`access_token`), and unset scalar fields appear with their default values.
+
+A protobuf `bytes` field is what `MessageToDict` makes of it — **Base64**, not text: `b"text"` is
+logged as `"dGV4dA=="`. The `<двоичные данные>` marker never appears in a body; it belongs to binary
+metadata values (`-bin` keys), which reach the JSON encoder as raw `bytes` and are decoded as UTF-8
+when they can be.
+
+Two failure modes replace the body:
+
+| `body` holds | Meaning |
+|---|---|
+| `<не удалось подготовить тело сообщения>` | conversion, masking or serialization raised |
+| `... <обрезано>` at the end | the JSON exceeded `payload_maxlength` (4096 characters by default) |
+
+Both constants live in `grpc_client.utils.logutils` (`PAYLOAD_UNAVAILABLE`, `TRUNCATION_SUFFIX`).
+A broken glom path in `sanitize_keys` is the usual cause of the first one — the request itself still
+goes out, because the log is built defensively.
+
+## Metadata rendering
+
+Metadata is masked, then grouped into a JSON object. A repeated key keeps all of its values as a
+list:
+
+```json
+{"x-region": ["ural", "siberia"], "authorization": "****"}
+```
+
+A dict would have kept only the last value, and the log would no longer match what was sent.
+The field is omitted entirely when there is no metadata — an empty JSON object is never written.
+
+## Masking mechanics
+
+One pass over the payload, driven by the merged key list (`sanitize_keys` plus, unless disabled,
+`DEFAULT_SANITIZE_KEYS`):
+
+| Key shape | Applies to | Matches |
+|---|---|---|
+| no separators (`password`) | body | a field with that name at **any** depth |
+| dot / star / brackets (`user.token`) | body | that glom path only |
+| any | metadata | the whole key, case-insensitive — metadata is flat, paths are not parsed |
+
+Name matching normalizes to snake_case, so `accessToken`, `AccessToken` and `access_token` all match
+`access_token`, and a composite name ending in a secret (`client_secret`, `user_password`) matches
+too. Substring matching is deliberately not used — it would mask a harmless `tokenizer`.
+
+Default names: `authorization`, `proxy-authorization`, `cookie`, `set-cookie`, `x-api-key`, `api-key`,
+`api_key`, `access_token`, `refresh_token`, `password`, `secret`, `token`.
+
+Name-based masking replaces the whole value, so a nested message under a field named `token`
+disappears entirely rather than being walked into. Traversal stops at 64 levels and replaces what is
+left with `<превышена глубина вложенности>` — a recursive structure must not take the call down with it.
+
+## Global defaults
+
+`log_level`, `err_log_level`, `json_indent` and the payload length limit fall back to
+`grpc_client.config.LOGGING_CONFIG` whenever they are not passed to `with_structlogger`. Fill that
+singleton once at startup:
+
+```python
+import logging
+
+from grpc_client import configure_logging
+
+configure_logging(
+    log_level=logging.DEBUG,
+    err_log_level=logging.WARNING,
+    json_indent=2,
+    payload_log_maxlength=4096,
+)
+```
+
+Only `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL` are accepted for the two levels, here and in
+`configure_logging(...)` alike — a level structlog has no name for raises `ValueError` when the client
+is built.
+
+Environment variables **override** the arguments of that function — but only while it runs. Nothing
+reads them on import, so a project that never calls `configure_logging(...)` gets library defaults no
+matter what the environment says:
+
+| Variable | Field | Used by this library |
+|---|---|---|
+| `GRPC_CLIENT_LOG_LEVEL` | `log_level` | yes |
+| `GRPC_CLIENT_ERR_LOG_LEVEL` | `err_log_level` | yes |
+| `GRPC_CLIENT_JSON_INDENT` | `json_indent` | yes |
+| `GRPC_CLIENT_PAYLOAD_LOG_MAXLENGTH` | `payload_log_maxlength` | yes — argument `payload_maxlength` |
+| `GRPC_CLIENT_USE_LINE_BREAKS` | `use_line_breaks` | no — text-log only setting |
+
+Precedence: argument of `with_structlogger` → env variable → `configure_logging` argument → library
+default (the middle two only apply once `configure_logging(...)` has run). `use_line_breaks` is the only setting with no counterpart here — this library never joins
+fields into one line.
+
+## Event names
+
+`grpc request sent` and `grpc response received`, exported as `sink.REQUEST_EVENT` and
+`sink.RESPONSE_EVENT`. They are not part of the public API (`__init__` exports
+`with_structlogger` only) — filter by them in log queries, but do not import them into production code.

grpc_client_structlog/.agents/skills/grpc-client-structlog-usage/references/pitfalls.md

@@ -0,0 +1,176 @@
+# Pitfalls
+
+Non-obvious behaviour that costs time when you hit it unprepared.
+
+## The built-in option crashes on a filtering bound logger
+
+This is the whole reason the library exists. `grpc_client.options.with_logger` calls
+`logger.isEnabledFor(level)`. A logger from `structlog.configure(wrapper_class=structlog.make_filtering_bound_logger(...))`
+has `is_enabled_for` instead, so every call dies with:
+
+```
+AttributeError: 'BoundLoggerFilteringAtDebug' object has no attribute 'isEnabledFor'
+```
+
+`with_structlogger` asks through `is_enabled_for` and falls back to "enabled" when the logger cannot
+answer. "Cannot answer" covers two cases: the method is absent, and the method **raises**. The second
+one is real — `structlog.stdlib.BoundLogger` declares both spellings but forwards them to the logger
+underneath, so
+`structlog.configure(wrapper_class=structlog.stdlib.BoundLogger, logger_factory=structlog.PrintLoggerFactory())`
+gives a logger that writes fine and explodes on the level question. Under the built-in option that
+combination kills every call.
+
+The check itself is not optional: building the body means `MessageToDict` plus masking plus
+`json.dumps`, and doing that for a record nobody will keep is wasteful.
+
+What is **not** guarded is the write itself. If the structlog processor chain raises, the exception
+comes out of the call — unlike stdlib `logging`, structlog does not swallow errors of its own
+pipeline, and hiding them would mean losing every record silently.
+
+## The payload field is `body`, never `message`
+
+Many pipelines end with `structlog.processors.EventRenamer("message")`, which moves `event` into
+`message`. A field of the library's own named `message` would be overwritten by the event text and
+disappear. So the payload is `body`, matching `http_client_structlog`. Do not rename it back.
+
+## Composite fields are JSON strings, not nested values
+
+`body` and `metadata` reach structlog already serialized. In a console renderer that reads fine; under
+`JSONRenderer` the field is a string with escaped quotes inside the outer JSON:
+
+```json
+{"event": "grpc request sent", "body": "{\"login\": \"morgan\"}"}
+```
+
+This is deliberate — nested structures would collide with field names of the surrounding application
+context and would explode the index of a log store. If a collector must see the body as an object,
+parse that string in a structlog processor of your own.
+
+Consequence for `json_indent`: it puts real newlines inside those strings. Useful when a human reads
+the console, harmful for a line-based collector — leave it unset in production.
+
+## structlog does its own level filtering
+
+`log_level` is just the level handed to `.log()`. If structlog (or the stdlib logging behind it) is
+configured above that level, the record is dropped and the option looks broken. Lowering `log_level`
+to `DEBUG` requires lowering the structlog threshold as well.
+
+When **both** `log_level` and `err_log_level` are filtered out, the interceptor skips everything —
+it does not even generate a `trace_id` or wrap the stream for counting.
+
+## Only five log levels exist
+
+`logging` lets you invent levels — `logger.log(15, ...)` is fine, and `options.with_logger` passes it
+through. structlog does not: a bound logger maps the level to a method **name**, and only
+`DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` have one. Both `structlog.stdlib.BoundLogger` and
+the classes from `make_filtering_bound_logger` raise `KeyError: 15`.
+
+So `with_structlogger` validates the two levels while the client is built and raises `ValueError`
+instead. The check runs on the **resolved** values, so a bad level in
+`grpc_client.configure_logging(...)` or in `GRPC_CLIENT_LOG_LEVEL` is caught too. Without it the
+failure would land on the first RPC, during the request record — before the call goes out, so the
+request would never be sent.
+
+## `details` is the one field that is never masked
+
+`body` and `metadata` go through the sanitizer. `details` — the service's error text — does not, and
+`payload_maxlength` does not trim it either. It is a free-form string, and masking matches field names
+and glom paths, so there is nothing to match on. `sanitize_keys=["details"]` does **not** help: that
+list applies inside the payload, not to the record's own fields.
+
+A service that does `context.abort(INVALID_ARGUMENT, f"bad token {token}")` leaks it. The built-in
+`options.with_logger` behaves identically, so this is not a regression — but it is the one channel
+where a secret reaches the log untouched.
+
+## The final record of an unread sync stream comes from a grpcio thread
+
+`_CountingCall` registers the finish log through grpcio's `add_done_callback`. When the caller is not
+sitting inside `next()` — the stream was abandoned, hit its deadline, or the channel closed — grpcio
+runs that callback on one of its **own** threads, and the record is written there. So the processor
+chain and the sink get called from a thread the application never set up: they have to be thread-safe.
+
+`structlog.contextvars` do survive that hop — verified on grpcio 1.83 for an abandoned stream, an
+expired deadline, and a context bound in a worker thread: the finish record carried the same
+`request_id` as the request record, even though a plain `threading.Thread` sees no contextvars at all.
+Do not rely on it blindly across grpcio upgrades, but it is not a known hole today.
+
+## Two logging options log everything twice
+
+`with_structlogger` and `options.with_logger` each append their own interceptor and neither is aware
+of the other. Both installed means two records per call in two different formats. Pick one.
+
+## Order matters relative to auth
+
+Interceptors run in the order they are added. Put `with_structlogger` **after**
+`options.with_auth(...)`, otherwise the logged metadata is the request before the token was injected.
+
+## `logger` accepts both bound logger flavours
+
+The parameter type is `structlog.stdlib.BoundLogger | structlog.typing.FilteringBoundLogger`. The two
+are not interchangeable for a type checker — the stdlib one spells the level check `getEffectiveLevel`
+and the filtering protocol spells it `get_effective_level` — so neither alone would accept the other,
+hence the union. At runtime the option only calls `.log(level, event, **fields)` and
+`is_enabled_for(level)`, which any bound logger provides; a logger built by some other wrapper class
+still works, it just needs a `cast` to type-check.
+
+## The counter and the async client
+
+`messages_count` counts what the caller actually read. On the async client, `call.read()` goes past
+the interceptor's wrapper, so those messages are not counted; async iteration (`async for`,
+`AsyncGRPCStreamResponse.collect()`) is counted correctly.
+
+## The async stream record arrives after the call, not after the last message
+
+It is written by a task scheduled from the call's completion callback. Assert on it only after
+`await client.close()` (or after leaving `async with`), which drains those tasks. A test that checks
+the stream record right after `collect()` is racy.
+
+## Masking never touches the message the caller receives
+
+Every masking pass builds a copy. The response message still holds the real values — `****` exists
+only in the log. Do not use the option as a way to strip secrets out of a payload.
+
+## `sanitize_keys` mixes two mechanisms
+
+A key without separators is a **name** matched at any depth; a key with a dot, star or brackets is an
+exact **glom path**. `password` masks the field everywhere, `user.password` masks exactly one place.
+For metadata neither applies literally: metadata is flat, so the whole key is compared,
+case-insensitively, and a glom-looking key is matched as a plain key name.
+
+A path that matches nothing is skipped silently, so a typo shows up as an unmasked field, not as an
+error.
+
+## A broken glom path costs the whole body
+
+Unlike `http_client_structlog`, where each field is protected separately, the gRPC body is one unit:
+if masking or serialization raises, `body` becomes `<не удалось подготовить тело сообщения>` and no
+part of the payload is logged. The call itself still goes out — the log is built defensively, so a
+logging failure never breaks a request. `metadata` is unaffected and stays correct.
+
+## How the option plugs into grpc-client
+
+`with_structlogger` installs `StructlogSink` through `options.with_log_sink` — the public extension
+point added in `grpc-client` 2.1. Nothing here subclasses an interceptor.
+
+The split is: `grpc-client` decides **what happened** — it intercepts all four call types, wraps
+response streams to count messages, reads the outcome, builds a `RequestRecord` / `ResponseRecord`
+and picks the level. `StructlogSink` decides **how it is written** — masking, JSON serialization,
+truncation, and the field names.
+
+`ResponseRecord` covers three outcomes with one shape, and the sink tells them apart the same way
+the built-in `TextLogSink` does:
+
+| Outcome | `status_code` | `message` | `messages_count` | Parser used |
+|---|---|---|---|---|
+| unary success | `OK` | the response | `None` | `parse_response` |
+| stream finished | `OK` | `None` | count | `parse_stream_response` |
+| any failure | the error code | `None` | count for streams, `None` for unary | `parse_error` |
+
+Everything the sink uses is public: `RequestRecord` / `ResponseRecord` / `resolve_log_levels` from
+`grpc_client`, `sanitize` / `sanitize_metadata` from `grpc_client.utils.sanitizer`, and
+`LogFormat` / `BytesEncoder` / the marker constants from `grpc_client.utils.logutils`.
+
+## Only `with_structlogger` is public API
+
+`__init__` exports that one name. `sink`, `parser` and the constants inside them are internal
+and can move. Filter logs by the event strings if you must, but do not import them.

grpc_client_structlog/__init__.py

@@ -0,0 +1,3 @@
+from .option import with_structlogger
+
+__all__ = ["with_structlogger"]

grpc_client_structlog/option.py

@@ -0,0 +1,62 @@
+from collections.abc import Sequence
+from typing import TypedDict, Unpack
+
+from grpc_client import BaseGRPCClient, ClientOption, options, resolve_log_levels
+from grpc_client.utils.logutils import LogFormat
+
+from .sink import StructLogger, StructlogSink, check_supported_level
+
+
+class StructLoggerOptions(TypedDict, total=False):
+    """Structured logging options."""
+
+    sanitize_keys: Sequence[str] | None
+    json_indent: int | None
+    log_level: int | None
+    err_log_level: int | None
+    payload_maxlength: int | None
+    use_default_sanitize_keys: bool
+
+
+def with_structlogger(logger: StructLogger, **settings: Unpack[StructLoggerOptions]) -> ClientOption:
+    """Set a structured logger for gRPC client requests and responses.
+
+    :param logger: structured logger
+    :param sanitize_keys: metadata key names and paths in the format
+                          [glom](https://glom.readthedocs.io/en/latest/) in the message body,
+                          whose values should be hidden
+    :param json_indent: indentation width for JSON property logging (defaults to no indentation)
+    :param log_level: gRPC client logging level, defaults to INFO;
+                      structlog accepts only DEBUG, INFO, WARNING, ERROR, and CRITICAL
+    :param err_log_level: failed request logging level, defaults to ERROR;
+                          the allowed values are the same
+    :param payload_maxlength: maximum logged message body length, defaults to 4096 characters;
+                              `None` in `grpc_client.configure_logging` removes the limit
+    :param use_default_sanitize_keys: whether to hide fields with common secret names
+                                      (see `grpc_client.utils.sanitizer.DEFAULT_SANITIZE_KEYS`)
+                                      at any depth, in addition to `sanitize_keys`
+    :returns: option applied to a gRPC client to set its logger
+    :raises ValueError: when building the client if structlog does not support the logging level
+    """
+
+    def option(client: BaseGRPCClient[object]) -> None:
+        # Read shared settings when building the client rather than creating the option:
+        # `grpc_client.configure_logging` may have been called after the option was created.
+        levels = resolve_log_levels(settings.get("log_level"), settings.get("err_log_level"))
+        # Check the resolved level: unsupported values can come
+        # both from an argument and from `configure_logging`.
+        check_supported_level("log_level", levels[0])
+        check_supported_level("err_log_level", levels[1])
+
+        sink = StructlogSink(
+            logger=logger,
+            log_format=LogFormat.from_config(
+                sanitize_keys=settings.get("sanitize_keys"),
+                json_indent=settings.get("json_indent"),
+                payload_maxlength=settings.get("payload_maxlength"),
+                use_default_sanitize_keys=settings.get("use_default_sanitize_keys", True),
+            ),
+        )
+        options.with_log_sink(sink, log_level=levels[0], err_log_level=levels[1])(client)
+
+    return option

grpc_client_structlog/parser.py

@@ -0,0 +1,156 @@
+import json
+import logging
+from typing import cast
+
+from google.protobuf.json_format import MessageToDict
+from google.protobuf.message import Message
+from grpc_client import RequestRecord, ResponseRecord
+from grpc_client.types import MetadataType
+from grpc_client.utils.logutils import PAYLOAD_UNAVAILABLE, TRUNCATION_SUFFIX, BytesEncoder, LogFormat
+from grpc_client.utils.sanitizer import sanitize, sanitize_metadata
+
+_logger = logging.getLogger(__name__)
+
+# `body` field value when the request body is a message stream.
+STREAMED_CONTENT = "<streamed content>"
+
+# `status_code` contains the code name rather than its number: names need no reference lookup,
+# and make filtering convenient. A number would add a second value to the field,
+# whereas searching for `2 (UNKNOWN)` would require substring matching.
+
+# `trace_id` is appended last to every record rather than set with the other fields:
+# renderers that preserve insertion order (such as `structlog.processors.JSONRenderer`)
+# output fields in this order, and the internal identifier must not split the call data.
+
+
+def parse_request(record: RequestRecord, log_format: LogFormat) -> dict[str, object]:
+    """Build structured log fields for a sent gRPC request.
+
+    :param record: request data
+    :param log_format: log formatting rules
+    :returns: structured request log fields
+    """
+    properties: dict[str, object] = {
+        "method": record.method,
+        "body": _parse_body(record.message, log_format) if record.message is not None else STREAMED_CONTENT,
+    }
+    if (metadata_field := _parse_metadata(record.metadata, log_format)) is not None:
+        properties["metadata"] = metadata_field
+
+    properties["trace_id"] = record.trace_id
+    return properties
+
+
+def parse_response(record: ResponseRecord, log_format: LogFormat) -> dict[str, object]:
+    """Build structured log fields for a received gRPC response.
+
+    :param record: completed call data
+    :param log_format: log formatting rules
+    :returns: structured response log fields
+    """
+    properties: dict[str, object] = {"method": record.method, "status_code": record.status_code.name}
+    if record.message is not None:
+        properties["body"] = _parse_body(record.message, log_format)
+    if (metadata_field := _parse_metadata(record.metadata, log_format)) is not None:
+        properties["metadata"] = metadata_field
+
+    properties["trace_id"] = record.trace_id
+    return properties
+
+
+def parse_stream_response(record: ResponseRecord, log_format: LogFormat) -> dict[str, object]:
+    """Build structured log fields for a completed response message stream.
+
+    Messages themselves are not logged: a stream may be arbitrarily long, and reading it
+    for logging would change call behavior.
+
+    :param record: completed stream data
+    :param log_format: log formatting rules
+    :returns: structured log fields for the completed stream
+    """
+    properties: dict[str, object] = {
+        "method": record.method,
+        "status_code": record.status_code.name,
+        "messages_count": record.messages_count,
+    }
+    if (metadata_field := _parse_metadata(record.metadata, log_format)) is not None:
+        properties["metadata"] = metadata_field
+
+    properties["trace_id"] = record.trace_id
+    return properties
+
+
+def parse_error(record: ResponseRecord, log_format: LogFormat) -> dict[str, object]:
+    """Build structured log fields for a failed call.
+
+    :param record: completed call data
+    :param log_format: log formatting rules
+    :returns: structured error log fields
+    """
+    properties: dict[str, object] = {
+        "method": record.method,
+        "status_code": record.status_code.name,
+        "details": record.details,
+    }
+    if record.messages_count is not None:
+        properties["messages_count"] = record.messages_count
+    if (metadata_field := _parse_metadata(record.metadata, log_format)) is not None:
+        properties["metadata"] = metadata_field
+
+    properties["trace_id"] = record.trace_id
+    return properties
+
+
+def _parse_metadata(metadata: MetadataType | None, log_format: LogFormat) -> str | None:
+    """Build the metadata field value.
+
+    Repeated key values are collected in a list: a regular dictionary would retain
+    only the last value and make the log differ from the sent metadata.
+
+    :param metadata: request or response metadata
+    :param log_format: log formatting rules
+    :returns: metadata as JSON, or None if absent
+    """
+    items = sanitize_metadata(metadata, log_format.sanitize_keys)
+    if not items:
+        return None
+
+    grouped: dict[str, object] = {}
+    for name, value in items:
+        if name not in grouped:
+            grouped[name] = value
+        elif isinstance(previous := grouped[name], list):
+            cast("list[object]", previous).append(value)
+        else:
+            grouped[name] = [grouped[name], value]
+
+    return _to_json(grouped, log_format.json_indent)
+
+
+def _parse_body(message: Message, log_format: LogFormat) -> str:
+    """Build the message body field value.
+
+    A log preparation error must not block requests: logs are built before sending, and a failure
+    here, for example on a deeply nested message, would break the call itself.
+
+    :param message: request or response message
+    :param log_format: log formatting rules
+    :returns: message body as JSON or a marker for an unavailable body
+    """
+    try:
+        payload = cast("dict[str, object]", MessageToDict(message, always_print_fields_with_no_presence=True))
+        masked = sanitize(payload, log_format.sanitize_keys)
+        return _truncate(_to_json(masked, log_format.json_indent), log_format.payload_maxlength)
+    except Exception:
+        _logger.warning("Не удалось подготовить тело сообщения gRPC", exc_info=True)
+        return PAYLOAD_UNAVAILABLE
+
+
+def _to_json(value: dict[str, object], indent: int | None) -> str:
+    return json.dumps(value, indent=indent, ensure_ascii=False, cls=cast("type[json.JSONEncoder]", BytesEncoder))
+
+
+def _truncate(value: str, maxlength: int | None) -> str:
+    if maxlength is None or len(value) <= maxlength:
+        return value
+    return value[:maxlength] + TRUNCATION_SUFFIX

grpc_client_structlog/sink.py

@@ -0,0 +1,95 @@
+import logging
+
+import grpc
+from grpc_client import RequestRecord, ResponseRecord
+from grpc_client.utils.logutils import LogFormat
+from structlog.stdlib import BoundLogger
+from structlog.typing import FilteringBoundLogger
+
+from .parser import parse_error, parse_request, parse_response, parse_stream_response
+
+# Structlog bound logger: stdlib-based or a class from `make_filtering_bound_logger`.
+# The second does not fit the first: its level check methods have different names.
+StructLogger = BoundLogger | FilteringBoundLogger
+
+# Sent request event.
+REQUEST_EVENT = "grpc request sent"
+
+# Received response event: success, failure, or stream completion.
+RESPONSE_EVENT = "grpc response received"
+
+# Levels supported by structlog.
+#
+# A stdlib logger accepts any number, while a structlog bound logger selects a method by level name,
+# and only these five levels have names. A stdlib logger would write an intermediate value such as 15,
+# but structlog raises `KeyError`.
+SUPPORTED_LOG_LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
+
+
+class StructlogSink:
+    """Sink that writes gRPC call records to structlog as separate fields."""
+
+    def __init__(self, logger: StructLogger, log_format: LogFormat | None = None) -> None:
+        """Initialize the object.
+
+        :param logger: structured logger used for requests and responses
+        :param log_format: log formatting rules, defaults to shared configuration
+        """
+        self._logger = logger
+        self._format = log_format if log_format is not None else LogFormat.from_config()
+
+    def is_enabled_for(self, level: int) -> bool:
+        """Check whether the logger writes records at the specified level.
+
+        The check may fail: users set the bound logger class in `structlog.configure`,
+        and `structlog.stdlib.BoundLogger`, for example, delegates the query to its underlying logger,
+        while `structlog.PrintLogger` cannot answer it. Treat such a logger as enabled:
+        silently losing records is worse than building an extra one, and breaking the
+        call itself over this query is even worse.
+
+        :param level: record level
+        :returns: True if a record at this level reaches output
+        """
+        try:
+            return self._logger.is_enabled_for(level)
+        except Exception:  # noqa: BLE001 - a broken check must not break the call
+            return True
+
+    def write_request(self, level: int, record: RequestRecord) -> None:
+        """Log a sent request."""
+        self._write(level, REQUEST_EVENT, parse_request(record, self._format))
+
+    def write_response(self, level: int, record: ResponseRecord) -> None:
+        """Log a completed call."""
+        self._write(level, RESPONSE_EVENT, self._response_properties(record))
+
+    def _response_properties(self, record: ResponseRecord) -> dict[str, object]:
+        """Build log fields suitable for the call outcome."""
+        if record.status_code is not grpc.StatusCode.OK:
+            return parse_error(record, self._format)
+        if record.messages_count is not None:
+            return parse_stream_response(record, self._format)
+        return parse_response(record, self._format)
+
+    def _write(self, level: int, event: str, properties: dict[str, object]) -> None:
+        """Write an event with fields to the structured logger."""
+        self._logger.log(level, event, **properties)
+
+
+def check_supported_level(name: str, level: int) -> None:
+    """Check whether structlog supports writing at this level.
+
+    Validate when building the client rather than on the first request: otherwise a logging
+    level typo becomes a `KeyError` inside structlog before the request is even sent;
+    its record is built before the call.
+
+    :param name: name of the parameter that supplied the level
+    :param level: level to check
+    :raises ValueError: if the level is not in `SUPPORTED_LOG_LEVELS`
+    """
+    if level in SUPPORTED_LOG_LEVELS:
+        return
+
+    supported = ", ".join(f"{logging.getLevelName(value)} ({value})" for value in SUPPORTED_LOG_LEVELS)
+    message = f"structlog не умеет писать уровнем {level}: {name} принимает только {supported}"
+    raise ValueError(message)