Add caller-provided logger configuration

CHANGELOG.md

@@ -9,6 +9,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ADDED
 
+- Added a `logger` parameter to `TaskHubGrpcClient`,
+  `AsyncTaskHubGrpcClient`, and `TaskHubGrpcWorker`. Applications can now
+  provide fully configured loggers without the SDK modifying their handlers,
+  formatter, level, filters, or propagation.
+
+CHANGED
+
+- Deprecated the `log_handler` and `log_formatter` parameters on
+  `TaskHubGrpcClient`, `AsyncTaskHubGrpcClient`, and `TaskHubGrpcWorker`.
+  Configure and pass a `logger` instead. These parameters will be removed in a
+  future major release.
 - Added the optional `new_version` argument to
 `OrchestrationContext.continue_as_new()` so continued orchestrations can
 switch to a new version.

azure-functions-durable/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+CHANGED
+
+- Durable Functions client and worker logs now use the Azure Functions
+  host-managed `azure.durable_functions` logger hierarchy instead of private
+  SDK handlers. Configure their level, destination, and telemetry routing
+  through the standard Functions/Python logging configuration.
+
 ## v2.0.0b2
 
 ADDED

azure-functions-durable/azure/durable_functions/client.py

@@ -4,6 +4,7 @@
 import asyncio
 import atexit
 import json
+import logging
 import threading
 
 from datetime import datetime, timedelta
@@ -35,6 +36,7 @@
 
 _sync_client_cache: dict[str, "SyncDurableFunctionsClient"] = {}
 _sync_client_cache_lock = threading.Lock()
+_LOGGER = logging.getLogger(__name__)
 
 
 def _first_forwarded_value(value: str) -> str:
@@ -176,7 +178,8 @@ def __init__(self, client_as_string: str):
             interceptors=interceptors,
             channel_options=channel_options,
             data_converter=DEFAULT_FUNCTIONS_DATA_CONVERTER,
-            emit_trace_spans=False)
+            emit_trace_spans=False,
+            logger=_LOGGER)
 
         # The gRPC aio channel is bound to the event loop it is created on. A
         # ``durable_client_input`` decode runs on the worker's invocation loop,
@@ -669,7 +672,8 @@ def __init__(self, client_as_string: str):
             interceptors=interceptors,
             channel_options=channel_options,
             data_converter=DEFAULT_FUNCTIONS_DATA_CONVERTER,
-            emit_trace_spans=False)
+            emit_trace_spans=False,
+            logger=_LOGGER)
 
     @classmethod
     def get_cached(cls, client_as_string: str) -> "SyncDurableFunctionsClient":

azure-functions-durable/azure/durable_functions/worker.py

@@ -2,6 +2,7 @@
 # Licensed under the MIT License.
 
 import base64
+import logging
 from threading import Lock
 from typing import Any, Optional
 
@@ -19,6 +20,8 @@
 from .internal.compat.orchestration_context import wrap_orchestrator
 from .internal.serialization import DEFAULT_FUNCTIONS_DATA_CONVERTER
 
+_LOGGER = logging.getLogger(__name__)
+
 
 # Host-driven Azure Functions execution engine for orchestrator and entity
 # functions. Despite subclassing ``TaskHubGrpcWorker``, it never opens a gRPC
