docs: document Actor run log redirection on the Logging page

docs/02_concepts/06_logging.mdx

@@ -1,7 +1,7 @@
 ---
 id: logging
 title: Logging
-description: Configure debug logging to inspect API requests and responses.
+description: Configure debug logging for API requests and redirect Actor run logs to Python loggers.
 ---
 
 import Tabs from '@theme/Tabs';
@@ -10,6 +10,12 @@ import CodeBlock from '@theme/CodeBlock';
 
 import LoggingConfigExample from '!!raw-loader!./code/06_logging_config.py';
 import LoggingFormatterExample from '!!raw-loader!./code/06_logging_formatter.py';
+import RedirectCallAsyncExample from '!!raw-loader!./code/06_redirect_call_async.py';
+import RedirectCallSyncExample from '!!raw-loader!./code/06_redirect_call_sync.py';
+import RedirectRunAsyncExample from '!!raw-loader!./code/06_redirect_run_async.py';
+import RedirectRunSyncExample from '!!raw-loader!./code/06_redirect_run_sync.py';
+
+import ApiLink from '@theme/ApiLink';
 
 The library logs useful debug information to the `apify_client` logger whenever it sends requests to the Apify API. You can configure this logger to print debug information to the standard output by adding a handler:
 
@@ -32,3 +38,39 @@ To display these additional properties in the log output, you need to use a cust
 </CodeBlock>
 
 For more information on creating and using custom log formatters, refer to the official Python [logging documentation](https://docs.python.org/3/howto/logging.html#formatters).
+
+## Redirecting Actor run logs
+
+When you start an Actor with <ApiLink to="class/ActorClient#call">`ActorClient.call`</ApiLink>, the client redirects the run's log to a Python logger while it waits for the run to finish. The same logger also receives the run's status and status message whenever they change. The `logger` argument controls where the lines go:
+
+- `'default'` (the default) - A built-in redirect logger named after the Actor and the run ID.
+- A `logging.Logger` - Your own logger receives the lines, so give it a handler and a level that let them through.
+- `None` - Redirection is turned off.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {RedirectCallAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {RedirectCallSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+For a run started with <ApiLink to="class/ActorClient#start">`ActorClient.start`</ApiLink>, or any other run you have a client for, use <ApiLink to="class/RunClient#get_streamed_log">`RunClient.get_streamed_log`</ApiLink> to redirect its log and <ApiLink to="class/RunClient#get_status_message_watcher">`RunClient.get_status_message_watcher`</ApiLink> to redirect its status messages. Both accept an optional `to_logger` and work as context managers, or you can call `start()` and `stop()` yourself:
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {RedirectRunAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {RedirectRunSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>

docs/02_concepts/code/06_redirect_call_async.py

@@ -0,0 +1,21 @@
+import logging
+
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # By default, the run's log and status messages go to a built-in redirect logger.
+    await actor_client.call()
+
+    # Send the run's log and status messages to your own logger.
+    logging.basicConfig(level=logging.INFO)
+    my_logger = logging.getLogger('my_actor_run')
+    await actor_client.call(logger=my_logger)
+
+    # Turn the redirection off.
+    await actor_client.call(logger=None)

docs/02_concepts/code/06_redirect_call_sync.py

@@ -0,0 +1,21 @@
+import logging
+
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # By default, the run's log and status messages go to a built-in redirect logger.
+    actor_client.call()
+
+    # Send the run's log and status messages to your own logger.
+    logging.basicConfig(level=logging.INFO)
+    my_logger = logging.getLogger('my_actor_run')
+    actor_client.call(logger=my_logger)
+
+    # Turn the redirection off.
+    actor_client.call(logger=None)

docs/02_concepts/code/06_redirect_run_async.py

@@ -0,0 +1,27 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    actor_run = await actor_client.start()
+    run_client = apify_client.run(actor_run.id)
+
+    # Use the helpers as context managers to redirect while the run is in progress.
+    streamed_log = await run_client.get_streamed_log()
+    status_message_watcher = await run_client.get_status_message_watcher()
+    async with streamed_log, status_message_watcher:
+        await run_client.wait_for_finish()
+
+    # Or start and stop them yourself.
+    actor_run = await actor_client.start()
+    run_client = apify_client.run(actor_run.id)
+
+    # With `from_start=False`, only log lines written from now on are redirected.
+    streamed_log = await run_client.get_streamed_log(from_start=False)
+    streamed_log.start()
+    # Do other work while the run's log is redirected.
+    await streamed_log.stop()

docs/02_concepts/code/06_redirect_run_sync.py

@@ -0,0 +1,27 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    actor_run = actor_client.start()
+    run_client = apify_client.run(actor_run.id)
+
+    # Use the helpers as context managers to redirect while the run is in progress.
+    streamed_log = run_client.get_streamed_log()
+    status_message_watcher = run_client.get_status_message_watcher()
+    with streamed_log, status_message_watcher:
+        run_client.wait_for_finish()
+
+    # Or start and stop them yourself.
+    actor_run = actor_client.start()
+    run_client = apify_client.run(actor_run.id)
+
+    # With `from_start=False`, only log lines written from now on are redirected.
+    streamed_log = run_client.get_streamed_log(from_start=False)
+    streamed_log.start()
+    # Do other work while the run's log is redirected.
+    streamed_log.stop()