Merge branch 'main' into task-queue-best-practices

Author: jsundai

docs/develop/go/continue-as-new.mdx

@@ -2,42 +2,114 @@
 id: continue-as-new
 title: Continue-As-New - Go SDK
 sidebar_label: Continue-As-New
+description: Learn how to use Temporal's Continue-As-New in Go to manage large Event Histories by atomically creating new Workflow Executions with the same Workflow Id and fresh parameters.
 toc_max_heading_level: 4
 keywords:
-  - continue-as-new
+  - continue-as-new workflow
+  - restart workflow
+  - fresh event history
+  - avoid large event histories
+  - temporal go continue-as-new
 tags:
   - Workflows
   - continue-as-new
   - Go SDK
   - Temporal SDKs
-description: Continue-As-New in Temporal allows a Workflow Execution to close and start a new one with the same Workflow Id, new Run Id, and fresh Event History to manage large Event Histories.
 ---
 
-[Continue-As-New](/workflow-execution/continue-as-new) enables a Workflow Execution to close successfully and create a new Workflow Execution in a single atomic operation if the number of Events in the Event History is becoming too large.
-The Workflow Execution spawned from the use of Continue-As-New has the same Workflow Id, a new Run Id, and a fresh Event History and is passed all the appropriate parameters.
+This page answers the following questions for Go developers:
+
+- [What is Continue-As-New?](#what)
+- [How to Continue-As-New?](#how)
+- [When is it right to Continue-as-New?](#when)
+- [How to test Continue-as-New?](#how-to-test)
+
+## What is Continue-As-New? {#what}
+
+[Continue-As-New](/workflow-execution/continue-as-new) lets a Workflow Execution close successfully and creates a new Workflow Execution.
+You can think of it as a checkpoint when your Workflow gets too long or approaches certain scaling limits.
+
+The new Workflow Execution is in the same [chain](/workflow-execution#workflow-execution-chain); it keeps the same Workflow Id but gets a new Run Id and a fresh Event History.
+It also receives your Workflow's usual parameters.
 
-To cause a Workflow Execution to [Continue-As-New](/workflow-execution/continue-as-new), the Workflow API should return the result of the [`NewContinueAsNewError()`](https://pkg.go.dev/go.temporal.io/sdk/workflow#NewContinueAsNewError) function available from the `go.temporal.io/sdk/workflow` package.
+## How to Continue-As-New using the Go SDK {#how}
 
+First, design your Workflow parameters so that you can pass in the "current state" when you Continue-As-New into the next Workflow run.
+This state is typically set to `None` for the original caller of the Workflow.
+
+<div class="copycode-notice-container">
+  <a href="https://github.com/temporalio/samples-go/blob/main/safe_message_handler/workflow.go">
+    View the source code
+  </a>{' '}
+  in the context of the rest of the application code.
+</div>
 ```go
-func SimpleWorkflow(ctx workflow.Context, value string) error {
-    ...
-    return workflow.NewContinueAsNewError(ctx, SimpleWorkflow, value)
+ClusterManagerInput struct {
+    State             *ClusterManagerState
+    TestContinueAsNew bool
 }
-```
 
-To check whether a Workflow Execution was spawned as a result of Continue-As-New, you can check if `workflow.GetInfo(ctx).ContinuedExecutionRunID` is not empty (i.e. `""`).
+func newClusterManager(ctx workflow.Context, wfInput ClusterManagerInput) (*ClusterManager, error) {
+
+````
+The test hook in the above snippet is covered [below](#how-to-test).
 
-**Notes**
+Inside your Workflow, return the [`NewContinueAsNewError`](https://pkg.go.dev/go.temporal.io/sdk/workflow#NewContinueAsNewError) error.
+This stops the Workflow right away and starts a new one.
+
+<div class="copycode-notice-container">
+  <a href="https://github.com/temporalio/samples-go/blob/main/safe_message_handler/workflow.go">
+    View the source code
+  </a>{' '}
+  in the context of the rest of the application code.
+</div>
+```go
+return ClusterManagerResult{}, workflow.NewContinueAsNewError(
+    ctx,
+    ClusterManagerWorkflow,
+    ClusterManagerInput{
+        State:             &cm.state,
+        TestContinueAsNew: cm.testContinueAsNew,
+    },
+)
+````
 
-- To prevent Signal loss, be sure to perform an asynchronous drain on the Signal channel.
-  Failure to do so can result in buffered Signals being ignored and lost.
-- Make sure that the previous Workflow and the Continue-As-New Workflow are referenced by the same alias.
-  Failure to do so can cause the Workflow to Continue-As-New on an entirely different Workflow.
+### Considerations for Workflows with Message Handlers {#with-message-handlers}
 
-:::warning Using Continue-as-New and Updates
+If you use Updates or Signals, don't call Continue-as-New from the handlers.
+Instead, wait for your handlers to finish in your main Workflow before you return `NewContinueAsNewError`.
+See the [`AllHandlersFinished`](message-passing#wait-for-message-handlers) example for guidance.
 
-- Temporal _does not_ support Continue-as-New functionality within Update handlers.
-- Complete all handlers _before_ using Continue-as-New.
-- Use Continue-as-New from your main Workflow Definition method, just as you would complete or fail a Workflow Execution.
+## When is it right to Continue-as-New using the Go SDK? {#when}
 
-:::
+Use Continue-as-New when your Workflow might hit [Event History Limits](/workflow-execution/event#event-history).
+
+Temporal tracks your Workflow's progress against these limits to let you know when you should Continue-as-New.
+Call `GetInfo(ctx).GetContinueAsNewSuggested()` to check if it's time.
+
+## How to test Continue-as-New using the Go SDK {#how-to-test}
+
+Testing Workflows that naturally Continue-as-New may be time-consuming and resource-intensive.
+Instead, add a test hook to check your Workflow's Continue-as-New behavior faster in automated tests.
+
+For example, when `TestContinueAsNew == True`, this sample creates a test-only variable called `maxHistoryLength` and sets it to a small value.
+A helper method in the Workflow checks it each time it considers using Continue-as-New:
+
+<div class="copycode-notice-container">
+  <a href="https://github.com/temporalio/samples-go/blob/main/safe_message_handler/workflow.go">
+    View the source code
+  </a>{' '}
+  in the context of the rest of the application code.
+</div>
+
+```go
+func (cm *ClusterManager) shouldContinueAsNew(ctx workflow.Context) bool {
+	if workflow.GetInfo(ctx).GetContinueAsNewSuggested() {
+		return true
+	}
+	if cm.maxHistoryLength > 0 && workflow.GetInfo(ctx).GetCurrentHistoryLength() > cm.maxHistoryLength {
+		return true
+	}
+	return false
+}
+```

docs/develop/go/core-application.mdx

@@ -569,8 +569,8 @@ A large Execution history can thus adversely impact the performance of your Work
 Therefore, be mindful of the amount of data you transfer through Activity invocation parameters or Return Values.
 Otherwise, no additional limitations exist on Activity implementations.
 
-    To spawn an [Activity Execution](/activity-execution), call [`ExecuteActivity()`](https://pkg.go.dev/go.temporal.io/workflow#ExecuteActivity) inside your Workflow Definition.
-    The API is available from the [`go.temporal.io/sdk/workflow`](https://pkg.go.dev/go.temporal.io/workflow) package.
+    To spawn an [Activity Execution](/activity-execution), call [`ExecuteActivity()`](https://pkg.go.dev/go.temporal.io/sdk/workflow#ExecuteActivity) inside your Workflow Definition.
+    The API is available from the [`go.temporal.io/sdk/workflow`](https://pkg.go.dev/go.temporal.io/sdk/workflow) package.
     The `ExecuteActivity()` API call requires an instance of `workflow.Context`, the Activity function name, and any variables to be passed to the Activity Execution.
         The Activity function name can be provided as a variable object (no quotations) or as a string.
         The benefit of passing the actual function object is that the framework can validate the parameters against the Activity Definition.

docs/develop/php/index.mdx

@@ -73,6 +73,7 @@ Send messages to read the state of Workflow Executions.
 - [How to develop with Updates](/develop/php/message-passing#updates)
 - [Message handler patterns](/develop/php/message-passing#message-handler-patterns)
 - [Message handler troubleshooting](/develop/php/message-passing#message-handler-troubleshooting)
+- [How to develop with Dynamic Handlers](/develop/php/message-passing#dynamic-handler)
 
 ## [Interrupt a Workflow feature guide](/develop/php/cancellation)
 
@@ -98,6 +99,7 @@ Complete Activities asynchronously.
 
 Configure and use the Temporal Observability APIs.
 
+- [How to log from a Workflow](/develop/php/observability#logging)
 - [How to use Visibility APIs](/develop/php/observability#visibility)
 
 ## [Debugging](/develop/php/debugging)

docs/develop/php/message-passing.mdx

@@ -8,6 +8,9 @@ keywords:
   - signals
   - queries
   - updates
+  - dynamic signals
+  - dynamic queries
+  - dynamic updates
 tags:
   - Workflows
   - Messages
@@ -839,3 +842,83 @@ When working with Queries, you may encounter these errors:
 
 - **The handler caused the Workflow Task to fail.**
   This would happen, for example, if the Query handler blocks the thread for too long without yielding.
+
+## Dynamic components {#dynamic-handler}
+
+Temporal supports Dynamic Queries, Signals, and Updates.
+These are unnamed handlers that are invoked if no other statically defined handler with the given name exists.
+
+Dynamic Handlers provide flexibility to handle cases where the names of Queries, Signals, or Updates aren't known at run time.
+
+:::caution
+
+Dynamic Handlers should be used judiciously as a fallback mechanism rather than the primary approach.
+Overusing them can lead to maintainability and debugging issues down the line.
+
+Instead, Signals, or Queries should be defined statically whenever possible, with clear names that indicate their purpose.
+Use static definitions as the primary way of structuring your Workflows.
+
+Reserve Dynamic Handlers for cases where the handler names are not known at development time and need to be looked up dynamically at runtime.
+They are meant to handle edge cases and act as a catch-all, not as the main way of invoking logic.
+
+:::
+
+### How to set a Dynamic Query {#set-a-dynamic-query}
+
+A Dynamic Query in Temporal is a Query method that is invoked dynamically at runtime if no other Query with the same name is registered.
+Use [`Workflow::registerDynamicQuery()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicQuery) to set a dynamic Query handler.
+
+The Query Handler parameters must accept a `string` name and [`ValuesInterface`](https://php.temporal.io/classes/Temporal-DataConverter-ValuesInterface.html) for the arguments.
+
+```php
+Workflow::registerDynamicQuery(function (string $name, ValuesInterface $arguments): string {
+    return \sprintf(
+        'Got query `%s` with %d arguments',
+        $name,
+        $arguments->count(),
+    );
+});
+```
+
+### How to set a Dynamic Signal {#set-a-dynamic-signal}
+
+A Dynamic Signal in Temporal is a Signal that is invoked dynamically at runtime if no other Signal with the same input is registered.
+Use [`Workflow::registerDynamicSignal()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicSignal) to set a dynamic Signal handler.
+
+The Signal Handler parameters must accept a `string` name and [`ValuesInterface`](https://php.temporal.io/classes/Temporal-DataConverter-ValuesInterface.html) for the arguments.
+
+```php
+Workflow::registerDynamicSignal(function (string $name, ValuesInterface $arguments): void {
+     Workflow::getLogger()->info(\sprintf(
+         'Executed signal `%s` with %d arguments',
+         $name,
+         $arguments->count(),
+     ));
+ });
+```
+
+### How to set a Dynamic Update {#set-a-dynamic-update}
+
+A Dynamic Update in Temporal is an Update that is invoked dynamically at runtime if no other Update with the same input is registered.
+Use [`Workflow::registerDynamicUpdate()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_registerDynamicUpdate) to set a dynamic Update handler.
+
+The method accepts two arguments:
+
+- Update Handler
+- Update Validator (optional) that should throw an exception if the validation fails
+
+Both the Handler and the Validator must accept a `string` name and [`ValuesInterface`](https://php.temporal.io/classes/Temporal-DataConverter-ValuesInterface.html) for the arguments.
+
+```php
+Workflow::registerDynamicUpdate(
+    static fn(string $name, ValuesInterface $arguments): string => \sprintf(
+        'Got update `%s` with %d arguments',
+        $name,
+        $arguments->count(),
+    ),
+    static fn(string $name, ValuesInterface $arguments) => \str_starts_with(
+        $name,
+        'update_',
+    ) or throw new \InvalidArgumentException('Invalid update name'),
+);
+```

docs/develop/php/observability.mdx

@@ -8,6 +8,7 @@ toc_max_heading_level: 4
 keywords:
   - guide-context
   - php
+  - logging and metrics
   - search attribute
   - search attributes
   - upsert search attributes
@@ -24,9 +25,82 @@ The observability section of the Temporal Developer's guide covers the many ways
 
 This section covers features related to viewing the state of the application, including:
 
+- [Log from a Workflow](#logging)
 - [Visibility](#visibility)
 
-## How to use Visibility APIs {#visibility}
+## Log from a Workflow {#logging}
+
+Logging enables you to record critical information during code execution.
+Loggers create an audit trail and capture information about your Workflow's operation.
+An appropriate logging level depends on your specific needs.
+During development or troubleshooting, you might use debug or even trace.
+In production, you might use info or warn to avoid excessive log volume.
+
+The logger supports the following logging levels:
+
+| Level   | Use                                                                                                       |
+| ------- | --------------------------------------------------------------------------------------------------------- |
+| `TRACE` | The most detailed level of logging, used for very fine-grained information.                               |
+| `DEBUG` | Detailed information, typically useful for debugging purposes.                                            |
+| `INFO`  | General information about the application's operation.                                                    |
+| `WARN`  | Indicates potentially harmful situations or minor issues that don't prevent the application from working. |
+| `ERROR` | Indicates error conditions that might still allow the application to continue running.                    |
+
+The Temporal SDK core normally uses `WARN` as its default logging level.
+
+To get a PSR-3 compatible logger in your Workflow code, use the [`Workflow::getLogger()`](https://php.temporal.io/classes/Temporal-Workflow.html#method_getLogger) method.
+
+```php
+use Temporal\Workflow;
+
+#[Workflow\WorkflowInterface]
+class MyWorkflow
+{
+    #[Workflow\WorkflowMethod]
+    public function execute(string $param): \Generator
+    {
+        Workflow::getLogger()->info('Workflow started', ['parameter' => $param]);
+
+        // Your workflow implementation
+
+        Workflow::getLogger()->info('Workflow completed');
+        return 'Done';
+    }
+}
+```
+
+The Workflow logger automatically enriches log context with the current Task Queue name.
+
+Logs in replay mode are omitted unless the [`enableLoggingInReplay`](https://php.temporal.io/classes/Temporal-Worker-WorkerOptions.html#method_withEnableLoggingInReplay) Worker option is set to true.
+
+```php
+$factory = WorkerFactory::create();
+$worker = $factory->newWorker('your-task-queue', WorkerOptions::new()
+    ->withEnableLoggingInReplay(true)
+);
+```
+
+### Default Logger
+
+By default, PHP SDK uses a [`StderrLogger`](https://php.temporal.io/classes/Temporal-Worker-Logger-StderrLogger.html) that outputs log messages to the standard error stream.
+These messages are automatically captured by RoadRunner and incorporated into its logging system with the INFO level, ensuring proper log collection in both development and production environments.
+For more details on RoadRunner's logging capabilities, see the [RoadRunner Logger documentation](https://docs.roadrunner.dev/docs/logging-and-observability/logger).
+
+### How to provide a custom logger {#custom-logger}
+
+You can set a custom PSR-3 compatible logger when creating a Worker:
+
+```php
+$myLogger = new MyLogger();
+
+$workerFactory = WorkerFactory::create(converter: $converter);
+$worker = $workerFactory->newWorker(
+    taskQueue: 'my-task-queue',
+    logger: $myLogger,
+);
+```
+
+## Visibility APIs {#visibility}
 
 The term Visibility, within the Temporal Platform, refers to the subsystems and APIs that enable an operator to view Workflow Executions that currently exist within a Temporal Service.
 

docs/develop/python/continue-as-new.mdx

@@ -65,12 +65,12 @@ This stops the Workflow right away and starts a new one.
   in the context of the rest of the application code.
 </div>
 ```python
-  workflow.continue_as_new(
-      ClusterManagerInput(
-          state=self.state,
-          test_continue_as_new=input.test_continue_as_new,
-      )
+workflow.continue_as_new(
+  ClusterManagerInput(
+      state=self.state,
+      test_continue_as_new=input.test_continue_as_new,
   )
+)
 ````
 
 ### Considerations for Workflows with Message Handlers {#with-message-handlers}

docs/production-deployment/cloud/get-started/api-keys.mdx

@@ -598,14 +598,14 @@ myClient.Connection.RpcMetadata = new Dictionary<string, string>()
 Create an initial `Connection` (for use with `Client`):
 
 ```typescript
-const connection = await Connection.connect(
+const connection = await Connection.connect({
     address: <endpoint>,
     tls: true,
     apiKey: <APIKey>,
     metadata: {
         'temporal-namespace': <namespace_id>.<account_id>,
     },
-)
+});
 const client = new Client({
     connection,
     namespace: <namespace_id>.<account_id>,
@@ -615,14 +615,14 @@ const client = new Client({
 Create an initial Worker `NativeConnection` (for use with `Worker`):
 
 ```typescript
-const connection = await NativeConnection.connect(
+const connection = await NativeConnection.connect({
     address: <endpoint>,
     tls: true,
     apiKey: <APIKey>,
     metadata: {
       'temporal-namespace': <namespace_id>.<account_id>,
     },
-)
+});
 const worker = await Worker.create({
     connection,
     namespace: <namespace_id>.<account_id>,