Merge branch 'main' into copilot/fix-typo-in-configuration-example

Author: jsundai

.github/workflows/snipsync.yml

@@ -0,0 +1,83 @@
+name: Snipsync
+
+on:
+  schedule:
+    - cron: '0 6 * * *' # Daily at 6:00 UTC
+  workflow_dispatch:
+
+jobs:
+  snipsync:
+    name: Sync code snippets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Generate token
+        id: generate_token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.TEMPORAL_CICD_APP_ID }}
+          private-key: ${{ secrets.TEMPORAL_CICD_PRIVATE_KEY }}
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          token: ${{ steps.generate_token.outputs.token }}
+          ref: main
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run snipsync
+        run: yarn snipsync
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push changes
+        if: steps.changes.outputs.has_changes == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          branch_name="snipsync/daily-update"
+          git checkout -B "$branch_name"
+          git add docs/
+          git commit -m "chore: sync code snippets via snipsync"
+          git push --force-with-lease origin "$branch_name"
+
+      - name: Create or update PR
+        if: steps.changes.outputs.has_changes == 'true'
+        env:
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+        run: |
+          branch_name="snipsync/daily-update"
+          existing_pr=$(gh pr list --head "$branch_name" --state open --json number --jq '.[0].number')
+
+          if [ -n "$existing_pr" ]; then
+            echo "PR #$existing_pr already exists — updated with latest push."
+          else
+            gh pr create \
+              --title "chore: sync code snippets" \
+              --body "$(cat <<'EOF'
+          Automated daily sync of code snippets from source repositories via snipsync.
+
+          This PR was generated by the [Snipsync workflow](https://github.com/${{ github.repository }}/actions/workflows/snipsync.yml).
+          EOF
+              )" \
+              --head "$branch_name" \
+              --base "main"
+          fi

docs/cloud/metrics/index.mdx

@@ -45,3 +45,5 @@ Cloud Metrics for all Namespaces in your account are available from two sources:
 OpenMetrics is the recommended option for most users.
 
 :::
+
+For setting up SDK metrics emitted by your Workers and Clients, see [SDK metrics setup](/cloud/metrics/sdk-metrics-setup).

docs/cloud/metrics/prometheus-grafana.mdx

