judgevet.diagnostics
Status: draft.
judgevet.diagnostics
Scope caller correlation and filter built-in diagnostic metadata.
Context tokens restore previous bindings, including after exceptions and task cancellation. Importing this module does not configure logging. See https://docs.python.org/3/library/contextvars.html for context inheritance.
Examples:
from judgevet.diagnostics import bind_request_id, current_request_id
with bind_request_id("request-123"):
assert current_request_id() == "request-123"
assert current_request_id() is None
See Also
- judgevet.adapters.outbound.http_events: Terminal HTTP events.
- judgevet.adapters.inbound.logs: Configured event rendering.
bind_request_id(request_id)
Bind a non-sensitive caller identifier until this scope exits.
None temporarily clears correlation. Nested scopes restore the outer value. New asyncio tasks inherit their creation context; sibling bindings stay isolated. The identifier stays local unless GatewayConfig opts into HTTP propagation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_id
|
str | None
|
None or an ASCII identifier of at most 128 characters. |
required |
Yields:
| Type | Description |
|---|---|
None
|
None while the binding is active. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the identifier has an invalid type, length or character. |
Examples:
with bind_request_id("gateway-123"):
assert current_request_id() == "gateway-123"
current_request_id()
Read the dedicated correlation binding without arbitrary logging context.
Returns:
| Type | Description |
|---|---|
str | None
|
The current caller identifier, or None outside a binding. |
diagnostic_model(model)
Keep bounded Jev-shaped identifiers without changing API model values.
This is a logging filter, not upstream model validation. Callers must still keep sensitive values out of version-shaped identifiers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
str | None
|
Requested or successfully resolved model value. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The bounded identifier, or None for any other value. |
filter_event_fields(_logger, _method, event_dict)
Restrict built-in events after context merge; preserve application events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
_logger
|
Any
|
Unused wrapped logger. |
required |
_method
|
str
|
Unused severity method. |
required |
event_dict
|
dict[str, Any]
|
Event after configured context merging. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Allowed built-in metadata, or the unchanged application event. |