Benign exceptions docs

docs/develop/dotnet/benign-exceptions.mdx

@@ -0,0 +1,59 @@
+---
+id: benign-exceptions
+title: Benign exceptions - .NET SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - dotnet
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - .NET SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal .NET SDK**
+
+When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, set the `category` parameter to `ApplicationErrorCategory.Benign` when throwing an [`ApplicationFailureException`](https://dotnet.temporal.io/api/Temporalio.Exceptions.ApplicationFailureException.html).
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```csharp
+using Temporalio.Activities;
+using Temporalio.Api.Enums.V1;
+using Temporalio.Exceptions;
+
+public class MyActivities
+{
+    [Activity]
+    public async Task<string> MyActivityAsync()
+    {
+        try
+        {
+            return await CallExternalServiceAsync();
+        }
+        catch (Exception e)
+        {
+            // Mark this error as benign since it's expected
+            throw new ApplicationFailureException(
+                "Service is down",
+                inner: e,
+                category: ApplicationErrorCategory.Benign);
+        }
+    }
+}
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.

docs/develop/go/benign-exceptions.mdx

@@ -0,0 +1,55 @@
+---
+id: benign-exceptions
+title: Benign exceptions - Go SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - go
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - Go SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal Go SDK**
+
+When Activities return errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, use [`temporal.NewApplicationErrorWithOptions`](https://pkg.go.dev/go.temporal.io/sdk/temporal#NewApplicationErrorWithOptions) and set the `Category` field to `temporal.ApplicationErrorCategoryBenign` in the `ApplicationErrorOptions`.
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```go
+import (
+	"go.temporal.io/sdk/activity"
+	"go.temporal.io/sdk/temporal"
+)
+
+func MyActivity(ctx context.Context) (string, error) {
+	result, err := callExternalService()
+	if err != nil {
+		// Mark this error as benign since it's expected
+		return "", temporal.NewApplicationErrorWithOptions(
+			err.Error(),
+			"",
+			temporal.ApplicationErrorOptions{
+				Category: temporal.ApplicationErrorCategoryBenign,
+			},
+		)
+	}
+	return result, nil
+}
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.

docs/develop/java/benign-exceptions.mdx

@@ -0,0 +1,63 @@
+---
+id: benign-exceptions
+title: Benign exceptions - Java SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - java
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - Java SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal Java SDK**
+
+When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, set the category to `ApplicationErrorCategory.BENIGN` using the [`ApplicationFailure`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/failure/ApplicationFailure.html) builder.
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```java
+import io.temporal.activity.ActivityInterface;
+import io.temporal.activity.ActivityMethod;
+import io.temporal.failure.ApplicationErrorCategory;
+import io.temporal.failure.ApplicationFailure;
+
+@ActivityInterface
+public interface MyActivities {
+  @ActivityMethod
+  String myActivity();
+}
+
+public class MyActivitiesImpl implements MyActivities {
+  @Override
+  public String myActivity() {
+    try {
+      return callExternalService();
+    } catch (Exception e) {
+      // Mark this error as benign since it's expected
+      throw ApplicationFailure.newBuilder()
+          .setMessage(e.getMessage())
+          .setType(e.getClass().getName())
+          .setCause(e)
+          .setCategory(ApplicationErrorCategory.BENIGN)
+          .build();
+    }
+  }
+}
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.

docs/develop/python/benign-exceptions.mdx

@@ -0,0 +1,49 @@
+---
+id: benign-exceptions
+title: Benign exceptions - Python SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - python
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - Python SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal Python SDK**
+
+When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, set the `category` parameter to `ApplicationErrorCategory.BENIGN` when raising an [`ApplicationError`](https://python.temporal.io/temporalio.exceptions.ApplicationError.html).
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```python
+from temporalio import activity
+from temporalio.exceptions import ApplicationError, ApplicationErrorCategory
+
+@activity.defn
+async def my_activity() -> str:
+    try:
+        return await call_external_service()
+    except Exception as err:
+        raise ApplicationError(
+            message=str(err),
+            # Mark this error as benign since it's expected
+            category=ApplicationErrorCategory.BENIGN,
+        )
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.

docs/develop/ruby/benign-exceptions.mdx

@@ -0,0 +1,51 @@
+---
+id: benign-exceptions
+title: Benign exceptions - Ruby SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - ruby
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - Ruby SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal Ruby SDK**
+
+When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, set the `category` parameter to `Temporalio::Error::ApplicationError::Category::BENIGN` when raising an `ApplicationError`.
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```ruby
+require 'temporalio/activity'
+
+class MyActivity < Temporalio::Activity::Definition
+  def execute
+    begin
+      call_external_service
+    rescue StandardError => e
+      # Mark this error as benign since it's expected
+      raise Temporalio::Error::ApplicationError.new(
+        e.message,
+        category: Temporalio::Error::ApplicationError::Category::BENIGN
+      )
+    end
+  end
+end
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.

docs/develop/typescript/benign-exceptions.mdx

@@ -0,0 +1,53 @@
+---
+id: benign-exceptions
+title: Benign exceptions - TypeScript SDK
+sidebar_label: Benign exceptions
+description: Mark expected or non-severe Activity errors as benign to reduce noise in logs, metrics, and OpenTelemetry traces.
+toc_max_heading_level: 2
+keywords:
+  - benign exceptions
+  - application failure
+  - error handling
+  - observability
+  - typescript
+tags:
+  - Activities
+  - Errors
+  - Failures
+  - TypeScript SDK
+  - Temporal SDKs
+---
+
+**How to mark an Activity error as benign using the Temporal TypeScript SDK**
+
+When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues.
+By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.
+
+To mark an error as benign, set the `category` field to `ApplicationFailureCategory.BENIGN` when creating an [`ApplicationFailure`](https://typescript.temporal.io/api/classes/common.ApplicationFailure).
+
+Benign errors:
+- Have Activity failure logs downgraded to DEBUG level
+- Do not emit Activity failure metrics
+- Do not set the OpenTelemetry failure status to ERROR
+
+```typescript
+import {
+  ApplicationFailure,
+  ApplicationFailureCategory,
+} from '@temporalio/common';
+
+export async function myActivity(): Promise<string> {
+  try {
+    return await callExternalService();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw ApplicationFailure.create({
+      message,
+      // Mark this error as benign since it's expected
+      category: ApplicationFailureCategory.BENIGN,
+    });
+  }
+}
+```
+
+Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.