@@ -0,0 +1,147 @@
+---
+id: sdk-metrics-setup
+title: Monitor SDK metrics with Prometheus and Grafana
+sidebar_label: SDK Metrics
+description: Set up Temporal SDK metrics with Prometheus and Grafana for monitoring Workers and Client performance.
+slug: /cloud/metrics/sdk-metrics-setup
+toc_max_heading_level: 4
+keywords:
+  - temporal sdk metrics
+  - prometheus scrape endpoint
+  - sdk metrics setup
+  - temporal sdk monitoring
+  - grafana sdk metrics
+  - worker metrics
+  - temporal sdk prometheus
+  - sdk metrics dashboard
+tags:
+  - Metrics
+  - Observability
+  - Temporal Cloud
+---
+
+import { ZoomingImage } from '@site/src/components';
+
+SDK metrics are emitted by SDK Clients used to start your Workers and to start, signal, or query your Workflow Executions.
+Unlike [Temporal Cloud metrics](/cloud/metrics/), which are exposed through a Prometheus HTTP API endpoint, SDK metrics require you to set up a Prometheus scrape endpoint in your application code for Prometheus to collect and aggregate.
+
+For a full list of available SDK metrics and their descriptions, see the [SDK metrics reference](/references/sdk-metrics).
+
+The process for setting up SDK metrics includes the following steps:
+
+1. [Expose a metrics endpoint](#sdk-metrics-setup) in your application code where Prometheus can scrape SDK metrics.
+2. [Configure Prometheus](#prometheus-configuration) to scrape your SDK metrics endpoints.
+3. [Add an SDK metrics data source](#grafana-data-source-configuration) in Grafana.
+4. [Set up dashboards](#grafana-dashboards-setup) to visualize SDK metrics.
+
+Set up your connections to Temporal Cloud using an SDK of your choice and have some Workflows running on Temporal Cloud.
+Ensure Prometheus and Grafana are installed.
+
+- [Go](/develop/go/temporal-client#connect-to-temporal-cloud)
+- [Java](/develop/java/temporal-client#connect-to-temporal-cloud)
+- [Python](/develop/python/temporal-client#connect-to-temporal-cloud)
+- [TypeScript](/develop/typescript/core-application#connect-to-temporal-cloud)
+- [.NET](/develop/dotnet/temporal-client#connect-to-temporal-cloud)
+
+## Expose a metrics endpoint {#sdk-metrics-setup}
+
+You must configure a Prometheus scrape endpoint for Prometheus to collect and aggregate your SDK metrics.
+Each language development guide has details on how to set this up.
+
+- [Go SDK](/develop/go/observability#metrics)
+- [Java SDK](/develop/java/observability#metrics)
+- [TypeScript SDK](/develop/typescript/observability#metrics)
+- [Python](/develop/python/observability#metrics)
+- [.NET](/develop/dotnet/observability#metrics)
+
+For working examples of how to configure metrics in each SDK, see the metrics samples:
+
+- [Go SDK Samples](https://github.com/temporalio/samples-go/tree/main/metrics)
+- [Java SDK Samples](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/metrics)
+- [TypeScript SDK Samples](https://github.com/temporalio/samples-typescript/tree/main/interceptors-opentelemetry)
+- [Python SDK Samples](https://github.com/temporalio/samples-python/tree/main/custom_metric)
+- [.NET SDK Samples](https://github.com/temporalio/samples-dotnet/tree/main/src/OpenTelemetry/DotNetMetrics)
+
+Some examples use OpenTelemtry to instrument metrics. It is useful to use a
+[Prometheus exporter with OpenTelemetry](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/prometheusexporter) to expose metrics for scraping.
+
+## Configure Prometheus {#prometheus-configuration}
+
+For Temporal SDKs, you must have Prometheus running and configured to listen on the scrape endpoints exposed in your application code.
+
+For this example, you can run Prometheus locally or as a Docker container.
+In either case, ensure that you set the listen targets to the ports where you expose your scrape endpoints.
+This configuration assumes the scrape endpoint is set to port 8077 as in the [SDK metrics setup](#sdk-metrics-setup) example.
+
+```yaml
+global:
+  scrape_interval: 30s # Set the scrape interval to every 30 seconds. Default is every 1 minute.
+#...
+
+# Set your scrape configuration targets to the ports exposed on your endpoints in the SDK.
+scrape_configs:
+  - job_name: 'temporalsdkmetrics'
+    metrics_path: /metrics
+    scheme: http
+    static_configs:
+      - targets:
+          # This is the scrape endpoint where Prometheus listens for SDK metrics.
+          - localhost:8077
+        # You can have multiple targets here, provided they are set up in your application code.
+```
+
+See the [Prometheus documentation](https://prometheus.io/docs/introduction/first_steps/) for more details on how you can run Prometheus locally or using Docker.
+
+To check whether Prometheus is receiving metrics from your SDK target, go to [http://localhost:9090](http://localhost:9090) and navigate to **Status > Targets**.
+The status of your target endpoint defined in your configuration appears here.
+
+## Add an SDK metrics data source in Grafana {#grafana-data-source-configuration}
+
+Depending on how you use Grafana, you can either install and run it locally, run it as a Docker container, or log in to Grafana Cloud to set up your data sources.
+
+If you have installed and are running Grafana locally, go to [http://localhost:3000](http://localhost:3000) and sign in.
+
+To add the SDK metrics Prometheus endpoint as a data source, do the following:
+
+1. Go to **Configuration > Data sources**.
+2. Select **Add data source > Prometheus**.
+3. Enter a name for your SDK metrics data source, such as _Temporal SDK metrics_.
+4. In the **HTTP** section, enter your Prometheus endpoint in the URL field.
+   If running Prometheus locally as described in the examples in this article, enter `http://localhost:9090`.
+5. For this example, enable **Skip TLS Verify** in the **Auth** section.
+6. Click **Save and test** to verify that the data source is working.
+
+If you see issues in setting this data source, check whether the endpoints set in your SDKs are showing metrics.
+If you don't see your SDK metrics at the scrape endpoints defined, check whether your Workers and Workflow Executions are running.
+If you see metrics on the scrape endpoints, but Prometheus shows your targets are down, then there is an issue with connecting to the targets set in your SDKs.
+Verify your Prometheus configuration and restart Prometheus.
+
+If you're running Grafana as a container, you can set your SDK metrics Prometheus data source in your Grafana configuration.
+See the example Grafana configuration described in the [Prometheus and Grafana setup for open-source Temporal Service](/self-hosted-guide/monitoring#grafana) article.
+
+## Set up Grafana dashboards {#grafana-dashboards-setup}
+
+To set up SDK metrics dashboards in Grafana, you can use the UI or configure them directly in your Grafana deployment.
+
+:::tip
+
+Temporal provides community-driven [example dashboards for Temporal SDKs](https://github.com/temporalio/dashboards/tree/master/sdk) that you can customize to meet your needs.
+
+:::
+
+To import a dashboard in Grafana:
+
+1. In the navigation bar, select **Dashboards** > **Import dashboard**.
+2. You can either copy and paste the JSON from the [Temporal SDK sample dashboards](https://github.com/temporalio/dashboards/tree/master/sdk), or import the JSON files into Grafana.
+3. Save the dashboard and review the metrics data in the graphs.
+
+To configure dashboards with the UI:
+
+1. Go to **Create > Dashboard** and add an empty panel.
+2. On the **Panel configuration** page, in the **Query** tab, select the "Temporal SDK metrics" data source that you configured earlier.
+3. Expand the **Metrics browser** and select the metrics you want.
+   A list of Worker performance metrics is described in the [Developer's Guide - Worker performance](/develop/worker-performance).
+   All SDK-related metrics are listed in the [SDK metrics](/references/sdk-metrics) reference.
+4. The graph should now display data based on your selected queries.
+   Note that SDK metrics will only show if you have Workflow Execution data and running Workers.
+   If you don't see SDK metrics, run your Worker and Workflow Executions, then monitor the dashboard.

docs/cloud/metrics/sdk-metrics-setup.mdx

@@ -84,6 +84,60 @@ This means there are several things Workflows cannot do such as:
 Some calls in .NET do unsuspecting non-deterministic things and are easy to accidentally use.
 This is especially true with `Task`s.
 Temporal requires that the deterministic `TaskScheduler.Current` is used, but many .NET async calls will use `TaskScheduler.Default` implicitly (and some analyzers even encourage this).
+
+The following sections cover replay-safe APIs, followed by .NET-specific `Task` gotchas.
+
+#### Logging
+
+Use [`Workflow.Logger`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Logger), which is an instance of .NET's `ILogger`. The SDK logger automatically suppresses log messages during replay to avoid duplicates:
+
+```csharp
+Workflow.Logger.LogInformation("Starting workflow for {Name}", name);
+```
+
+For logger configuration, see [Observability: Logging](/develop/dotnet/observability#logging).
+
+#### Random numbers and UUIDs
+
+Use [`Workflow.Random`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_Random) to get a deterministic `Random` instance. For UUIDs, use [`Workflow.NewGuid()`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_NewGuid). Never use `System.Random` or `Guid.NewGuid()` directly:
+
+```csharp
+// Good - deterministic across replays
+var value = Workflow.Random.Next(1, 100);
+var uniqueId = Workflow.NewGuid();
+
+// Bad - different result on every replay
+var value = new Random().Next(1, 100);
+```
+
+#### Current time
+
+Use [`Workflow.UtcNow`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_UtcNow) instead of `DateTime.UtcNow`. The SDK returns the time of the last Workflow Task, which is consistent across replays:
+
+```csharp
+var currentTime = Workflow.UtcNow;
+```
+
+#### Detecting replay (advanced)
+
+Use [`Workflow.Unsafe.IsReplaying`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.Unsafe.html#Temporalio_Workflows_Workflow_Unsafe_IsReplaying) to guard code that should only run on the first execution, such as emitting metrics or sending external notifications from an Interceptor.
+:::caution
+
+Never use this to affect Workflow business logic — branching on replay status breaks determinism.
+
+:::
+
+```csharp
+if (!Workflow.Unsafe.IsReplaying)
+{
+    EmitMetric("workflow_started", 1);
+}
+```
+
+If your goal is to always take action when something new is happening, check that `Workflow.Unsafe.IsReplayingHistoryEvents` is false instead. This will be false during read-only operations like queries and update validators. This is what the SDK's built-in logger and metric meter use internally.
+
+#### .NET Task gotchas
+
 Here are some known gotchas to avoid with .NET tasks inside of Workflows:
 
 - Do not use `Task.Run` - this uses the default scheduler and puts work on the thread pool.

docs/develop/dotnet/core-application.mdx

@@ -37,8 +37,7 @@ Follow these guidelines when writing your message handlers:
 
 - Message handlers are defined as methods on the Workflow class, using one of the three attributes: [`WorkflowQueryAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowQueryAttribute.html), [`WorkflowSignalAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowSignalAttribute.html), and [`WorkflowUpdateAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowUpdateAttribute.html).
 - The parameters and return values of handlers and the main Workflow function must be [serializable](/dataconversion).
-- Prefer data classes to multiple input parameters.
-  Data class parameters allow you to add fields without changing the calling signature.
+- Prefer data classes to multiple input parameters. Data class parameters allow you to add fields without changing the calling signature. Keep in mind that serialization and deserialization can fail with the default data converter if the new field does not have a default value.
 
 ### Query handlers {#queries}
 

docs/develop/dotnet/message-passing.mdx

@@ -52,7 +52,7 @@ func YourWorkflow(ctx workflow.Context) error {
 		WaitForCancellation: true,
 	}
 	defer func() {
-		// This logic ensures cleanup only happens if there is a Cancellation error
+		// This logic ensures cleanup only happens if there is a Cancelation error
 		if !errors.Is(ctx.Err(), workflow.ErrCanceled) {
 			return
 		}