@@ -44,6 +47,7 @@ def __init__(self) -> None:
         super().__init__(
             data_converter=DEFAULT_FUNCTIONS_DATA_CONVERTER,
             emit_trace_spans=False,
+            logger=_LOGGER,
         )
         self._registration_lock = Lock()
         self._registered_orchestrator_functions: dict[

docs/features.md

@@ -268,6 +268,72 @@ message formatting.
 > Create the replay-safe logger once at the start of your orchestrator
 > and reuse it throughout the function.
 
+### SDK logging
+
+`TaskHubGrpcClient`, `AsyncTaskHubGrpcClient`, and `TaskHubGrpcWorker`
+accept a configured `logging.Logger` through their `logger` parameter. The
+SDK uses a supplied logger unchanged: it does not add handlers or modify its
+formatter, level, filters, or propagation setting. The Durable Task Scheduler
+client and worker accept the same parameter.
+
+Use one shared logger when client and worker records should use the same
+destination, format, and correlation filters:
+
+```python
+import logging
+
+from durabletask.client import TaskHubGrpcClient
+from durabletask.worker import TaskHubGrpcWorker
+
+sdk_logger = logging.getLogger("myapp.durabletask")
+sdk_logger.setLevel(logging.INFO)
+
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter(
+    "%(asctime)s %(name)s %(levelname)s %(message)s"))
+sdk_logger.addHandler(handler)
+sdk_logger.propagate = False
+
+worker = TaskHubGrpcWorker(logger=sdk_logger)
+client = TaskHubGrpcClient(logger=sdk_logger)
+```
+
+Because `logging.getLogger()` returns the same logger for a given name,
+configure a shared logger once during application startup. Do not add a new
+handler every time a client or worker is constructed, or every record will be
+emitted once by each handler.
+
+Alternatively, configure handlers on the root logger and allow propagation:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+sdk_logger = logging.getLogger("myapp.durabletask")
+
+worker = TaskHubGrpcWorker(logger=sdk_logger)
+client = TaskHubGrpcClient(logger=sdk_logger)
+```
+
+> [!WARNING]
+> Use either handlers attached directly to `sdk_logger` with
+> `sdk_logger.propagate = False`, or root handlers with propagation enabled.
+> Combining both emits each Durable Task record twice.
+
+Pass separate named loggers when clients and workers need independently
+configured levels, destinations, or filters:
+
+```python
+worker = TaskHubGrpcWorker(
+    logger=logging.getLogger("myapp.durabletask.worker"))
+client = TaskHubGrpcClient(
+    logger=logging.getLogger("myapp.durabletask.client"))
+```
+
+The older `log_handler` and `log_formatter` parameters are deprecated. They
+will be removed in a future major release. Passing either one together with
+`logger` raises `ValueError`; none of the supplied logging options are ignored.
+
 ### Large payload externalization
 
 Orchestration inputs, outputs, and event data are transmitted through gRPC messages. When these

durabletask-azuremanaged/CHANGELOG.md

@@ -7,6 +7,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+ADDED
+
+- Added a `logger` parameter to `DurableTaskSchedulerClient`,
+  `AsyncDurableTaskSchedulerClient`, and `DurableTaskSchedulerWorker`. Applications
+  can now provide fully configured loggers without the SDK modifying them.
+
+CHANGED
+
+- Deprecated the `log_handler` and `log_formatter` parameters on
+  `DurableTaskSchedulerClient`, `AsyncDurableTaskSchedulerClient`, and
+  `DurableTaskSchedulerWorker`. Configure and pass a `logger` instead. These
+  parameters will be removed in a future major release.
+
 ## v1.9.0
 
 CHANGED

durabletask-azuremanaged/durabletask/azuremanaged/client.py

@@ -38,7 +38,8 @@ def __init__(self, *,
                  payload_store: PayloadStore | None = None,
                  data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
-                 log_formatter: logging.Formatter | None = None):
+                 log_formatter: logging.Formatter | None = None,
+                 logger: logging.Logger | None = None):
 
         if not taskhub:
             raise ValueError("Taskhub value cannot be empty. Please provide a value for your taskhub")
@@ -57,6 +58,7 @@ def __init__(self, *,
             metadata=None,
             log_handler=log_handler,
             log_formatter=log_formatter,
+            logger=logger,
             interceptors=resolved_interceptors,
             channel_options=channel_options,
             resiliency_options=resiliency_options,
@@ -86,8 +88,13 @@ class AsyncDurableTaskSchedulerClient(AsyncTaskHubGrpcClient):
         default_version (str | None, optional): Default version string for orchestrations.
         payload_store (PayloadStore | None, optional): A payload store for
             externalizing large payloads. If None, payloads are sent inline.
-        log_handler (logging.Handler | None, optional): Custom logging handler for client logs.
-        log_formatter (logging.Formatter | None, optional): Custom log formatter for client logs.
+        log_handler (logging.Handler | None, optional): Deprecated custom logging
+            handler for client logs. Use ``logger`` instead.
+        log_formatter (logging.Formatter | None, optional): Deprecated custom log
+            formatter. Use ``logger`` instead.
+        logger (logging.Logger | None, optional): Caller-configured logger for
+            client logs. It cannot be combined with ``log_handler`` or
+            ``log_formatter``; doing so raises ``ValueError``.
 
     Raises:
         ValueError: If taskhub is empty or None.
@@ -118,7 +125,8 @@ def __init__(self, *,
                  payload_store: PayloadStore | None = None,
                  data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
-                 log_formatter: logging.Formatter | None = None):
+                 log_formatter: logging.Formatter | None = None,
+                 logger: logging.Logger | None = None):
 
         if not taskhub:
             raise ValueError("Taskhub value cannot be empty. Please provide a value for your taskhub")
@@ -137,6 +145,7 @@ def __init__(self, *,
             metadata=None,
             log_handler=log_handler,
             log_formatter=log_formatter,
+            logger=logger,
             interceptors=resolved_interceptors,
             channel_options=channel_options,
             resiliency_options=resiliency_options,

durabletask-azuremanaged/durabletask/azuremanaged/worker.py

@@ -44,8 +44,13 @@ class DurableTaskSchedulerWorker(TaskHubGrpcWorker):
             settings will be used.
         payload_store (PayloadStore | None, optional): A payload store for
             externalizing large payloads. If None, payloads are sent inline.
-        log_handler (logging.Handler | None, optional): Custom logging handler for worker logs.
-        log_formatter (logging.Formatter | None, optional): Custom log formatter for worker logs.
+        log_handler (logging.Handler | None, optional): Deprecated custom logging
+            handler for worker logs. Use ``logger`` instead.
+        log_formatter (logging.Formatter | None, optional): Deprecated custom log
+            formatter. Use ``logger`` instead.
+        logger (logging.Logger | None, optional): Caller-configured logger for
+            worker logs. It cannot be combined with ``log_handler`` or
+            ``log_formatter``; doing so raises ``ValueError``.
 
     Raises:
         ValueError: If taskhub is empty or None.
@@ -84,7 +89,8 @@ def __init__(self, *,
                  payload_store: PayloadStore | None = None,
                  data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
-                 log_formatter: logging.Formatter | None = None):
+                 log_formatter: logging.Formatter | None = None,
+                 logger: logging.Logger | None = None):
 
         if not taskhub:
             raise ValueError("The taskhub value cannot be empty.")
@@ -106,6 +112,7 @@ def __init__(self, *,
             metadata=None,
             log_handler=log_handler,
             log_formatter=log_formatter,
+            logger=logger,
             interceptors=resolved_interceptors,
             channel_options=channel_options,
             resiliency_options=resiliency_options,

durabletask/client.py

@@ -412,6 +412,7 @@ def __init__(self, *,
                  metadata: list[tuple[str, str]] | None = None,
                  log_handler: logging.Handler | None = None,
                  log_formatter: logging.Formatter | None = None,
+                 logger: logging.Logger | None = None,
                  channel: grpc.Channel | None = None,
                  secure_channel: bool = False,
                  interceptors: Sequence[shared.ClientInterceptor] | None = None,
@@ -422,6 +423,7 @@ def __init__(self, *,
                  data_converter: DataConverter | None = None,
                  emit_trace_spans: bool = True):
 
+        self._logger = shared.get_logger("client", log_handler, log_formatter, logger)
         self._owns_channel = channel is None
         self._data_converter = data_converter if data_converter is not None else JsonDataConverter()
         self._host_address = (
@@ -482,7 +484,6 @@ def __init__(self, *,
         # can prepend the interceptor themselves via grpc.intercept_channel.
         self._channel = channel
         self._stub = cast(_SyncTaskHubSidecarServiceStub, stubs.TaskHubSidecarServiceStub(channel))
-        self._logger = shared.get_logger("client", log_handler, log_formatter)
         self.default_version = default_version
         self._payload_store = payload_store
         self._emit_trace_spans = emit_trace_spans
@@ -941,6 +942,7 @@ def __init__(self, *,
                  metadata: list[tuple[str, str]] | None = None,
                  log_handler: logging.Handler | None = None,
                  log_formatter: logging.Formatter | None = None,
+                 logger: logging.Logger | None = None,
                  channel: grpc.aio.Channel | None = None,
                  secure_channel: bool = False,
                  interceptors: Sequence[shared.AsyncClientInterceptor] | None = None,
@@ -951,6 +953,7 @@ def __init__(self, *,
                  data_converter: DataConverter | None = None,
                  emit_trace_spans: bool = True):
 
+        self._logger = shared.get_logger("async_client", log_handler, log_formatter, logger)
         self._owns_channel = channel is None
         self._data_converter = data_converter if data_converter is not None else JsonDataConverter()
         self._host_address = (
@@ -1008,7 +1011,6 @@ def __init__(self, *,
             if channel is not None
             else None
         )
-        self._logger = shared.get_logger("async_client", log_handler, log_formatter)
         self.default_version = default_version
         self._payload_store = payload_store
         self._emit_trace_spans = emit_trace_spans

durabletask/internal/shared.py

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
+import inspect
 import logging
 import warnings
 from collections.abc import Sequence
@@ -72,6 +73,22 @@ def from_json(json_str: str | bytes | bytearray, expected_type: type | None = No
 INSECURE_PROTOCOLS = ["http://", "grpc://"]
 
 
+def _get_legacy_logging_warning_stacklevel() -> int:
+    stacklevel = 1
+    frame = inspect.currentframe()
+    if frame is not None:
+        frame = frame.f_back
+
+    while frame is not None:
+        module_name = frame.f_globals.get("__name__", "")
+        if module_name != "durabletask" and not module_name.startswith("durabletask."):
+            break
+        stacklevel += 1
+        frame = frame.f_back
+
+    return stacklevel
+
+
 def get_default_host_address() -> str:
     return "localhost:4001"
 
@@ -178,7 +195,22 @@ def get_async_grpc_channel(
 def get_logger(
         name_suffix: str,
         log_handler: logging.Handler | None = None,
-        log_formatter: logging.Formatter | None = None) -> logging.Logger:
+        log_formatter: logging.Formatter | None = None,
+        logger: logging.Logger | None = None) -> logging.Logger:
+    if logger is not None:
+        if log_handler is not None or log_formatter is not None:
+            raise ValueError(
+                "'logger' cannot be combined with 'log_handler' or 'log_formatter'.")
+        return logger
+
+    if log_handler is not None or log_formatter is not None:
+        warnings.warn(
+            "'log_handler' and 'log_formatter' are deprecated and will be removed "
+            "in a future major release. Configure and pass a 'logger' instead.",
+            DeprecationWarning,
+            stacklevel=_get_legacy_logging_warning_stacklevel(),
+        )
+
     logger = logging.Logger(f"durabletask-{name_suffix}")
 
     # Add a default log handler if none is provided