Skip to content
Open
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
28 changes: 10 additions & 18 deletions wiki/cascade-cms-wiki/docs/advanced/cpu-intensive.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ By default `.then()` callbacks run on the async event loop, which is fine for I/

## When to Use `ProcessPoolExecutor`

- Image resizing, compression, or optimization
- Parsing large XML/JSON structures or heavy data transformation
- Running intensive regular expressions across large HTML bodies
- Light callbacks like simple string replacements or metadata dictionary updates do not need it and perform better on the default thread pool or event loop.
- Image resizing, compression, or other pixel-level processing operations
- Heavy data transformations or bulk regex parsing on large HTML bodies
- Complex serialization or cryptographic hashing tasks
- Light callbacks (title string replace, metadata dict update) that don't need it and are faster on the default thread pool or main loop

---

Expand All @@ -18,18 +18,10 @@ By default `.then()` callbacks run on the async event loop, which is fine for I/
```python
from concurrent.futures import ProcessPoolExecutor
from os import cpu_count
from cascade_cms import Cascade

env = {"SERVER": "prod", "API_KEY": "secret", "CASCADE_URL": "https://cascade.example.com"}

def optimize_image(asset):
# CPU-bound image processing work here
return asset

with Cascade(env, {}) as cascade:
with ProcessPoolExecutor(max_workers=cpu_count()) as executor:
cascade.operations.read(id).then(optimize_image)
results = cascade.submit_requests(executor=executor)
with ProcessPoolExecutor(max_workers=cpu_count()) as executor:
cascade.operations.read(id).then(optimize_image)
results = cascade.submit_requests(executor=executor)
```

---
Expand Down Expand Up @@ -58,12 +50,12 @@ cascade.operations.read(id).then(transform)

## `ProcessPoolExecutor` vs `ThreadPoolExecutor`

`ProcessPoolExecutor` provides true parallelism across multiple CPU cores in separate memory spaces, but requires all callback functions and data to be picklable and incurs inter-process communication overhead. `ThreadPoolExecutor` uses shared memory with minimal overhead and no pickling restrictions, but remains limited by Python's Global Interpreter Lock (GIL) for CPU-bound tasks. Use `ProcessPoolExecutor` for heavy CPU computation, and stick with `ThreadPoolExecutor` (the default) for I/O-bound work.
`ProcessPoolExecutor` provides true parallelism across multiple CPU cores with separate memory spaces, but requires all callback functions and data to be picklable and incurs higher task-dispatch overhead. `ThreadPoolExecutor` (which is the default) shares memory and has lower overhead, but is still bound by the Global Interpreter Lock (GIL) and cannot achieve true parallelism for CPU-bound tasks. Use `ProcessPoolExecutor` for CPU-heavy workflows and `ThreadPoolExecutor` for I/O-bound work.

---

## Performance Considerations

Spawning and managing worker processes carries an initialization overhead, meaning extremely fast callbacks may run slower in a process pool than synchronously due to serialization costs. Additionally, offloading CPU work via the executor does not change the network concurrency rules; the driver's underlying `MAX_REQUESTS` semaphore still governs HTTP request limits.
Spawning worker processes has a measurable startup cost, so for very fast callbacks the inter-process communication and pickling overhead may outweigh the parallel execution benefit. Additionally, the driver's underlying request concurrency semaphore still governs HTTP operations independently of whatever executor is chosen for synchronous callback functions.

<!-- synthesized-for: 3.1.1 -->
<!-- synthesized-for: 3.9.2 -->
4 changes: 2 additions & 2 deletions wiki/cascade-cms-wiki/docs/advanced/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Advanced

Welcome to the advanced power user guide for tuning and scaling your application. This section covers configuration and performance topics that go beyond the defaults, including caching behavior, debug logging, and CPU-intensive callback patterns.
Welcome to the advanced section for power users who want to tune their library usage beyond the standard defaults. This guide covers performance optimization for CPU-intensive callbacks and granular configuration for debugging complex workflows.

---

Expand All @@ -11,4 +11,4 @@ Welcome to the advanced power user guide for tuning and scaling your application
| [Logging & Debugging](logging.md) | Enabling debug mode, configuring the debug dict, reading log output, and walking through a sample logfile |
| [CPU-Intensive Tasks](cpu-intensive.md) | When to use `ProcessPoolExecutor`, pickling constraints, and performance trade-offs vs `ThreadPoolExecutor` |

