cloudru-qa-grpc-client-structlog 1.0.0__tar.gz

cloudru_qa_grpc_client_structlog-1.0.0/.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`.

cloudru_qa_grpc_client_structlog-1.0.0/.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.

cloudru_qa_grpc_client_structlog-1.0.0/.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.

cloudru_qa_grpc_client_structlog-1.0.0/.gitignore

@@ -0,0 +1,26 @@
+/docs/plans/
+.venv/
+.venvs/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+report*.xml
+allure-results/
+allure-report/
+.allure/
+logs/
+*.log
+.env
+.env.*
+.DS_Store
+dist/
+build/
+*.egg-info/
+/packages/*/api/
+.claude/settings.local.json