Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions asherah-py/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,17 +125,23 @@ asyncio.run(main())

### Log hook

Receive every log event from the Rust core (encrypt/decrypt path,
metastore drivers, KMS clients).
Receive log events from the Rust core (encrypt/decrypt path,
metastore drivers, KMS clients). Only `warn` and `error` events are
delivered unless you pass `min_level`: `"error"`, `"warn"` (or
`"warning"`), `"info"`, `"debug"` or `"trace"`, case-insensitive.
Omitting it or passing `None` means `"warn"`. Any other string raises
`ValueError` and a non-string (such as `logging.DEBUG`) raises
`TypeError`; the installed hook is left unchanged. The callback argument
is required: pass `None` to deregister.

```python
def on_log(event):
# event = {"level": "trace"|"debug"|"info"|"warn"|"error",
# "message": str, "target": str}
if event["level"] in ("warn", "error"):
print(f"[asherah {event['level']}] {event['message']}")
print(f"[asherah {event['level']}] {event['target']}: {event['message']}")

asherah.set_log_hook(on_log)
asherah.set_log_hook(on_log) # warn and error
asherah.set_log_hook(on_log, min_level="debug") # include debug and info

# later, to deregister:
asherah.set_log_hook(None)
Expand Down Expand Up @@ -300,7 +306,7 @@ behavior in an asyncio application.

| Function | Description |
|---|---|
| `set_log_hook(callback)` | Register a `(event_dict) -> None` log callback. Pass `None` to deregister. |
| `set_log_hook(callback, min_level="warn")` | Register a `(event_dict) -> None` log callback for events at or above `min_level`. Pass `None` to deregister. |
| `set_metrics_hook(callback)` | Register a `(event_dict) -> None` metrics callback. Pass `None` to deregister. |

### Factory / Session API (recommended)
Expand Down
3 changes: 2 additions & 1 deletion asherah-py/asherah/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@

Observability hooks are also exposed:

- :func:`set_log_hook` receives every log event from the Rust core.
- :func:`set_log_hook` receives log events from the Rust core at or above
``min_level`` (default ``"warn"``).
- :func:`set_metrics_hook` receives encrypt/decrypt timings and key cache
hit/miss/stale counters.

Expand Down
22 changes: 18 additions & 4 deletions asherah-py/asherah/_asherah.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -124,14 +124,28 @@ def set_metrics_hook(callback: Optional[Callable[[Any], None]] = ...) -> None:
callback, so the callback runs single-threaded from Python's
perspective."""

def set_log_hook(callback: Optional[Callable[[Any], None]] = ...) -> None:
"""Install a callback that receives every log event from the Rust
core (encrypt/decrypt path, metastore drivers, KMS clients).
def set_log_hook(
callback: Optional[Callable[[Any], None]], min_level: Optional[str] = ...
) -> None:
"""Install a callback that receives log events from the Rust core
(encrypt/decrypt path, metastore drivers, KMS clients) at or above
``min_level``.

``callback`` is required; pass ``None`` to deregister.

``min_level`` is one of ``"error"``, ``"warn"``, ``"warning"``,
``"info"``, ``"debug"``, ``"trace"``, case-insensitive; omitted or
``None`` means ``"warn"``. Any other string raises ``ValueError`` and
a non-string raises ``TypeError``; either way the current hook is left
unchanged. Records below the level are discarded before they are
formatted.

The callback receives a single ``dict`` argument with keys
``"level"`` (``"trace"|"debug"|"info"|"warn"|"error"``),
``"message"`` (the formatted log message), and ``"target"`` (the
source module string).
source module string). Events are queued and delivered on a
dedicated dispatch thread; when the queue is full, events are
dropped rather than blocking encrypt/decrypt.

Pass ``None`` to deregister."""

Expand Down
5 changes: 4 additions & 1 deletion asherah-py/docs/aws-production-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,10 @@ asherah.set_metrics_hook(on_metric)
The first encrypt produces:
- A row in `AsherahKeys` with `Id="_SK_payments"`.
- A row in `AsherahKeys` with `Id="_IK_<partition>_payments_checkout"`.
- A log event at `info` level reporting IK creation.
- With the log hook installed at `min_level="debug"`, a `debug` event
from `asherah::session` reporting IK creation
(`create_intermediate_key: id=_IK_<partition>_payments_checkout`). The
hook above uses the default level (`warn`), which does not deliver it.

Subsequent encrypts in the same partition reuse the cached IK — no
metastore round-trip — until expiry.
Expand Down
13 changes: 9 additions & 4 deletions asherah-py/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,10 +163,15 @@ asherah.set_metrics_hook(on_metric)
Hooks are process-global. `set_log_hook(None)` / `set_metrics_hook(None)`
deregister.

`set_log_hook_sync` and `set_metrics_hook_sync` variants fire on the
encrypt/decrypt thread before the operation returns — pick those if
you need contextvars / OpenTelemetry trace context intact in the
callback or have verifiably non-blocking handlers.
The log hook delivers `warn` and `error` events by default. Pass
`min_level` (`"error"`, `"warn"`, `"info"`, `"debug"` or `"trace"`) to
change that, e.g. `asherah.set_log_hook(on_log, min_level="debug")`.

Both hooks queue events and invoke the callback on a dedicated dispatch
thread, not on the encrypt/decrypt thread, so contextvars and
OpenTelemetry trace context from the calling code are not visible in
the callback. When the queue is full, events are dropped rather than
blocking the operation.

## 8. Move to production

Expand Down
4 changes: 3 additions & 1 deletion asherah-py/docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,9 @@ parallel test runners (pytest-xdist) race on hook state.
@pytest.mark.serial
def test_log_hook_fires(asherah_factory):
events = []
asherah.set_log_hook(events.append)
# The default level (warn) delivers nothing for a plain encrypt; the
# key loads and creations it performs are logged at debug.
asherah.set_log_hook(events.append, min_level="debug")
try:
with asherah_factory.get_session("p") as s:
s.encrypt_text("hello")
Expand Down
9 changes: 6 additions & 3 deletions asherah-py/docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,11 +206,14 @@ When a problem isn't covered above:
```python
def on_log(event):
print(f"[asherah {event['level']}] {event['target']}: {event['message']}")
asherah.set_log_hook(on_log)
asherah.set_log_hook(on_log, min_level="trace")
factory = asherah.SessionFactory.from_config(config)
```
The hook receives `warn` and `error` events; `info`, `debug` and
`trace` records are not delivered. An operation that fails in the
The log hook delivers only `warn` and `error` unless `min_level`
is lowered. At `debug`/`trace` it adds the session's key loads and
creations and metastore load/store calls. Records from other Rust
crates that log through the `log` facade are forwarded too; the AWS
SDK's internal diagnostics are not. An operation that fails in the
Rust core logs a `python binding operation failed: …` warn event
with the full error chain, and a failed KMS decrypt logs an
`asherah::kms_aws_envelope` error event that lists every attempted
Expand Down
54 changes: 50 additions & 4 deletions asherah-py/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ use asherah::metrics;
use asherah::metrics::{AsyncMetricsConfig, AsyncMetricsSink, MetricsSink};
use asherah_config as config;
use once_cell::sync::Lazy;
use pyo3::exceptions::PyRuntimeError;
use pyo3::exceptions::{PyRuntimeError, PyValueError};
use pyo3::prelude::*;
use pyo3::types::PyBytes;
use pyo3::types::PyDict;
Expand All @@ -35,6 +35,24 @@ type SessionHandle = ael::session::PublicSession<
const NATIVE_HOOK_QUEUE_CAPACITY: usize = 4096;
const DEFAULT_LOG_HOOK_MIN_LEVEL: log::LevelFilter = log::LevelFilter::Warn;

/// Resolve `set_log_hook`'s `min_level` argument (case-insensitive);
/// `None` selects the Warn default.
fn log_hook_min_level(name: Option<&str>) -> Result<log::LevelFilter, String> {
let Some(name) = name else {
return Ok(DEFAULT_LOG_HOOK_MIN_LEVEL);
};
match name.to_ascii_lowercase().as_str() {
"error" => Ok(log::LevelFilter::Error),
"warn" | "warning" => Ok(log::LevelFilter::Warn),
"info" => Ok(log::LevelFilter::Info),
"debug" => Ok(log::LevelFilter::Debug),
"trace" => Ok(log::LevelFilter::Trace),
_ => Err(format!(
"invalid min_level {name:?}: expected one of \"error\", \"warn\", \"warning\", \"info\", \"debug\", \"trace\""
)),
}
}

fn sanitized_anyhow_message(op: &str, err: &anyhow::Error) -> String {
format!("{op} failed: {err}")
}
Expand Down Expand Up @@ -597,11 +615,12 @@ impl MetricsSink for PyMetricsSink {

struct PyLogSink {
callback: Arc<Py<PyAny>>,
min_level: log::LevelFilter,
}

impl LogSink for PyLogSink {
fn min_level(&self) -> log::LevelFilter {
DEFAULT_LOG_HOOK_MIN_LEVEL
self.min_level
}

fn log(&self, record: &log::Record<'_>) {
Expand Down Expand Up @@ -661,18 +680,24 @@ fn set_metrics_hook(callback: Option<&Bound<'_, PyAny>>) -> PyResult<()> {
}

#[pyfunction]
fn set_log_hook(callback: Option<&Bound<'_, PyAny>>) -> PyResult<()> {
#[pyo3(
signature = (callback, min_level=None),
text_signature = "(callback, min_level='warn')"
)]
fn set_log_hook(callback: Option<&Bound<'_, PyAny>>, min_level: Option<&str>) -> PyResult<()> {
let min_level = log_hook_min_level(min_level).map_err(PyValueError::new_err)?;
ensure_logger().map_err(|e| PyRuntimeError::new_err(e.to_string()))?;
if let Some(cb) = callback {
let obj: Py<PyAny> = cb.clone().unbind();
let arc = Arc::new(obj);
let sink = AsyncLogSink::new(
PyLogSink {
callback: Arc::clone(&arc),
min_level,
},
AsyncLogConfig {
queue_capacity: NATIVE_HOOK_QUEUE_CAPACITY,
min_level: DEFAULT_LOG_HOOK_MIN_LEVEL,
min_level,
},
)
.map_err(|e| PyRuntimeError::new_err(format!("log hook dispatcher error: {e}")))?;
Expand Down Expand Up @@ -735,6 +760,27 @@ mod tests {
assert_eq!(DEFAULT_LOG_HOOK_MIN_LEVEL, log::LevelFilter::Warn);
}

#[test]
fn log_hook_min_level_parses_names_case_insensitively() {
use log::LevelFilter;
assert_eq!(log_hook_min_level(None), Ok(LevelFilter::Warn));
for (name, level) in [
("error", LevelFilter::Error),
("warn", LevelFilter::Warn),
("warning", LevelFilter::Warn),
("WARNING", LevelFilter::Warn),
("info", LevelFilter::Info),
("Debug", LevelFilter::Debug),
("TRACE", LevelFilter::Trace),
] {
assert_eq!(log_hook_min_level(Some(name)), Ok(level), "{name}");
}
for bad in ["", "verbose", "off", "warn ", "critical"] {
let err = log_hook_min_level(Some(bad)).unwrap_err();
assert!(err.contains("invalid min_level"), "{bad}: {err}");
}
}

#[test]
fn binding_limits_reject_oversize_inputs() {
assert!(check_plaintext_len_py(ael::limits::MAX_PAYLOAD_BYTES + 1).is_err());
Expand Down
75 changes: 75 additions & 0 deletions asherah-py/tests/test_hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
- registering hook AFTER setup is supported
- hooks fire under both module-level and Session API
- log event level is the lowercase name ("warn" not "WARN")
- log hook min_level: default delivers warn+ only, "debug" adds debug,
invalid names raise ValueError
- set_log_hook requires its callback argument; rejected calls leave the
installed hook in place
"""
from __future__ import annotations

Expand Down Expand Up @@ -290,3 +294,74 @@ def test_metrics_event_dict_shape():
elif e["type"] in ("cache_hit", "cache_miss", "cache_stale"):
assert "name" in e
assert isinstance(e["name"], str)


def test_log_hook_min_level_debug_delivers_debug_records():
"""The default hook level is warn; min_level="debug" adds debug records."""
import asherah

_configure_env()
default_events = []
asherah.set_log_hook(lambda e: default_events.append(e))
asherah.setup(_config())
# First encrypt for a partition loads/creates keys and logs at debug.
asherah.encrypt_string("lvl-default", "payload")
asherah.shutdown()
_wait_for_stable_len(default_events)
below_warn = [e for e in default_events if e["level"] not in ("warn", "error")]
assert below_warn == [], f"default hook received sub-warn events: {below_warn!r}"

debug_events = []
asherah.set_log_hook(lambda e: debug_events.append(e), min_level="debug")
asherah.setup(_config())
asherah.encrypt_string("lvl-debug", "payload")
asherah.shutdown()
assert _wait_for(lambda: any(e["level"] == "debug" for e in debug_events)), (
f"expected a debug event with min_level='debug', got {debug_events!r}"
)
_wait_for_stable_len(debug_events)
assert not any(e["level"] == "trace" for e in debug_events), (
"min_level='debug' must not deliver trace events"
)


def test_log_hook_invalid_min_level_raises_value_error():
import asherah

with pytest.raises(ValueError, match="min_level"):
asherah.set_log_hook(lambda e: None, min_level="verbose")
with pytest.raises(ValueError, match="min_level"):
asherah.set_log_hook(None, min_level="")
with pytest.raises(ValueError, match='"warning"'):
asherah.set_log_hook(None, min_level="critical")
# Level names are case-insensitive; "warning" is accepted. Passing
# None with a valid level deregisters (nothing is installed here).
asherah.set_log_hook(None, min_level="WARNING")
with pytest.raises(TypeError):
asherah.set_log_hook(None, min_level=10)


def test_log_hook_callback_is_required_and_rejected_calls_keep_the_hook():
import asherah

_configure_env()
with pytest.raises(TypeError):
asherah.set_log_hook()

events = []
asherah.set_log_hook(lambda e: events.append(e), min_level="debug")
# None of these may replace or remove the installed hook.
with pytest.raises(TypeError):
asherah.set_log_hook(min_level="debug")
with pytest.raises(ValueError):
asherah.set_log_hook(lambda e: None, min_level="verbose")
with pytest.raises(TypeError):
asherah.set_log_hook(lambda e: None, min_level=10)

asherah.setup(_config())
asherah.encrypt_string("still-hooked", "payload")
asherah.shutdown()
assert _wait_for(lambda: any(e["level"] == "debug" for e in events)), (
f"the installed debug hook stopped receiving events: {events!r}"
)
_wait_for_stable_len(events)
Loading