<!-- synthesized-for: 3.1.1 -->
<!-- synthesized-for: 3.9.2 -->
46 changes: 23 additions & 23 deletions wiki/cascade-cms-wiki/docs/advanced/logging.md
Original file line number Diff line number Diff line change
@@ -1,66 +1,66 @@
# Logging & Debugging
# Logging & Design

Operation logger owns all console, logfile, and (verbose mode) request/response file output for the cascade_cms library. Two output modes exist: normal mode for everyday use and debug mode for diagnosing failures, controlled solely by whether `debug_config` is `None`. Both produce logfiles; debug mode adds a verbose nested call-chain log alongside a quieter console output.
The `cascade_cms` library provides two distinct logging and execution modes: normal mode for everyday use and debug mode for diagnosing failures. Both produce detailed logfiles, but debug mode adds a verbose nested call-chain log alongside a quieter console output.

---

## Normal Mode Output

Normal mode produces minimal console output and a simple logfile. It logs lifecycle markers such as `[INIT]`, `[RUNNING]`, `[DONE]`, and `[EXIT]`, along with batch tallies and operation progress lines. The normal logfile is named `{SERVER}_{timestamp}.log` and records one line per chain.
Normal mode outputs minimal console messages and a simple logfile. It handles initialization, progress reporting, and cleanup while writing one concise line per completed chain to the logfile.

### Normal Logfile Format

```text
[INIT]: Connecting to myserver.com
[RUNNING]: myscript.py
(uuid_or_path, asset_type) OP1 -> fn_name: Type -> ...
1/1 succeeded
[DONE]: 1 assets processed in 0.5s
[EXIT]: Disconnecting from myserver.com
[INIT]: Connecting to example.com
[LOG]: logs/example.com_2023-10-27T12-00-00-000000_1.log
[RUNNING]: my_script.py
3/3 succeeded
[DONE]: 3 assets processed in 0.5s
0 failed, 3 succeeded
[EXIT]: Disconnecting from example.com
```

---

## Enabling Debug Mode

```python
wrapper = CascadeWrapperBase("myserver.com", debug_config={
debug_config = {
"log_dir": "./logs",
"show_network_headers": True
})
"show_network_headers": True,
}
wrapper = CascadeWrapperBase(server="example.com", debug_config=debug_config)
```

---

## Debug Configuration Options

Recognized `debug_config` keys control the log directory and network header visibility.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| log_dir | str | "./logs" | Directory for the logfile and (verbose mode) request/response JSON files. |
| log_dir | str / PathLike | "./logs" | Directory for the logfile and (verbose mode) request/response JSON files. |
| show_network_headers | bool | False | Verbose mode only: also log request/response HTTP headers. |

---

## Debug Logfile Format

The debug logfile uses the naming convention `{SERVER}_debug_{timestamp}.log`. It features a quiet console, a verbose logfile, and per-request JSON files. There is no longer a separate "log operations vs. callbacks vs. responses" toggle — `_is_debug` is the single on/off switch for verbose behavior.
The debug logfile is named using the pattern `{SERVER}_debug_{timestamp}_{serial}.log`. It contains a quiet console output, a verbose logfile, and per-request JSON files when `debug_config` is provided.

### Sample Debug Log

```text
>>>> START REQUEST <<+
(uuid_or_path, asset_type) OP1 -> fn_name: Type -> ...
[GET] https://myserver.com/api/v1/read/site/path
1/1 succeeded
>>>> END REQUEST <<<<
>>>> START REQUEST <<^
(mySite/blog/post-1, page) READ -> read
[GET] https://example.com/api/v1/read/page/mySite/blog/post-1
3/3 succeeded
>>>> END REQUEST <<^
```

---

## Interpreting Errors in Debug Mode

Error lines in debug mode utilize a `v` marker followed by an `!ERROR:` block indicating the failure at the specified step index. Chain-level failures go through `flush_chain_error` which has step-index context. `log_cascade_error` provides a thin wrapper to log a `CascadeError` (API-level failure) outside of chain context, while `log_python_error` logs an unhandled Python exception with traceback, file name, and line number.
When a failure occurs, `OperationLogger` records a `v` marker pointing directly to the column of the failing step, followed by an `!ERROR:` block that includes the error message and the source file and line number (`@{file}:{line}`). For network or library failures, category prefixes such as `[NETWORK]` or `[CASCADE-REST-CMS]` are prepended to the message.

<!-- synthesized-for: 3.1.1 -->
<!-- synthesized-for: 3.9.2 -->
Loading