diff --git a/docs/best-practices/cloud-access-control.mdx b/docs/best-practices/cloud-access-control.mdx index c81dc74122..17ea876be9 100644 --- a/docs/best-practices/cloud-access-control.mdx +++ b/docs/best-practices/cloud-access-control.mdx @@ -58,8 +58,8 @@ One convention is to give certificates a common name that matches the namespace. Teams should standardize on either [mTLS certificates](/cloud/certificates) or [API keys](/cloud/api-keys) for the following operations: -- Connect Temporal clients to Temporal Cloud (e.g. Worker processes) -- Automation (e.g. Temporal Cloud [Operations API](/ops), [Terraform provider](/cloud/terraform-provider), [Temporal CLI](/cli/setup-cli)) +- Connect Temporal clients to Temporal Cloud (for example, Worker processes) +- Automation (for example, Temporal Cloud [Operations API](/ops), [Terraform provider](/cloud/terraform-provider), [Temporal CLI](/cli/setup-cli)) By default, teams should use API keys with [service accounts](/cloud/manage-access/service-accounts) for both operations. API keys are generally easier to set up and rotate than mTLS certificates, and service accounts let you assign account-level and @@ -108,7 +108,7 @@ Use the following sequence when rotating credentials: 4. Validate connectivity and normal Workflow execution using the new credential. 5. Remove the old credential only after all clients and Workers have switched. -### Use Certificate Filters to restrict access when using shared CAs (e.g., `dev` vs `prod`) +### Use Certificate Filters to restrict access when using shared CAs (for example, `dev` vs `prod`) Certificate Filters are an additional way of validating using the client certificate presented during client authentication. Give certificates a common name that matches the namespace. This is not a requirement. diff --git a/docs/best-practices/cost-optimization.mdx b/docs/best-practices/cost-optimization.mdx index 9705672d90..9c9090c822 100644 --- a/docs/best-practices/cost-optimization.mdx +++ b/docs/best-practices/cost-optimization.mdx @@ -266,7 +266,7 @@ Alternatively, if you are looking to do analysis on closed Workflow Executions, - Temporal Cloud Usage dashboard for Actions and Storage metrics - Event History for per-Workflow billable Actions estimates -- Export metrics to observability platforms (Datadog, Grafana, etc.) for custom monitoring +- Export metrics to observability platforms such as Datadog or Grafana for custom monitoring ## When to get help diff --git a/docs/best-practices/managing-namespace.mdx b/docs/best-practices/managing-namespace.mdx index e2a4631668..6f5e983d8e 100644 --- a/docs/best-practices/managing-namespace.mdx +++ b/docs/best-practices/managing-namespace.mdx @@ -70,7 +70,7 @@ Use a pattern like `--` to name Namespaces: :::tip Temporal Cloud Cloud Namespace names are limited to [39 characters](/cloud/namespaces#temporal-cloud-namespace-name). -If you need to include region, use short codes (e.g., `aps1`, `use1`). +If you need to include region, use short codes (for example, `aps1`, `use1`). ::: ## Organizational Patterns diff --git a/docs/best-practices/pre-production-testing.mdx b/docs/best-practices/pre-production-testing.mdx index 43a570e7de..c8866ea425 100644 --- a/docs/best-practices/pre-production-testing.mdx +++ b/docs/best-practices/pre-production-testing.mdx @@ -74,7 +74,7 @@ Depending on execution environment: **What to test** -Periodically restart a fixed or random percentage (e.g. 20-30%) of your Worker fleet every few minutes. +Periodically restart a fixed or random percentage (for example, 20-30%) of your Worker fleet every few minutes. **Why it matters** diff --git a/docs/best-practices/security-controls.mdx b/docs/best-practices/security-controls.mdx index 29b1977a28..5ad9839744 100644 --- a/docs/best-practices/security-controls.mdx +++ b/docs/best-practices/security-controls.mdx @@ -37,7 +37,7 @@ Strong identity management in Temporal Cloud is crucial for ensuring secure acce #### 1. Enable [SAML Single Sign-on](/cloud/manage-access/saml) (SSO) for User Access -Integrate Temporal Cloud with your organization's identity provider via SAML 2.0 for centralized authentication. SSO allows you to enforce your corporate login policies (MFA, password complexity, etc.). When you configure SAML with Temporal Cloud, you can disable social logins (i.e. Microsoft, Google) by opening a support ticket. +Integrate Temporal Cloud with your organization's identity provider via SAML 2.0 for centralized authentication. SSO allows you to enforce your corporate login policies (such as MFA and password complexity). When you configure SAML with Temporal Cloud, you can disable social logins (that is, Microsoft, Google) by opening a support ticket. #### 2. Use Least-Privilege Roles for Temporal Cloud Users @@ -49,7 +49,7 @@ When applicable, use [SCIM](/cloud/manage-access/scim) or the Temporal Cloud use #### Use Service Accounts for Automation -For non-human access (CI/CD pipelines, backend services), use [Temporal Cloud Service Accounts](/cloud/manage-access/service-accounts) instead of shared user logins. Service Accounts are machine identities that can be granted specific permissions without ties to an individual. Create separate Service Accounts with unique API keys for different applications or microservices, and apply least privilege to each (e.g. a service account that only has access to one Namespace). +For non-human access (CI/CD pipelines, backend services), use [Temporal Cloud Service Accounts](/cloud/manage-access/service-accounts) instead of shared user logins. Service Accounts are machine identities that can be granted specific permissions without ties to an individual. Create separate Service Accounts with unique API keys for different applications or microservices, and apply least privilege to each (for example, a service account that only has access to one Namespace). ## Secure Application Authentication and API Access @@ -67,7 +67,7 @@ We recommend you enable mTLS for strong identity assurance of clients; it ensure #### 2. Proactively manage and rotate certificates -Track the expiration dates of your client and [Certificate Authority certificates](/cloud/certificates). Temporal Cloud trusts the uploaded CA; if it expires, all client authorizations will fail. Establish and automate a certificate rotation schedule (e.g. rotate client certificates quarterly and CA certificates annually, well before expiry). Temporal supports uploading a new CA certificate alongside the old one to allow seamless rollover. Always test new certificates in a staging environment if possible. +Track the expiration dates of your client and [Certificate Authority certificates](/cloud/certificates). Temporal Cloud trusts the uploaded CA; if it expires, all client authorizations will fail. Establish and automate a certificate rotation schedule (for example, rotate client certificates quarterly and CA certificates annually, well before expiry). Temporal supports uploading a new CA certificate alongside the old one to allow seamless rollover. Always test new certificates in a staging environment if possible. #### 3. If you’re using API Keys, handle them with strict care @@ -90,9 +90,9 @@ Temporal Cloud supports private connectivity options such as [AWS PrivateLink](/ #### 2. Separate environments by Namespace -Use [Temporal Namespaces](/best-practices/managing-namespace#naming-conventions) to isolate workflows for different environments or teams (e.g. development, staging, production). Each Namespace is logically segregated and cannot interact with others by default, providing a security boundary. +Use [Temporal Namespaces](/best-practices/managing-namespace#naming-conventions) to isolate workflows for different environments or teams (for example, development, staging, production). Each Namespace is logically segregated and cannot interact with others by default, providing a security boundary. -Ensure that your production Namespace uses stricter network controls (e.g. only accessible from the prod network) and that credentials for it are separate from non-prod Namespaces. This limits the impact of any compromise in a lower environment, and as workflow data is only visible to users with access to that Namespace, separating environments by Namespace also enforces data-visibility boundaries. +Ensure that your production Namespace uses stricter network controls (for example, only accessible from the prod network) and that credentials for it are separate from non-prod Namespaces. This limits the impact of any compromise in a lower environment, and as workflow data is only visible to users with access to that Namespace, separating environments by Namespace also enforces data-visibility boundaries. ## Data Protection and Encryption @@ -125,7 +125,7 @@ Temporal Cloud’s platform is engineered for fault-tolerance out of the box, bu | **Single-Region** | **If your application is built for one region and does not have stringent high-availability or disaster recovery requirements.** | 99.9% | ≤ 8 hours | ≤ 8 hours | | **Same-Region Replication** | **If you want higher availability but your application is designed for a single region or if cross region latency doesn’t meet SLAs for application** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) | | **Multi-Region Replication** | **If a disruption of your workflow will cause loss of revenue, poor end-user experience, or issues with regulatory compliance.** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) | -| **Multi-Cloud Replication** | **If you need the highest level of disaster tolerance, protecting against outages of an entire cloud provider (e.g., AWS or GCP)** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) | +| **Multi-Cloud Replication** | **If you need the highest level of disaster tolerance, protecting against outages of an entire cloud provider (for example, AWS or GCP)** | 99.99% | ≤ 20 minutes | Near-zero (≈ seconds) | ### Best Practices: diff --git a/docs/cloud/connectivity/aws-connectivity.mdx b/docs/cloud/connectivity/aws-connectivity.mdx index c8148b1b0c..b8e11efdf1 100644 --- a/docs/cloud/connectivity/aws-connectivity.mdx +++ b/docs/cloud/connectivity/aws-connectivity.mdx @@ -94,8 +94,8 @@ The next step is to [configure private DNS](#configuring-private-dns-for-aws-pri When you connect to Temporal Cloud through AWS PrivateLink you normally must: -1. **Point your SDKs/Workers at the PrivateLink DNS name** for the VPC Endpoint (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`), **and** -2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (e.g., `my-namespace.my-account.tmprl.cloud`). +1. **Point your SDKs/Workers at the PrivateLink DNS name** for the VPC Endpoint (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`), **and** +2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (for example, `my-namespace.my-account.tmprl.cloud`). By creating a Route 53 **private hosted zone (PHZ)** that maps the public Temporal Cloud hostname (or region hostname) to your VPC Endpoint, you can: @@ -154,7 +154,7 @@ Save the **`vpce-*.amazonaws.com`** value — you will target it in the CNAME re #### 2. Create a Route 53 Private Hosted Zone (do not yet attach Worker VPCs) a. Open _Route 53 → Hosted zones → Create hosted zone_. -b. Enter the domain chosen from the table above, e.g., `payments.abcde.tmprl.cloud`. +b. Enter the domain chosen from the table above, for example, `payments.abcde.tmprl.cloud`. c. Type: _Private hosted zone for Temporal Cloud_. d. Leave VPC associations empty for now (you'll add them in step 4). e. Create the hosted zone. @@ -165,7 +165,7 @@ Inside the new PHZ: | Field | Value | | --------------- | ------------------------------------------------------------------------------------- | -| **Record name** | the Namespace Endpoint (e.g., `payments.abcde.tmprl.cloud`). | +| **Record name** | the Namespace Endpoint (for example, `payments.abcde.tmprl.cloud`). | | **Record type** | `CNAME` | | **Value** | Your VPC Endpoint DNS name (`vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com`) | | **TTL** | 60s is typical; 15s for Namespaces with High Availability (to minimize recovery time after failover). | @@ -214,8 +214,8 @@ You can avoid creating DNS records for each Namespace by pointing Workers direct 1. Create the PrivateLink VPC Endpoint (one per region — all Namespaces in that region share it). 2. Configure each Worker with: - - **Endpoint**: the DNS name of the VPC Endpoint in the region where the Worker runs (e.g., `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233`) - - **Server name** (SNI override): the Namespace Endpoint value (e.g., `my-namespace.my-account.tmprl.cloud`) + - **Endpoint**: the DNS name of the VPC Endpoint in the region where the Worker runs (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233`) + - **Server name** (SNI override): the Namespace Endpoint value (for example, `my-namespace.my-account.tmprl.cloud`) With this approach, new Namespaces do not require new DNS records. Workers set their **Endpoint** to the VPC Endpoint DNS name and their **Server name** to the Namespace Endpoint, so the client SDK accepts the TLS handshake from Temporal Cloud. diff --git a/docs/cloud/connectivity/gcp-connectivity.mdx b/docs/cloud/connectivity/gcp-connectivity.mdx index 307e9e7813..ec4dbad866 100644 --- a/docs/cloud/connectivity/gcp-connectivity.mdx +++ b/docs/cloud/connectivity/gcp-connectivity.mdx @@ -110,7 +110,7 @@ See [configuring private DNS for GCP Private Service Connect](#configuring-priva When you connect to Temporal Cloud through GCP Private Service Connect you normally must: 1. **Point your SDKs/Workers at the Private Service Connect endpoint IP address** _and_ -2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (e.g., `my-namespace.my-account.tmprl.cloud`). +2. **Override the Server Name Indicator (SNI)** so that the TLS handshake still presents the public Temporal Cloud hostname (for example, `my-namespace.my-account.tmprl.cloud`). By creating a **private Cloud DNS zone (PZ)** that maps the public Temporal Cloud hostname (or the region hostname) directly to the PSC endpoint IP address, you can: @@ -155,8 +155,8 @@ Save the internal IP -- you will point the A record at it. 1. Open _Network Services → Cloud DNS → Create zone_. 2. Select zone type **Private**. -3. Enter a **Zone name** (e.g., `temporal-cloud`). -4. Enter a **DNS name** based on the table above (e.g., `payments.abcde.tmprl.cloud` or `us-east-1.aws.api.temporal.io`). +3. Enter a **Zone name** (for example, `temporal-cloud`). +4. Enter a **DNS name** based on the table above (for example, `payments.abcde.tmprl.cloud` or `us-east-1.aws.api.temporal.io`). 5. Select **Add networks** and choose the Project and Network that contains your PSC endpoint. 6. Click **Create**. @@ -166,10 +166,10 @@ Inside the new zone, add a _standard A record_: | Field | Value | | -------------------- | -------------------------------------------------------------- | -| DNS name | the namespace endpoint (e.g. `payments.abcde.tmprl.cloud`) | +| DNS name | the namespace endpoint (for example, `payments.abcde.tmprl.cloud`) | | Resource record type | A | | TTL | 60s is typical, but you can adjust as needed. | -| IPv4 Address | the internal IP address of your PSC endpoint (e.g. `10.1.2.3`) | +| IPv4 Address | the internal IP address of your PSC endpoint (for example, `10.1.2.3`) | #### 4. Verify DNS resolution from inside the Network diff --git a/docs/cloud/connectivity/index.mdx b/docs/cloud/connectivity/index.mdx index 7fcbaa86d5..f98fb1615c 100644 --- a/docs/cloud/connectivity/index.mdx +++ b/docs/cloud/connectivity/index.mdx @@ -223,16 +223,16 @@ We strongly recommend using private DNS instead of updating client server and TL If you are unable to configure private DNS, you must update two settings in your Temporal clients: -1. Set the endpoint server address to the PrivateLink or Private Service Connect endpoint (e.g. `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233` or `:7233`). -2. Set TLS configuration to override the TLS server name (the Namespace Endpoint, e.g., `my-namespace.my-account.tmprl.cloud`). +1. Set the endpoint server address to the PrivateLink or Private Service Connect endpoint (for example, `vpce-0123456789abcdef-abc.us-east-1.vpce.amazonaws.com:7233` or `:7233`). +2. Set TLS configuration to override the TLS server name (the Namespace Endpoint, for example, `my-namespace.my-account.tmprl.cloud`). The TLS server name override depends on your authentication method: | Authentication | TLS server name to use | | -------------- | ---------------------- | -| mTLS (single-region Namespace) | The Namespace Endpoint, e.g. `my-namespace.my-account.tmprl.cloud` | -| API key (single-region Namespace) | The regional API endpoint, e.g. `us-east-1.aws.api.temporal.io` or `us-central1.gcp.api.temporal.io` | -| Multi-region Namespace (mTLS or API key) | The active region endpoint, e.g. `us-east-1.aws.api.temporal.io` | +| mTLS (single-region Namespace) | The Namespace Endpoint, for example `my-namespace.my-account.tmprl.cloud` | +| API key (single-region Namespace) | The regional API endpoint, for example `us-east-1.aws.api.temporal.io` or `us-central1.gcp.api.temporal.io` | +| Multi-region Namespace (mTLS or API key) | The active region endpoint, for example `us-east-1.aws.api.temporal.io` | If you authenticate with an API key over PrivateLink/PSC and use the wrong server name, the TLS handshake will fail with errors such as `connection reset by peer` even though `nc` reports the port as open. diff --git a/docs/cloud/get-started/namespaces.mdx b/docs/cloud/get-started/namespaces.mdx index e1f3a78ba7..7838e7575e 100644 --- a/docs/cloud/get-started/namespaces.mdx +++ b/docs/cloud/get-started/namespaces.mdx @@ -424,7 +424,7 @@ track, and manage namespaces more easily. ### Tag Structure and Limits - Each namespace can have a maximum of 10 tags -- Each key must be unique for a given namespace (e.g., a namespace cannot have both `team:foo` and `team:bar` tags) +- Each key must be unique for a given namespace (for example, a namespace cannot have both `team:foo` and `team:bar` tags) - Keys and values must be 1-63 characters in length - Allowed characters: lowercase letters (`a-z`), numbers (`0-9`), periods (`.`), underscores (`_`), hyphens (`-`), and at signs (`@`) diff --git a/docs/cloud/high-availability/failovers/index.mdx b/docs/cloud/high-availability/failovers/index.mdx index 466d4651f6..63857dbf64 100644 --- a/docs/cloud/high-availability/failovers/index.mdx +++ b/docs/cloud/high-availability/failovers/index.mdx @@ -81,7 +81,7 @@ list, and it may change over time. You can also [manually trigger a failover](/cloud/high-availability/failovers/manage#trigger-failover) based on your own monitoring or for failover testing. -Most Namespaces with High Availability are well-served by automatic failovers. The cases where a manual failover (i.e., +Most Namespaces with High Availability are well-served by automatic failovers. The cases where a manual failover (that is, a failover triggered by a user) is warranted are: - **Testing failover or migrating to a new region.** A manual failover is the standard way to exercise your failover @@ -158,7 +158,7 @@ non-graceful failover, replication lag causes a temporary setback in Workflow pr failover: - Operations that had already replicated remain durable in the replica. -- Operations that had not yet replicated (i.e., that are still in the replication backlog) are reconciled when the +- Operations that had not yet replicated (that is, that are still in the replication backlog) are reconciled when the region recovers, according to the conflict resolution process. :::caution Conflict resolution requires a recoverable region diff --git a/docs/cloud/high-availability/ha-connectivity.mdx b/docs/cloud/high-availability/ha-connectivity.mdx index 1243c61c7f..a1a42d7876 100644 --- a/docs/cloud/high-availability/ha-connectivity.mdx +++ b/docs/cloud/high-availability/ha-connectivity.mdx @@ -274,7 +274,7 @@ Plan for these three things: 1. **DNS overrides for both clouds.** Your private DNS for `region.tmprl.cloud` needs entries for both the AWS region (CNAME → AWS VPCE) and the GCP region (A → PSC IP). This typically means a Route 53 private hosted zone in your AWS Worker VPCs *and* a Cloud DNS private zone in your GCP Worker network — both for the same `region.tmprl.cloud` parent — each with the records relevant to the cloud the Workers run in. 2. **Worker reachability across clouds.** Your AWS-resident Workers must be able to reach the GCP PSC endpoint when GCP is active, and vice versa. Options include: - Run Workers in both clouds (preferred — simplest, lowest latency, matches the failover model). - - Establish cross-cloud connectivity (e.g., AWS Transit Gateway + GCP Cloud Interconnect, or a third-party transit) so Workers in one cloud can resolve and reach the other cloud's private endpoint. + - Establish cross-cloud connectivity (for example, AWS Transit Gateway + GCP Cloud Interconnect, or a third-party transit) so Workers in one cloud can resolve and reach the other cloud's private endpoint. 3. **Connectivity Rules in both regions.** GCP PSC requires a Connectivity Rule. AWS PrivateLink does not, but if you want to enforce private-only access, add one for the AWS side as well so the Namespace is private-only in both regions. :::caution Alpine/musl + GCP PSC: missing AAAA records can break Workers @@ -284,7 +284,7 @@ GCP Private Service Connect endpoints return only A (IPv4) records — there is If you run Workers on Alpine and use multi-cloud HA, either: - Switch the Worker base image to a glibc-based distribution (Debian, Ubuntu, distroless), or -- Configure your application/runtime to disable AAAA lookups (e.g., set `GODEBUG=netdns=go+v4` for Go, or prefer IPv4 in the Java/Node/Python runtimes you use). +- Configure your application/runtime to disable AAAA lookups (for example, set `GODEBUG=netdns=go+v4` for Go, or prefer IPv4 in the Java/Node/Python runtimes you use). ::: diff --git a/docs/cloud/manage-access/service-accounts.mdx b/docs/cloud/manage-access/service-accounts.mdx index d93d4df7ad..30ea3be289 100644 --- a/docs/cloud/manage-access/service-accounts.mdx +++ b/docs/cloud/manage-access/service-accounts.mdx @@ -197,7 +197,7 @@ In particular, a Namespace-scoped Service Account must _always_ have: - A `Read` Account Role - A single Namespace Permission -Note that a Namespace-scoped Service Account cannot be reassigned to a different Namespace after creation, but its Namespace permission can be modified (e.g. from `Read` to `Write`). +Note that a Namespace-scoped Service Account cannot be reassigned to a different Namespace after creation, but its Namespace permission can be modified (for example, from `Read` to `Write`). Namespace-scoped Service Accounts are useful in situations when you need to restrict a client's access to a single Namespace. diff --git a/docs/cloud/manage-access/users.mdx b/docs/cloud/manage-access/users.mdx index 3f93c1739e..a2475c2113 100644 --- a/docs/cloud/manage-access/users.mdx +++ b/docs/cloud/manage-access/users.mdx @@ -73,7 +73,7 @@ If your account does not have an Account Owner, please reach out to [Support](ht ## Using the Account Owner role -The Account Owner role (i.e., users with the Account Owner system role) holds the highest level of access in the system. +The Account Owner role (that is, users with the Account Owner system role) holds the highest level of access in the system. This role configures account-level parameters and manages Temporal billing and payment information. It allows users to perform all actions within the Temporal Cloud account. diff --git a/docs/cloud/metrics/openmetrics/api-reference.mdx b/docs/cloud/metrics/openmetrics/api-reference.mdx index f5745fb7a1..2be6e66894 100644 --- a/docs/cloud/metrics/openmetrics/api-reference.mdx +++ b/docs/cloud/metrics/openmetrics/api-reference.mdx @@ -70,8 +70,8 @@ A metric is a numeric attribute measured at a specific point in time, labeled wi All Temporal Cloud metrics are exposed as *gauges* in OpenMetrics format, but represent different measurement types: -* **Rate metrics**: Pre-computed per-second rates with delta temporality (e.g., `temporal_cloud_v1_workflow_success_count` \- workflows completed per second) -* **Value metrics**: Current or instantaneous values (e.g., `temporal_cloud_v1_approximate_backlog_count` \- current number of tasks in queue) +* **Rate metrics**: Pre-computed per-second rates with delta temporality (for example, `temporal_cloud_v1_workflow_success_count` \- workflows completed per second) +* **Value metrics**: Current or instantaneous values (for example, `temporal_cloud_v1_approximate_backlog_count` \- current number of tasks in queue) The list of metrics and their labels are available via the [List Descriptors](/cloud/metrics/openmetrics/api-reference#list-metric-descriptors) endpoint or in the [Metrics Reference](/cloud/metrics/openmetrics/metrics-reference). @@ -164,7 +164,7 @@ To account for metric data latency, this endpoint returns metrics from the curre | Parameter | Type | Description | | ----- | ----- | ----- | -| `namespaces` | string array | Filter to specific Namespaces. Supports wildcards (e.g., `production-*`) | +| `namespaces` | string array | Filter to specific Namespaces. Supports wildcards (for example, `production-*`) | | `metrics` | string array | Filter to specific metrics | Array parameters use repeated keys. To pass multiple values, repeat the parameter name once per value: diff --git a/docs/cloud/metrics/openmetrics/index.mdx b/docs/cloud/metrics/openmetrics/index.mdx index b13e7e81d6..bcc1f8e33e 100644 --- a/docs/cloud/metrics/openmetrics/index.mdx +++ b/docs/cloud/metrics/openmetrics/index.mdx @@ -38,7 +38,7 @@ Stream metrics from Temporal Cloud into your observability tool in about 5 minut **Prerequisites** - An **Account Owner** or **Global Admin** role on the Temporal Cloud account. The Metrics Read-Only role is an account-level role and can only be granted by these roles. A Namespace Admin cannot complete these steps. -- An account in the observability tool you want to use (Datadog, Grafana Cloud, New Relic, ClickStack, self-hosted Prometheus, etc.). +- An account in the observability tool you want to use, such as Datadog, Grafana Cloud, New Relic, ClickStack, or self-hosted Prometheus. **Steps** diff --git a/docs/cloud/metrics/openmetrics/metrics-reference.mdx b/docs/cloud/metrics/openmetrics/metrics-reference.mdx index a364c56dc8..95f65e4ad8 100644 --- a/docs/cloud/metrics/openmetrics/metrics-reference.mdx +++ b/docs/cloud/metrics/openmetrics/metrics-reference.mdx @@ -31,7 +31,7 @@ This document describes all metrics available from the Temporal Cloud OpenMetric All metrics are exposed as OpenMetrics gauges, but represent different measurement types: * *Rate Metrics*: per-second rate of the aggregated values -* *Value Metrics*: The most recent aggregate value within a look-back window (e.g. backlogs, limits) +* *Value Metrics*: The most recent aggregate value within a look-back window (for example, backlogs, limits) * *Percentile Metrics*: Pre-calculated aggregated latency percentiles in seconds :::note diff --git a/docs/cloud/metrics/openmetrics/migration-guide.mdx b/docs/cloud/metrics/openmetrics/migration-guide.mdx index a0bd87541d..3695ddc29d 100644 --- a/docs/cloud/metrics/openmetrics/migration-guide.mdx +++ b/docs/cloud/metrics/openmetrics/migration-guide.mdx @@ -40,7 +40,7 @@ Complete your migration to the OpenMetrics endpoint before this date. ## Why We're Making This Change 1. **Industry-Standard Format**: Native compatibility with Prometheus and OpenTelemetry and all major observability - platforms (Datadog, New Relic etc.) without custom integrations. + platforms such as Datadog or New Relic without custom integrations. 2. **High-Cardinality Metrics**: Access to previously unavailable dimensions including: - `temporal_task_queue` labels on multiple metrics @@ -453,7 +453,7 @@ match exactly between the two endpoints. Some metrics may be consistently differ `temporal_cloud_v1_total_action_count` which includes History Export actions in the OpenMetrics endpoint. In the case of consistent differences the OpenMetrics endpoint is considered to be more accurate. -### Can I still query metrics directly (e.g. with a Grafana dashboard)? +### Can I still query metrics directly (for example, with a Grafana dashboard)? Currently, the OpenMetrics endpoint requires an observability platform to collect and query metrics. Direct querying via API to return a time series of data is not supported. Supporting this type of query pattern is a future roadmap item. diff --git a/docs/cloud/migrate/automated.mdx b/docs/cloud/migrate/automated.mdx index de087b4034..27c234cf8e 100644 --- a/docs/cloud/migrate/automated.mdx +++ b/docs/cloud/migrate/automated.mdx @@ -451,7 +451,7 @@ The following are known limitations. - OSS server versions 1.22 or newer are required. Refer to the [upgrade](/self-hosted-guide/upgrade-server#upgrade-server) procedure as needed. -- History shard counts must be a power of two (eg. 512, 1024, etc...). +- History shard counts must be a power of two (for example, 512 or 1024). - If you have multiple self-hosted servers and they are all configured with the same cluster name (by default Temporal uses 'active' as cluster name), they cannot be connected to a single migration server simultaneously due to cluster name collision. There are 2 available options: @@ -462,8 +462,8 @@ The following are known limitations. this may impact your eligibility for automated migration. Specifically, whenever Global Namespace has been previously enabled the following restrictions apply: 1. Initial Failover Version must be less than or equal to 1,000,000 - 2. Failover Version Increment must be a divisor of 1,000,000 (eg. 10) -- OSS supports cross-Namespace commands (e.g., parent-child, SignalExternal, CancelExternal) through the + 2. Failover Version Increment must be a divisor of 1,000,000 (for example, 10) +- OSS supports cross-Namespace commands (for example, parent-child, SignalExternal, CancelExternal) through the `system.enableCrossNamespaceCommands` configuration. This configuration is disabled on Temporal Cloud. The `system.enableCrossNamespaceCommands` configuration must be disabled, and code using cross-Namespace calls must be updated or removed prior to migration. diff --git a/docs/cloud/notifications.mdx b/docs/cloud/notifications.mdx index d7b4c7974c..e59e6c7b96 100644 --- a/docs/cloud/notifications.mdx +++ b/docs/cloud/notifications.mdx @@ -22,7 +22,7 @@ tags: ## Get notified about Temporal Cloud status {/* #cloud-status */} In the event of an incident, Temporal updates the [Temporal Cloud status page](https://status.temporal.io/) with important updates. -Users can subscribe to updates in their preferred mode (e.g. email, Slack, SMS, etc.) by visiting this page. +Users can subscribe to updates in their preferred mode, such as email, Slack, or SMS, by visiting this page. ## Get notified about administrative events {/* #admin-notifications */} diff --git a/docs/cloud/operation-api.mdx b/docs/cloud/operation-api.mdx index 9c2f8c83c5..0f85cb2fe3 100644 --- a/docs/cloud/operation-api.mdx +++ b/docs/cloud/operation-api.mdx @@ -176,7 +176,7 @@ This limit applies to all requests made by each service account through any clie **Asynchronous operations: 10 concurrent operations at a time** -By default, each account can have up to 10 long-running (asynchronous) mutating operations in flight at once. This limit applies to a subset of create, update, and delete operations (for example Namespace, User, API Key, Export Sink, and Service Account mutations), not every RPC that returns an async operation. +By default, each account can have up to 10 long-running (asynchronous) mutating operations in flight at once. This limit applies to a subset of create, update, and delete operations (for example, Namespace, User, API Key, Export Sink, and Service Account mutations), not every RPC that returns an async operation. ### Important considerations diff --git a/docs/cloud/rto-rpo.mdx b/docs/cloud/rto-rpo.mdx index 123c901ed4..07d02dc72c 100644 --- a/docs/cloud/rto-rpo.mdx +++ b/docs/cloud/rto-rpo.mdx @@ -296,7 +296,7 @@ benefits to combining a manual failover process with automatic failovers: - Even if you have robust tooling to detect an outage and trigger a failover, leaving automatic failovers enabled provides a "safety net" in case your automation misses an outage. It also gives Temporal leeway to - preemptively fail over your Namespace if we detect that it may be disrupted soon, e.g., by a rolling failure that has + preemptively fail over your Namespace if we detect that it may be disrupted soon, for example, by a rolling failure that has impacted other Namespaces but not yours, yet. ## Comparing RTO and SLA @@ -310,7 +310,7 @@ and apply in different situations. | How is it measured? | The achieved recovery time is measured in terms of minutes per outage. | The achieved service error rate is measured in terms of error rate per month. | | How is the calculation performed? | The achieved recovery time in a given outage is the total time between when a disruption to a Namespace began and when the Namespace was restored to full functionality, either after a failover to a healthy region or after the outage has been mitigated. | Temporal measures the percentage of requests to Temporal Cloud that fail, and applies a [formula](/cloud/sla) to get the final percentage for the month. | | Do partial degradations count? | Most outages contain periods of **partial degradation** where some percentage of Namespace operations fail while the rest complete as normal. When they disrupt a Namespace, periods of partial degradation count in the calculation of the recovery time. | Partial degradations only partially count for the service error rate calculation. A 5-minute window with a 10% error rate would count less than a 5-minute window with a 100% error rate. | -| What is excluded? | For partial degradations, what counts as a disruption to a Namespace is subject to Temporal's expert judgment, but a good rule of thumb is a service error rate >=10%. | We exclude outages that are out of Temporal's control to mitigate, e.g., a failure of the underlying cloud provider infrastructure that affects a Namespace without High Availability and automatic failovers enabled. If a Namespace has the relevant High Availability feature and has automatic failovers enabled, then Temporal can act to mitigate the outage and it does usually count against the SLA. Full exclusions on the [SLA page](/cloud/sla). | +| What is excluded? | For partial degradations, what counts as a disruption to a Namespace is subject to Temporal's expert judgment, but a good rule of thumb is a service error rate >=10%. | We exclude outages that are out of Temporal's control to mitigate, for example, a failure of the underlying cloud provider infrastructure that affects a Namespace without High Availability and automatic failovers enabled. If a Namespace has the relevant High Availability feature and has automatic failovers enabled, then Temporal can act to mitigate the outage and it does usually count against the SLA. Full exclusions on the [SLA page](/cloud/sla). | The following examples illustrate the RTO and SLA calculations for different types of outages in a regional outage. These hypothetical Namespaces are based on actual Temporal Cloud performance in a diff --git a/docs/cloud/service-health.mdx b/docs/cloud/service-health.mdx index d38757b413..c3371a1feb 100644 --- a/docs/cloud/service-health.mdx +++ b/docs/cloud/service-health.mdx @@ -175,7 +175,7 @@ that creates demo charts for these limits and count metrics respectively. The limit metrics, throttle metrics, and count metrics are already directly comparable as per second rates. Keep in mind that each `count` metric is represented as a per second rate averaged over each minute. For example, to get the total count of Actions, you must multiply this metric by 60. -When setting alerts against limits, consider if your workload is spiky or sensitive to throttling (e.g. does latency matter?). If your workload is sensitive, consider alerting +When setting alerts against limits, consider if your workload is spiky or sensitive to throttling (for example, does latency matter?). If your workload is sensitive, consider alerting for `temporal_cloud_v1_total_action_count` at a 50% threshold of the `temporal_cloud_v1_action_limit`. If your workload is not sensitive, consider an alert at 90% of this threshold or directly when throttling is detected as a value greater than zero for `temporal_cloud_v1_total_action_throttled_count`. This logic can also be used to automatically scale [Temporal Resource Units](/cloud/capacity-modes#provisioned-capacity) up or down as needed. Some workloads choose to exceed limits and accept throttling because they are not latency sensitive. @@ -225,9 +225,9 @@ To understand a spiky workload, always read all three metrics in the row as a se | Metric | What it tells you | | ------ | ----------------- | -| Count (e.g. `temporal_cloud_v1_total_action_count`) | Average demand over the minute | -| Limit (e.g. `temporal_cloud_v1_action_limit`) | Your provisioned ceiling | -| Throttle (e.g. `temporal_cloud_v1_total_action_throttled_count`) | Whether the limit was actually hit | +| Count (for example, `temporal_cloud_v1_total_action_count`) | Average demand over the minute | +| Limit (for example, `temporal_cloud_v1_action_limit`) | Your provisioned ceiling | +| Throttle (for example, `temporal_cloud_v1_total_action_throttled_count`) | Whether the limit was actually hit | A non-zero throttle value means throttling occurred during that window, even when the count sits comfortably below the limit. Most often this reflects a sub-minute burst in your own workload. If you cannot find a matching burst in your SDK metrics, the cause may be a shared limit or another Cloud-side condition rather than your namespace. In that case, contact [Temporal Support](/cloud/support#support-ticket). For spiky or latency-sensitive workloads, alert on the throttle metric directly (any value greater than zero) rather than relying only on a count-versus-limit threshold, which can hide sub-minute bursts. The same logic applies to all three limit types — Actions (APS), service requests (RPS), and operations — using each row of the [limit / count / throttle table](#rps-aps-rate-limits) above. diff --git a/docs/cloud/tcld/apikey.mdx b/docs/cloud/tcld/apikey.mdx index 65b0b0dc68..69bcf2c6fe 100644 --- a/docs/cloud/tcld/apikey.mdx +++ b/docs/cloud/tcld/apikey.mdx @@ -92,7 +92,7 @@ Alias: `oid` #### --owner-type -Filter API keys by owner type (i.e. 'user', 'service-account') +Filter API keys by owner type (that is, 'user', 'service-account') Alias: `ot` diff --git a/docs/cloud/tcld/namespace.mdx b/docs/cloud/tcld/namespace.mdx index 87f453b82d..071c297a6f 100644 --- a/docs/cloud/tcld/namespace.mdx +++ b/docs/cloud/tcld/namespace.mdx @@ -77,7 +77,7 @@ Alias: `rd` #### --auth-method -The authentication method to use for the namespace (e.g. 'mtls', 'api_key') +The authentication method to use for the namespace (for example, 'mtls', 'api_key') #### --ca-certificate-file @@ -486,7 +486,7 @@ Alias: `v` ##### --auth-method -The authentication method used for the namespace (i.e. 'restricted', 'mtls', 'api_key', 'api_key_or_mtls') +The authentication method used for the namespace (that is, 'restricted', 'mtls', 'api_key', 'api_key_or_mtls') Alias: `am` diff --git a/docs/cloud/worker-health.mdx b/docs/cloud/worker-health.mdx index 4e95e91b28..de81e116af 100644 --- a/docs/cloud/worker-health.mdx +++ b/docs/cloud/worker-health.mdx @@ -197,7 +197,7 @@ There are three typical causes for this: - There are not enough workers to perform work - Each worker is either under resourced, or is misconfigured, to handle enough work -- There is congestion caused by the environment (eg., network) hosting the worker(s) and Temporal Cloud +- There is congestion caused by the environment (for example, network) hosting the worker(s) and Temporal Cloud Consider diff --git a/docs/design-patterns/delayed-callback.mdx b/docs/design-patterns/delayed-callback.mdx index 298a7ecdec..8ccb1356af 100644 --- a/docs/design-patterns/delayed-callback.mdx +++ b/docs/design-patterns/delayed-callback.mdx @@ -23,7 +23,7 @@ Temporal lets you build durable, observable webhook-based integrations without a ## Problem Waiting for another system without Durable Execution is hard. You must implement your own: -- durable timers (e.g. with a cron per timer) +- durable timers (for example, with a cron per timer) - retry queues - state stores - reconciliation jobs @@ -715,7 +715,7 @@ func CompleteJob(ctx context.Context, c client.Client, jobID string, result stri **Trade-offs** - Your inbound webhook handler requires a Temporal client; you need the client library in the service receiving webhooks. -- Task tokens for async completion must be persisted outside Temporal (e.g., in a database); if that store is unavailable the callback cannot complete. +- Task tokens for async completion must be persisted outside Temporal (for example, in a database); if that store is unavailable the callback cannot complete. - Workflow IDs must be deterministic and stable across webhook deliveries (order ID, user ID, etc.) so that Signal-with-Start routes to the correct instance. ## Comparison with alternatives diff --git a/docs/design-patterns/eager-workflow-start.mdx b/docs/design-patterns/eager-workflow-start.mdx index 0c9cb3f116..88cf4cbac5 100644 --- a/docs/design-patterns/eager-workflow-start.mdx +++ b/docs/design-patterns/eager-workflow-start.mdx @@ -44,7 +44,7 @@ sequenceDiagram 1. In a normal start, the server queues the Workflow execution and the Matching Service waits for an available Worker slot. The Worker polls, picks up the task, runs it, and reports back—adding an extra server round-trip. 2. With Eager Workflow Start enabled, the server detects that the requesting client has a co-located Worker with an available slot. Instead of queuing the task, the server attaches the first Workflow Task to the `StartWorkflowExecution` response. 3. The Worker processes the Workflow Task immediately upon receiving the response. No separate poll is required. -4. If the server cannot fulfill the eager request (e.g., no local slot is available), it falls back silently to normal dispatch. Your code does not need to handle this case explicitly. +4. If the server cannot fulfill the eager request (for example, no local slot is available), it falls back silently to normal dispatch. Your code does not need to handle this case explicitly. ## Problem @@ -187,7 +187,7 @@ The TypeScript SDK does not currently support Eager Workflow Start. Use [Local A **Good fit:** -- The workflow starter and Worker run in the same deployment unit (e.g., a single service that both handles API requests and runs Workers) +- The workflow starter and Worker run in the same deployment unit (for example, a single service that both handles API requests and runs Workers) - You need the absolute minimum total-workflow latency and are already using Local Activities - The language is Go, Java, or Python @@ -212,7 +212,7 @@ The TypeScript SDK does not currently support Eager Workflow Start. Use [Local A - **Combine with Local Activities.** Eager Workflow Start eliminates the Matching overhead on the first Workflow Task; Local Activities eliminate server round-trips within each Workflow Task. Together they provide the greatest total latency reduction. - **Use a non-blocking Worker start.** Start the Worker before executing the Workflow so it has an available slot. In Go, use `w.Start()` and defer `w.Stop()`. In Python, use `async with Worker(...)`. In Java, call `factory.start()` before creating the workflow stub. -- **Do not rely on eager dispatch always firing.** The server falls back to normal dispatch if no local slot is available (e.g., the Worker is at capacity). Design the Workflow to work correctly in both cases. +- **Do not rely on eager dispatch always firing.** The server falls back to normal dispatch if no local slot is available (for example, the Worker is at capacity). Design the Workflow to work correctly in both cases. - **Share the same client and connection.** The Worker and the workflow starter must use the same `WorkflowClient` instance (Java), `client.Client` (Go), or `Client` (Python). A Worker using a different connection cannot receive eager tasks from another client. - **Be mindful of resource sharing in co-located deployments.** When a Worker runs in the same process as a request handler, they share CPU, memory, and failure domains. A spike in activity execution can slow request handling, and vice versa. Monitor Worker CPU, Workflow Task execution latency, and task queue depth to ensure Worker load does not affect client-facing latency. diff --git a/docs/design-patterns/early-return-local-activities.mdx b/docs/design-patterns/early-return-local-activities.mdx index c23660dce4..6f70dc4a62 100644 --- a/docs/design-patterns/early-return-local-activities.mdx +++ b/docs/design-patterns/early-return-local-activities.mdx @@ -308,7 +308,7 @@ public class Impl implements TransactionWorkflow { ## Common pitfalls - **Putting slow operations in Phase 1.** If any Phase 1 Local Activity takes too long, the Workflow Task times out and retries. The client also waits longer for its early response, defeating the purpose of the pattern. -- **Non-idempotent Phase 1.** A retried Workflow Task re-executes all Local Activities in that task. Ensure Phase 1 operations (e.g., creating a record in an external system) are safe to re-run. +- **Non-idempotent Phase 1.** A retried Workflow Task re-executes all Local Activities in that task. Ensure Phase 1 operations (for example, creating a record in an external system) are safe to re-run. - **Ignoring Phase 1 errors in Phase 2.** Always check Phase 1 error state before proceeding to Phase 2. If Phase 1 failed, Phase 2 should run a compensating Activity (cancel, rollback) rather than complete. - **Mixing Local and regular Activity stubs incorrectly.** In Java, `Workflow.newLocalActivityStub` and `Workflow.newActivityStub` return distinct objects. Make sure Phase 1 uses the local stub and Phase 2 uses the regular stub. diff --git a/docs/design-patterns/event-accumulator.mdx b/docs/design-patterns/event-accumulator.mdx index e6aeb4c9ce..89865041c6 100644 --- a/docs/design-patterns/event-accumulator.mdx +++ b/docs/design-patterns/event-accumulator.mdx @@ -360,7 +360,7 @@ Producers in all SDKs call Signal-With-Start to atomically start the workflow if The Accumulator pattern is well suited when events related to the same entity or group arrive from multiple producers — including a single consumer (for example, a Kafka consumer) polling a topic that carries events for multiple groups simultaneously — and can be processed together as batches, when downstream systems prefer batched calls rather than one call per event, and when at-least-once event delivery makes deduplication necessary at the collection layer. -It is not a good fit for use cases that require processing every event individually in _strict order_, for cases where the batch size is known in advance and all events arrive within a short deterministic window (a standard workflow is sufficient), or when events for different keys must be correlated at processing time (consider fan-in with e.g. Child Workflows or multiple levels of Accumulator). +It is not a good fit for use cases that require processing every event individually in _strict order_, for cases where the batch size is known in advance and all events arrive within a short deterministic window (a standard workflow is sufficient), or when events for different keys must be correlated at processing time (consider fan-in with for example Child Workflows or multiple levels of Accumulator). ## Benefits and trade-offs diff --git a/docs/design-patterns/fairness.mdx b/docs/design-patterns/fairness.mdx index 17f692ddc2..1f96fb9673 100644 --- a/docs/design-patterns/fairness.mdx +++ b/docs/design-patterns/fairness.mdx @@ -18,7 +18,7 @@ The Fairness pattern distributes Worker capacity proportionally across tenants o ## Problem -When multiple tenants (e.g. customers) share a single Task Queue, a high-volume tenant can fill the queue and occupy all Worker slots. Other tenants receive no service until the dominant tenant's backlog drains. This starvation violates throughput guarantees and makes latency for lower-volume tenants unpredictable under burst conditions. +When multiple tenants (for example, customers) share a single Task Queue, a high-volume tenant can fill the queue and occupy all Worker slots. Other tenants receive no service until the dominant tenant's backlog drains. This starvation violates throughput guarantees and makes latency for lower-volume tenants unpredictable under burst conditions. The classic workaround—assigning one Task Queue per tenant—scales poorly: each new tenant requires a new Worker deployment, idle capacity on low-traffic tenants cannot be used by busy ones, and queue management complexity grows with tenant count. diff --git a/docs/design-patterns/mapreduce-tree.mdx b/docs/design-patterns/mapreduce-tree.mdx index bbdde190cf..43282d7001 100644 --- a/docs/design-patterns/mapreduce-tree.mdx +++ b/docs/design-patterns/mapreduce-tree.mdx @@ -418,7 +418,7 @@ public class NodeWorkflowImpl implements NodeWorkflow { ## Best practices - **Set a `leafThreshold` to control tree depth.** A threshold of 3–10 records per leaf is typical. Too small a threshold creates excessive Workflow overhead; too large prevents full parallelism. -- **Set a `MAX_DEPTH` guard.** Recursive fan-out without a depth limit can produce extremely deep trees for large record sets. Fail fast if depth exceeds your expected maximum (e.g. `log2(totalRecords / leafThreshold) + 2`). +- **Set a `MAX_DEPTH` guard.** Recursive fan-out without a depth limit can produce extremely deep trees for large record sets. Fail fast if depth exceeds your expected maximum (for example, `log2(totalRecords / leafThreshold) + 2`). - **Avoid external writes in Node Workflows.** Node Workflows only aggregate results from children. Leaf Workflows perform the actual work. Keeping the roles separate prevents duplicate external writes if a Node is retried. - **Use signals for result aggregation, not return values.** A parent cannot directly await a child started in a previous Workflow run. Signals decouple the result delivery from the parent-child lifetime, making the pattern resilient to replays. - **Skip the reduce phase if results are not needed.** If you only need the side effects of processing each record (writes to a database, messages sent), omit the signal-back entirely and set `PARENT_CLOSE_POLICY_ABANDON` on all children. diff --git a/docs/design-patterns/parallel-execution.mdx b/docs/design-patterns/parallel-execution.mdx index 262fa3c487..4675e07ddc 100644 --- a/docs/design-patterns/parallel-execution.mdx +++ b/docs/design-patterns/parallel-execution.mdx @@ -515,7 +515,7 @@ You may overwhelm external services without throttling, and storing many Futures ## Common pitfalls - **Exceeding the pending Activities limit.** A single Workflow Execution can have at most 2,000 pending (concurrently running) Activities. Scheduling more causes Workflow Task failures. Batch Activities or use child Workflows for higher concurrency. -- **Ignoring errors from individual Activities.** Waiting for all results (e.g., `Promise.allOf()` in Java, `Promise.all()` in TypeScript, `asyncio.gather()` in Python) fails on the first error by default. If you need partial results, catch errors inside each async function or use `Promise.allSettled()` / `return_exceptions=True` / per-Future error checking. +- **Ignoring errors from individual Activities.** Waiting for all results (for example, `Promise.allOf()` in Java, `Promise.all()` in TypeScript, `asyncio.gather()` in Python) fails on the first error by default. If you need partial results, catch errors inside each async function or use `Promise.allSettled()` / `return_exceptions=True` / per-Future error checking. - **Blowing the 4 MB gRPC message limit.** Scheduling hundreds of Activities in a single Workflow Task can exceed the 4 MB gRPC message size limit if their combined inputs are large. Batch scheduling across multiple Workflow Tasks. - **Not using Continue-As-New for large fan-outs.** Each Activity adds events to history. Hundreds of parallel Activities can quickly approach the 50K event limit. Use Continue-As-New or child Workflows to partition work. diff --git a/docs/design-patterns/pick-first.mdx b/docs/design-patterns/pick-first.mdx index 7e82065f55..b4ad5e1930 100644 --- a/docs/design-patterns/pick-first.mdx +++ b/docs/design-patterns/pick-first.mdx @@ -542,7 +542,7 @@ Only the first result is used; others are discarded. ## Common pitfalls - **Missing heartbeats in Activities.** Activities must heartbeat to detect cancellation. Without heartbeats, cancelled Activities continue running until their StartToCloseTimeout expires, wasting resources. -- **Not waiting for cancellation cleanup.** Without configuring the cancellation type to wait for completion (e.g., `WaitForCancellation: true` in Go, `WAIT_CANCELLATION_COMPLETED` in other SDKs), fetching a cancelled Activity's result returns a cancellation error immediately, before the Activity has finished cleanup. Configure this setting if you need to wait for cleanup to complete. +- **Not waiting for cancellation cleanup.** Without configuring the cancellation type to wait for completion (for example, `WaitForCancellation: true` in Go, `WAIT_CANCELLATION_COMPLETED` in other SDKs), fetching a cancelled Activity's result returns a cancellation error immediately, before the Activity has finished cleanup. Configure this setting if you need to wait for cleanup to complete. - **Ignoring errors from the winning Activity.** The first Activity to complete might return an error. Always check the result for errors rather than assuming success. - **Forgetting to cancel remaining Activities.** If you forget to cancel the shared context or scope after receiving the first result, the remaining Activities continue running indefinitely. diff --git a/docs/design-patterns/retry-metrics.mdx b/docs/design-patterns/retry-metrics.mdx index ef39080a52..7ee3236cfe 100644 --- a/docs/design-patterns/retry-metrics.mdx +++ b/docs/design-patterns/retry-metrics.mdx @@ -32,7 +32,7 @@ Common gaps: ## Solution Read the current attempt number from the Activity execution context and emit a counter metric when it exceeds a threshold. -The metric is sent through the Temporal SDK's built-in metrics scope — the same pipeline used for SDK-internal metrics — so it flows to whatever metrics backend your Workers are already configured to use (Prometheus, StatsD, etc.) without additional setup. +The metric is sent through the Temporal SDK's built-in metrics scope — the same pipeline used for SDK-internal metrics — so it flows to whatever metrics backend your Workers are already configured to use, such as Prometheus or StatsD, without additional setup. ```mermaid sequenceDiagram @@ -357,7 +357,7 @@ if (ctx.info.attempt > ALERT_THRESHOLD) { - **Choose a threshold above normal transient noise.** If your downstream system occasionally has 1–2 retry attempts under normal conditions, set the threshold at 5 or 10 so the metric only fires for genuinely sustained failures. - **Emit on every attempt above the threshold, not only once.** Incrementing the counter on each high-attempt invocation allows alerting systems to detect both the onset and the duration of a problem by watching the counter rate. - **Use the SDK metrics scope, not a third-party library.** The SDK scope integrates with your Worker's existing metrics pipeline and adds default tags such as namespace and task queue automatically. -- **Set up rate-based alerts, not count-based.** A count alert requires resetting or remembering the baseline. A rate alert (e.g., "more than 3 increments per minute") fires when the problem is active and clears when it resolves. +- **Set up rate-based alerts, not count-based.** A count alert requires resetting or remembering the baseline. A rate alert (for example, "more than 3 increments per minute") fires when the problem is active and clears when it resolves. - **Combine with Fast/Slow Retries.** Emit the metric in the slow-phase Activity of a [Fast/Slow Retries](/design-patterns/fast-slow-retries) pattern to alert when the Workflow has been in the slow phase long enough to be a concern. ## Common pitfalls diff --git a/docs/develop/dotnet/best-practices/data-handling/data-conversion.mdx b/docs/develop/dotnet/best-practices/data-handling/data-conversion.mdx index a91d6b35c4..33f0e95aae 100644 --- a/docs/develop/dotnet/best-practices/data-handling/data-conversion.mdx +++ b/docs/develop/dotnet/best-practices/data-handling/data-conversion.mdx @@ -34,7 +34,7 @@ Temporal's Converter architecture looks like this: Data converters are used to convert raw Temporal payloads to/from actual .NET types. A custom data converter can be set via the `DataConverter` option when creating a client. Data converters are a combination of payload converters, payload codecs, and failure converters. -Payload converters convert .NET values to/from serialized bytes. Payload codecs convert bytes to bytes (e.g. for compression or encryption). Failure converters convert exceptions to/from serialized failures. +Payload converters convert .NET values to/from serialized bytes. Payload codecs convert bytes to bytes (for example, for compression or encryption). Failure converters convert exceptions to/from serialized failures. Data converters are in the `Temporalio.Converters` namespace. The default data converter uses a default payload converter, which supports the following types: diff --git a/docs/develop/dotnet/best-practices/testing-suite.mdx b/docs/develop/dotnet/best-practices/testing-suite.mdx index 2032e38e85..c439f051b9 100644 --- a/docs/develop/dotnet/best-practices/testing-suite.mdx +++ b/docs/develop/dotnet/best-practices/testing-suite.mdx @@ -287,7 +287,7 @@ If there is a non-determinism, this will throw an exception. Event history can be loaded from more than just JSON. It can be fetched individually from a Workflow handle, or even in a list. -For example, the following code will check that all Workflow histories for a certain Workflow type (i.e. workflow class) are safe with the current Workflow code. +For example, the following code will check that all Workflow histories for a certain Workflow type (that is, workflow class) are safe with the current Workflow code. ```csharp using Temporalio; diff --git a/docs/develop/dotnet/workflows/basics.mdx b/docs/develop/dotnet/workflows/basics.mdx index 4a4e005984..b669a05d31 100644 --- a/docs/develop/dotnet/workflows/basics.mdx +++ b/docs/develop/dotnet/workflows/basics.mdx @@ -81,10 +81,10 @@ This means there are several things Workflows shouldn't do such as: - Perform IO (network, disk, stdio, etc) - Access/alter external mutable state - Do any threading -- Do anything using the system clock (e.g. `DateTime.Now`) - - This includes .NET timers (e.g. `Task.Delay` or `Thread.Sleep`) +- Do anything using the system clock (for example, `DateTime.Now`) + - This includes .NET timers (for example, `Task.Delay` or `Thread.Sleep`) - Make any random calls -- Make any not-guaranteed-deterministic calls (e.g. iterating over a dictionary) +- Make any not-guaranteed-deterministic calls (for example, iterating over a dictionary) The SDK provides replay-safe alternatives for common needs. @@ -211,7 +211,7 @@ Here are the rules to disable: - [CA2007](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca2007) - This encourages users to use `ConfigureAwait` instead of directly waiting on a task. But in Workflows, there is no benefit to this and it just adds noise (and if used, needs to be `ConfigureAwait(true)` not `ConfigureAwait(false)`). - [CA2008](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca2008) - This encourages users to always apply an explicit task scheduler because the default of `TaskScheduler.Current` is bad. But for Workflows, the default of `TaskScheduler.Current` is good/required. - [CA5394](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca5394) - This discourages use of non-crypto random. But deterministic Workflows, via `Workflow.Random` intentionally provide a deterministic non-crypto random instance. -- `CS1998` - This discourages use of `async` on async methods that don't `await`. But Workflows handlers like Signals are often easier to write in one-line form this way, e.g. `public async Task SignalSomethingAsync(string value) => this.value = value;`. +- `CS1998` - This discourages use of `async` on async methods that don't `await`. But Workflows handlers like Signals are often easier to write in one-line form this way, for example `public async Task SignalSomethingAsync(string value) => this.value = value;`. - [VSTHRD105](https://github.com/microsoft/vs-threading/blob/main/doc/analyzers/VSTHRD105.md) - This is similar to `CA2008` above in that use of implicit current scheduler is discouraged. That does not apply to Workflows where it is encouraged/required. Here is the `.editorconfig` snippet for the above which may frequently change as more analyzers need to be adjusted: diff --git a/docs/develop/dotnet/workflows/cancellation.mdx b/docs/develop/dotnet/workflows/cancellation.mdx index 0bb2d03f75..8110e9b5e5 100644 --- a/docs/develop/dotnet/workflows/cancellation.mdx +++ b/docs/develop/dotnet/workflows/cancellation.mdx @@ -66,7 +66,7 @@ Workflow Definitions can be written to respond to cancellation requests. It is c Cancellation to perform cleanup. Cancellation Requests on Workflows cancel the `Workflow.CancellationToken`. This is the token that is implicitly used -for all calls within the workflow as well (e.g. Timers, Activities, etc) and therefore cancellation is propagated to +for all calls within the workflow as well (for example, Timers, Activities, etc) and therefore cancellation is propagated to them to be handled and bubble out. ```csharp diff --git a/docs/develop/dotnet/workflows/child-workflows.mdx b/docs/develop/dotnet/workflows/child-workflows.mdx index be1f25358c..5c53e2f7dc 100644 --- a/docs/develop/dotnet/workflows/child-workflows.mdx +++ b/docs/develop/dotnet/workflows/child-workflows.mdx @@ -38,7 +38,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In .NET, awaiting `StartChildWorkflowAsync()` or `ExecuteChildWorkflowAsync()` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the call resolves. diff --git a/docs/develop/environment-configuration.mdx b/docs/develop/environment-configuration.mdx index f8297723e7..239d2f98a4 100644 --- a/docs/develop/environment-configuration.mdx +++ b/docs/develop/environment-configuration.mdx @@ -99,7 +99,7 @@ Select a concept to highlight the matching connection settings in a Cloud profil { label: 'Address', description: - 'Temporal Service host and port. For Temporal Cloud, use your Namespace endpoint (for example your-namespace.account.tmprl.cloud:7233).', + 'Temporal Service host and port. For Temporal Cloud, use your Namespace endpoint (for example, your-namespace.account.tmprl.cloud:7233).', lines: [2], }, { diff --git a/docs/develop/go/integrations/google-adk.mdx b/docs/develop/go/integrations/google-adk.mdx index be6136548a..4e49fc9cd6 100644 --- a/docs/develop/go/integrations/google-adk.mdx +++ b/docs/develop/go/integrations/google-adk.mdx @@ -118,7 +118,7 @@ if err := w.Run(worker.InterruptCh()); err != nil { ``` -`Config.Models` is optional for providers ADK's registry already knows (for example `gemini-*`): when a model name is +`Config.Models` is optional for providers ADK's registry already knows (for example, `gemini-*`): when a model name is absent, `InvokeModel` falls back to `model.NewLLM`. Supply a factory to inject credentials, disable the model SDK's own retries, or override the default. diff --git a/docs/develop/go/platform/observability.mdx b/docs/develop/go/platform/observability.mdx index 07c07d1337..0a93e3f6c3 100644 --- a/docs/develop/go/platform/observability.mdx +++ b/docs/develop/go/platform/observability.mdx @@ -119,7 +119,7 @@ You can also register interceptors through a [Plugin](/develop/plugins-guide#int Each tracing interceptor uses its library's native propagation mechanism to serialize trace spans into Temporal headers. For example, OpenTelemetry uses its `TextMapPropagator` with the W3C TraceContext format. The SDK carries these headers across Workflow, Activity, and Child Workflow boundaries, so the tracing library can reconstruct the call graph. For more information, see the documentation for [OpenTelemetry](https://opentelemetry.io/), [OpenTracing](https://opentracing.io), and [Datadog](https://docs.datadoghq.com/tracing/). -To build custom context propagation (e.g., tenant IDs, auth tokens), see [Context Propagation](/develop/go/best-practices/context-propagation). +To build custom context propagation (for example, tenant IDs, auth tokens), see [Context Propagation](/develop/go/best-practices/context-propagation). ## Log from a Workflow {/* #logging */} diff --git a/docs/develop/go/workflows/child-workflows.mdx b/docs/develop/go/workflows/child-workflows.mdx index 4f139d8199..46f43fcf74 100644 --- a/docs/develop/go/workflows/child-workflows.mdx +++ b/docs/develop/go/workflows/child-workflows.mdx @@ -22,7 +22,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In Go, you must explicitly call `GetChildWorkflowExecution()` on the `ChildWorkflowFuture` and then call `Get()` on the returned Future to wait for this Event. diff --git a/docs/develop/go/workflows/message-passing.mdx b/docs/develop/go/workflows/message-passing.mdx index 4c7bdf5419..c1937dca92 100644 --- a/docs/develop/go/workflows/message-passing.mdx +++ b/docs/develop/go/workflows/message-passing.mdx @@ -349,7 +349,7 @@ You must provide a `WaitForStage` when calling `UpdateWorkflow()`. This parameter controls the stage the update must reach before returning a handle to the caller: - If `WaitForStage` is set to `WorkflowUpdateStageCompleted`, the handle is returned after the Update completes. -- If `WaitForStage` is set to `WorkflowUpdateStageAccepted`, the handle is returned after the Update is accepted (i.e. after the validator has run, if there is a validator). +- If `WaitForStage` is set to `WorkflowUpdateStageAccepted`, the handle is returned after the Update is accepted (that is, after the validator has run, if there is a validator). You can't send Updates directly from one Workflow to another. If you need to send Updates across Workflows, like to Child Workflows, use an Activity. diff --git a/docs/develop/go/workflows/selectors.mdx b/docs/develop/go/workflows/selectors.mdx index 6d73a11339..6d1218ca25 100644 --- a/docs/develop/go/workflows/selectors.mdx +++ b/docs/develop/go/workflows/selectors.mdx @@ -148,7 +148,7 @@ Merely matching on the channel doesn't consume the message; it has to be explici ## Query Selector state -You can use the `selector.HasPending` API to ensure that signals are not lost when a Workflow is closed (e.g. by `ContinueAsNew`). +You can use the `selector.HasPending` API to ensure that signals are not lost when a Workflow is closed (for example, by `ContinueAsNew`). ## Learn more diff --git a/docs/develop/java/client/temporal-client.mdx b/docs/develop/java/client/temporal-client.mdx index 801a1b90b5..881f202202 100644 --- a/docs/develop/java/client/temporal-client.mdx +++ b/docs/develop/java/client/temporal-client.mdx @@ -681,7 +681,7 @@ A Workflow Execution can be started either synchronously or asynchronously. - Asynchronous start initiates a Workflow Execution and immediately returns to the caller. This is the most common way to start Workflows in production code. The [`WorkflowClient`](https://github.com/temporalio/sdk-java/blob/main/temporal-sdk/src/main/java/io/temporal/client/WorkflowClient.java) - provides some static methods, such as `start`, `execute`, `signalWithStart` etc., that help with starting your + provides some static methods, such as `start`, `execute`, and `signalWithStart`, that help with starting your Workflows asynchronously. The following examples show how to start Workflow Executions asynchronously, with either typed or untyped diff --git a/docs/develop/java/integrations/spring-ai.mdx b/docs/develop/java/integrations/spring-ai.mdx index 672b113ee9..1da765cb60 100644 --- a/docs/develop/java/integrations/spring-ai.mdx +++ b/docs/develop/java/integrations/spring-ai.mdx @@ -254,7 +254,7 @@ public class TimestampTools { ### Plain tools -Any class with `@Tool` methods that isn't an Activity stub, Nexus stub, or `@SideEffectTool` runs directly on the Workflow thread. Use this for inherently deterministic tools (such as updating in-memory agent state), or for orchestration of durable primitives as you need, e.g. calling multiple Activities, child Workflows, wait conditions, or other Temporal durable primitives. +Any class with `@Tool` methods that isn't an Activity stub, Nexus stub, or `@SideEffectTool` runs directly on the Workflow thread. Use this for inherently deterministic tools (such as updating in-memory agent state), or for orchestration of durable primitives as you need, for example calling multiple Activities, child Workflows, wait conditions, or other Temporal durable primitives. [springai/basic/src/main/java/io/temporal/samples/springai/chat/StringTools.java](https://github.com/temporalio/samples-java/blob/main/springai/basic/src/main/java/io/temporal/samples/springai/chat/StringTools.java) diff --git a/docs/develop/java/workflows/child-workflows.mdx b/docs/develop/java/workflows/child-workflows.mdx index 747a2df3b6..af7a23ae05 100644 --- a/docs/develop/java/workflows/child-workflows.mdx +++ b/docs/develop/java/workflows/child-workflows.mdx @@ -22,7 +22,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In Java, you must explicitly call `Workflow.getWorkflowExecution(child)` to get a `Promise`, then call `.get()` on that Promise to wait for this Event. diff --git a/docs/develop/php/client/temporal-client.mdx b/docs/develop/php/client/temporal-client.mdx index 81cd46d9d1..3d0d46aca2 100644 --- a/docs/develop/php/client/temporal-client.mdx +++ b/docs/develop/php/client/temporal-client.mdx @@ -153,7 +153,7 @@ Workflow stub is a proxy generated by the [`WorkflowClient`](https://php.tempora You can use a typed or untyped Workflow stub in the client code. - Typed Workflow stubs are useful because they are type safe and allow you to invoke your Workflow methods such as `#[WorkflowMethod]`, `#[QueryMethod]`, `#[SignalMethod]`, and `#[UpdateMethod]` directly. -- An untyped Workflow stub does not use a Workflow interface. It is more flexible because it has methods from the [`WorkflowStubInterface`](https://php.temporal.io/classes/Temporal-Client-WorkflowStubInterface.html), such as `start`, `signal`, `getResults`, `query`, `signal`, `update`, `cancel`, `terminate`, etc. +- An untyped Workflow stub does not use a Workflow interface. It is more flexible because it has methods from the [`WorkflowStubInterface`](https://php.temporal.io/classes/Temporal-Client-WorkflowStubInterface.html), such as `start`, `signal`, `getResults`, `query`, `update`, `cancel`, and `terminate` When using untyped Workflow stub, we rely on the Workflow Type, Activity Type, Child Workflow Type, as well as Query and Signal names. For example, there is a Workflow defined as follows: diff --git a/docs/develop/php/workflows/basics.mdx b/docs/develop/php/workflows/basics.mdx index dd0afccff5..ff0588b962 100644 --- a/docs/develop/php/workflows/basics.mdx +++ b/docs/develop/php/workflows/basics.mdx @@ -148,7 +148,7 @@ Always do the following in the Workflow implementation code: - Don't perform any IO or service calls as they are not usually deterministic. Use Activities for this. - Only use `Workflow::now()` to get the current time inside a Workflow. - Call `yield Workflow::timer()` instead of `sleep()`. -- Do not use any blocking SPL provided by PHP (i.e. `fopen`, `PDO`, etc) in **Workflow code**. +- Do not use any blocking SPL provided by PHP (that is, `fopen`, `PDO`, etc) in **Workflow code**. - Use `yield Workflow::getVersion()` when making any changes to the Workflow code. Without this, any deployment of updated Workflow code might break already open Workflows. - Don't access configuration APIs directly from a Workflow because changes in the configuration might affect a Workflow Execution path. diff --git a/docs/develop/php/workflows/child-workflows.mdx b/docs/develop/php/workflows/child-workflows.mdx index 8548e3529c..d17cda75df 100644 --- a/docs/develop/php/workflows/child-workflows.mdx +++ b/docs/develop/php/workflows/child-workflows.mdx @@ -18,7 +18,7 @@ description: Start a Child Workflow Execution within a parent Workflow using Tem A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In PHP, yielding `$child->start()` or `Workflow::executeChildWorkflow()` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the yield resolves. diff --git a/docs/develop/python/best-practices/data-handling/data-conversion.mdx b/docs/develop/python/best-practices/data-handling/data-conversion.mdx index 9d0f665a29..52ab8a01dc 100644 --- a/docs/develop/python/best-practices/data-handling/data-conversion.mdx +++ b/docs/develop/python/best-practices/data-handling/data-conversion.mdx @@ -27,7 +27,7 @@ The default Data Converter supports converting multiple types including: - Anything that can be converted to JSON including: - Anything that [`json.dump`](https://docs.python.org/3/library/json.html#json.dump) supports natively - [dataclasses](https://docs.python.org/3/library/dataclasses.html) - - Iterables including ones JSON dump may not support by default, e.g. `set` + - Iterables including ones JSON dump may not support by default, for example `set` - [IntEnum, StrEnum](https://docs.python.org/3/library/enum.html) based enumerates - [UUID](https://docs.python.org/3/library/uuid.html) diff --git a/docs/develop/python/workflows/child-workflows.mdx b/docs/develop/python/workflows/child-workflows.mdx index cfe1816de1..734e83474d 100644 --- a/docs/develop/python/workflows/child-workflows.mdx +++ b/docs/develop/python/workflows/child-workflows.mdx @@ -28,7 +28,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In Python, awaiting `start_child_workflow()` or `execute_child_workflow()` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the call resolves. diff --git a/docs/develop/ruby/activities/basics.mdx b/docs/develop/ruby/activities/basics.mdx index 0c3d9e2d5c..18a2e63f8a 100644 --- a/docs/develop/ruby/activities/basics.mdx +++ b/docs/develop/ruby/activities/basics.mdx @@ -57,7 +57,7 @@ This section covers advanced concurrency and execution options that most users w ::: -By default, activities run in the "thread pool executor" (i.e. `Temporalio::Worker::ActivityExecutor::ThreadPool`). +By default, activities run in the "thread pool executor" (that is, `Temporalio::Worker::ActivityExecutor::ThreadPool`). This default is shared across all workers and is a naive thread pool that continually makes threads as needed when none are idle/available to handle incoming work. If a thread sits idle long enough, it will be killed. diff --git a/docs/develop/ruby/best-practices/data-handling/data-conversion.mdx b/docs/develop/ruby/best-practices/data-handling/data-conversion.mdx index fc18262a2e..652daea6de 100644 --- a/docs/develop/ruby/best-practices/data-handling/data-conversion.mdx +++ b/docs/develop/ruby/best-practices/data-handling/data-conversion.mdx @@ -34,13 +34,13 @@ Temporal's Converter architecture looks like this: Data converters are used to convert raw Temporal payloads to/from actual Ruby types. A custom data converter can be set via the `data_converter` keyword argument when creating a client. Data converters are a combination of payload converters, payload codecs, and failure converters. -Payload converters convert Ruby values to/from serialized bytes. Payload codecs convert bytes to bytes (e.g. for compression or encryption). Failure converters convert exceptions to/from serialized failures. +Payload converters convert Ruby values to/from serialized bytes. Payload codecs convert bytes to bytes (for example, for compression or encryption). Failure converters convert exceptions to/from serialized failures. Data converters are in the `Temporalio::Converters` module. The default data converter uses a default payload converter, which supports the following types: - `nil` -- "bytes" (i.e. `String` with `Encoding::ASCII_8BIT` encoding) +- "bytes" (that is, `String` with `Encoding::ASCII_8BIT` encoding) - `Google::Protobuf::MessageExts` instances - [JSON module](https://docs.ruby-lang.org/en/master/JSON.html) for everything else diff --git a/docs/develop/ruby/best-practices/testing-suite.mdx b/docs/develop/ruby/best-practices/testing-suite.mdx index 1ac7c51738..4bc6365f57 100644 --- a/docs/develop/ruby/best-practices/testing-suite.mdx +++ b/docs/develop/ruby/best-practices/testing-suite.mdx @@ -250,7 +250,7 @@ If there is a non-determinism, this will raise an exception. Event history can be loaded from more than just JSON. It can be fetched individually from a Workflow handle, or even in a list. -For example, the following code will check that all Workflow histories for a certain Workflow type (i.e. workflow class) are safe with the current Workflow code. +For example, the following code will check that all Workflow histories for a certain Workflow type (that is, workflow class) are safe with the current Workflow code. ```ruby # Create a replayer diff --git a/docs/develop/ruby/integrations/rails-integration.mdx b/docs/develop/ruby/integrations/rails-integration.mdx index 47711755b2..e1e75feb6b 100644 --- a/docs/develop/ruby/integrations/rails-integration.mdx +++ b/docs/develop/ruby/integrations/rails-integration.mdx @@ -44,7 +44,7 @@ This comes from bootsnap via zeitwerk because it is lazily loading a class/modul It is not good to lazily load code during a Workflow run because it can be side effecting. Workflows and the classes they reference should be eagerly loaded. -To resolve this, either always eagerly load (e.g. `config.eager_load = true`) or explicitly require what is used by a workflow at the top of the file. +To resolve this, either always eagerly load (for example, `config.eager_load = true`) or explicitly require what is used by a workflow at the top of the file. Note, this only affects non-production environments. diff --git a/docs/develop/ruby/workflows/basics.mdx b/docs/develop/ruby/workflows/basics.mdx index bc7253abf3..9f88875209 100644 --- a/docs/develop/ruby/workflows/basics.mdx +++ b/docs/develop/ruby/workflows/basics.mdx @@ -91,7 +91,7 @@ Ruby Workflows. This means there are several things Workflows cannot do such as: - Perform IO (network, disk, stdio, etc) - Access/alter external mutable state - Do any threading -- Do anything using the system clock (e.g. `Time.Now`) +- Do anything using the system clock (for example, `Time.Now`) - Make any random calls - Make any not-guaranteed-deterministic calls diff --git a/docs/develop/ruby/workflows/cancellation.mdx b/docs/develop/ruby/workflows/cancellation.mdx index 7fbf6bc7a3..3db3191b1e 100644 --- a/docs/develop/ruby/workflows/cancellation.mdx +++ b/docs/develop/ruby/workflows/cancellation.mdx @@ -55,7 +55,7 @@ Cancellation to perform cleanup. Cancellation Requests on Workflows cancel the `Temporalio::Workflow.cancellation` which is a `Temporalio::Cancellation` that effectively serves as a cancellation token. This is the cancellation that is implicitly used for all calls within -the workflow as well (e.g. Timers, Activities, etc) and therefore cancellation is propagated to them to be handled and +the workflow as well (for example, Timers, Activities, etc) and therefore cancellation is propagated to them to be handled and bubble out. ```ruby diff --git a/docs/develop/ruby/workflows/child-workflows.mdx b/docs/develop/ruby/workflows/child-workflows.mdx index 0064e1a5f6..00b4dc295b 100644 --- a/docs/develop/ruby/workflows/child-workflows.mdx +++ b/docs/develop/ruby/workflows/child-workflows.mdx @@ -27,7 +27,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In Ruby, calling `start_child_workflow` or `execute_child_workflow` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the call returns. diff --git a/docs/develop/rust/activities/execution.mdx b/docs/develop/rust/activities/execution.mdx index 5e10c57ea0..cbf49d41d2 100644 --- a/docs/develop/rust/activities/execution.mdx +++ b/docs/develop/rust/activities/execution.mdx @@ -95,7 +95,7 @@ Workflows can either: * `await` the result immediately (blocking progress), or * store the `Future` and await it later to allow concurrent execution. -In Rust, calling `.await` on the Activity invocation returns the result. If you need more control (e.g., parallel execution), you can create multiple Activity futures and await them selectively. +In Rust, calling `.await` on the Activity invocation returns the result. If you need more control (for example, parallel execution), you can create multiple Activity futures and await them selectively. You must provide either `schedule_to_close_timeout` or `start_to_close_timeout`. diff --git a/docs/develop/rust/workflows/child-workflows.mdx b/docs/develop/rust/workflows/child-workflows.mdx index d2e98266e8..7e1cfb8adf 100644 --- a/docs/develop/rust/workflows/child-workflows.mdx +++ b/docs/develop/rust/workflows/child-workflows.mdx @@ -22,7 +22,7 @@ This page shows how to do the following: A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc...) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In Rust, awaiting `ctx.child_workflow()` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the call resolves. diff --git a/docs/develop/task-queue-priority-fairness.mdx b/docs/develop/task-queue-priority-fairness.mdx index 1df6d72ac6..efbd8227c7 100644 --- a/docs/develop/task-queue-priority-fairness.mdx +++ b/docs/develop/task-queue-priority-fairness.mdx @@ -282,7 +282,7 @@ You can set fairness keys and weights for a Workflow within the SDK like so. Sel { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [6], }, { @@ -319,7 +319,7 @@ we, err := c.ExecuteWorkflow(context.Background(), workflowOptions, MyWorkflow) { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [5], }, { @@ -357,7 +357,7 @@ workflow.run(); { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [8], }, { @@ -395,7 +395,7 @@ await client.start_workflow( { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [7], }, { @@ -432,7 +432,7 @@ client.start_workflow( { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [5], }, { @@ -467,7 +467,7 @@ const handle = await startWorkflow(workflows.priorityWorkflow, { { label: 'Fairness key', description: - 'Groups Tasks into a virtual queue (for example by tenant or workload type) so no single group monopolizes the Task Queue.', + 'Groups Tasks into a virtual queue (for example, by tenant or workload type) so no single group monopolizes the Task Queue.', lines: [9], }, { diff --git a/docs/develop/typescript/best-practices/data-handling/data-conversion.mdx b/docs/develop/typescript/best-practices/data-handling/data-conversion.mdx index 9fa095df81..7e2c3424d6 100644 --- a/docs/develop/typescript/best-practices/data-handling/data-conversion.mdx +++ b/docs/develop/typescript/best-practices/data-handling/data-conversion.mdx @@ -123,7 +123,7 @@ You can now use a variety of data types in arguments. ## How to use a custom payload converter in TypeScript {/* #custom-payload-conversion */} To support custom Payload conversion, create a [custom Payload Converter](/payload-converter#composite-data-converters) and configure the Data Converter to use it in your Client options. -You can use Custom Payload Converters to change how application objects get serialized to binary Payload. To handle custom data types that are not natively JSON-serializable (e.g., `BigInt`, `Date`, or binary data), you can create a custom Payload Converter. A Custom Payload Converter is responsible for converting your custom data types to a payload format that Temporal can manage. +You can use Custom Payload Converters to change how application objects get serialized to binary Payload. To handle custom data types that are not natively JSON-serializable (for example, `BigInt`, `Date`, or binary data), you can create a custom Payload Converter. A Custom Payload Converter is responsible for converting your custom data types to a payload format that Temporal can manage. To implement a Custom Payload Converter in TypeScript, you need to do the following steps: diff --git a/docs/develop/typescript/nexus/feature-guide.mdx b/docs/develop/typescript/nexus/feature-guide.mdx index b171eb82d2..1a31c47382 100644 --- a/docs/develop/typescript/nexus/feature-guide.mdx +++ b/docs/develop/typescript/nexus/feature-guide.mdx @@ -498,7 +498,7 @@ The plugin creates the following spans: See the [interceptors-opentelemetry sample](https://github.com/temporalio/samples-typescript/tree/main/interceptors-opentelemetry) for a complete example. -For custom interceptor logic beyond tracing (e.g., logging, authorization), see [Nexus interceptor registration](/develop/typescript/workers/interceptors#nexus-interceptor-registration). +For custom interceptor logic beyond tracing (for example, logging, authorization), see [Nexus interceptor registration](/develop/typescript/workers/interceptors#nexus-interceptor-registration). ## Learn more diff --git a/docs/develop/typescript/platform/observability.mdx b/docs/develop/typescript/platform/observability.mdx index df7aef590b..687b9552b6 100644 --- a/docs/develop/typescript/platform/observability.mdx +++ b/docs/develop/typescript/platform/observability.mdx @@ -186,7 +186,7 @@ A Temporal Worker may emit logs in various ways, including: - Messages emitted by the underlying Temporal Core SDK (native code). All of these messages are internally routed to a single logger object, called the Runtime's Logger. -By default, the Runtime's Logger simply writes messages to the console (i.e. the process's `STDOUT`). +By default, the Runtime's Logger simply writes messages to the console (that is, the process's `STDOUT`). #### How to customize the Runtime's Logger diff --git a/docs/develop/typescript/workflows/child-workflows.mdx b/docs/develop/typescript/workflows/child-workflows.mdx index 2b40eab07b..934e096158 100644 --- a/docs/develop/typescript/workflows/child-workflows.mdx +++ b/docs/develop/typescript/workflows/child-workflows.mdx @@ -18,7 +18,7 @@ description: Start and manage Child Workflow Executions using Temporal's Child W A [Child Workflow Execution](/child-workflows) is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API. -When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted), etc.) are logged in the Workflow Execution Event History. +When using a Child Workflow API, Child Workflow related Events ([StartChildWorkflowExecutionInitiated](/references/events#startchildworkflowexecutioninitiated), [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted), [ChildWorkflowExecutionCompleted](/references/events#childworkflowexecutioncompleted)) are logged in the Workflow Execution Event History. The [ChildWorkflowExecutionStarted](/references/events#childworkflowexecutionstarted) Event must be logged to the Event History before the Parent Workflow completes to ensure the Child Workflow has started. In TypeScript, awaiting `startChild()` or `executeChild()` internally waits for this Event before returning, so the Child Workflow is guaranteed to have started once the call resolves. diff --git a/docs/develop/worker-tuning-reference.mdx b/docs/develop/worker-tuning-reference.mdx index 27c8892245..508b317d1f 100644 --- a/docs/develop/worker-tuning-reference.mdx +++ b/docs/develop/worker-tuning-reference.mdx @@ -98,7 +98,7 @@ Memory settings control the Workflow cache size and thread pool allocation. |-----|----------------------------------------------| | **Go** | 10,000 | | **Java** | 600 | -| **TypeScript** | Dynamic (e.g., 2000 for 4 GiB RAM) | +| **TypeScript** | Dynamic (for example, 2000 for 4 GiB RAM) | | **Python** | 1,000 | | **.NET** | 10,000 | diff --git a/docs/encyclopedia/architecture/temporal-sdks.mdx b/docs/encyclopedia/architecture/temporal-sdks.mdx index 16417383fe..de93a07a67 100644 --- a/docs/encyclopedia/architecture/temporal-sdks.mdx +++ b/docs/encyclopedia/architecture/temporal-sdks.mdx @@ -226,7 +226,7 @@ Starting a Workflow Execution creates a new Event, WorkflowExecutionStarted, and The Temporal Service then schedules a Workflow Task by adding it to the Task Queue. When the Worker has capacity, it picks up this Task, and begin executing code. -Each step of the Task (e.g. Scheduled, Started, and Completed), gets recorded into the Event History. +Each step of the Task (for example, Scheduled, Started, and Completed), gets recorded into the Event History. - Scheduled means that the Temporal Service has added a Task to the Task Queue. - Started means that the Worker has dequeued the Task. diff --git a/docs/encyclopedia/context-propagation.mdx b/docs/encyclopedia/context-propagation.mdx index efae923744..a04de0d02b 100644 --- a/docs/encyclopedia/context-propagation.mdx +++ b/docs/encyclopedia/context-propagation.mdx @@ -19,7 +19,7 @@ Context propagation lets you pass custom key-value data from a Client to Workflo Common use cases: -- Propagating distributed tracing IDs (e.g., OpenTelemetry trace context) +- Propagating distributed tracing IDs (for example, OpenTelemetry trace context) - Passing tenant IDs for multi-tenant applications - Forwarding auth tokens or request-scoped metadata diff --git a/docs/encyclopedia/detecting-activity-failures.mdx b/docs/encyclopedia/detecting-activity-failures.mdx index 891c4a28a8..ae764bc75e 100644 --- a/docs/encyclopedia/detecting-activity-failures.mdx +++ b/docs/encyclopedia/detecting-activity-failures.mdx @@ -195,7 +195,7 @@ Activity Heartbeats work in conjunction with a [Heartbeat Timeout](#heartbeat-ti Activity Heartbeats are implemented within the Activity Definition. Custom progress information can be included in the Heartbeat which can then be used by the Activity Execution should a retry occur. -An Activity Heartbeat can be recorded as often as needed (e.g. once a minute or every loop iteration). +An Activity Heartbeat can be recorded as often as needed (for example, once a minute or every loop iteration). It is often a good practice to Heartbeat on anything but the shortest Activity Execution. Temporal SDKs control the rate at which Heartbeats are sent to the Temporal Service. diff --git a/docs/encyclopedia/plugins.mdx b/docs/encyclopedia/plugins.mdx index 0dade76bba..57fb027e60 100644 --- a/docs/encyclopedia/plugins.mdx +++ b/docs/encyclopedia/plugins.mdx @@ -16,7 +16,7 @@ A Plugin bundles multiple extensibility primitives - interceptors, context propa Common use cases: -- AI Agent SDKs (e.g., OpenAI Agents, Pydantic AI, LangGraph) +- AI Agent SDKs (for example, OpenAI Agents, Pydantic AI, LangGraph) - Observability packages (tracing, logging, metrics) - Encryption or compliance middleware - Shared infrastructure integrations (messaging, payments, LLM calls) diff --git a/docs/encyclopedia/temporal-service/multi-cluster-replication.mdx b/docs/encyclopedia/temporal-service/multi-cluster-replication.mdx index 06ccc883d0..d172ce6d50 100644 --- a/docs/encyclopedia/temporal-service/multi-cluster-replication.mdx +++ b/docs/encyclopedia/temporal-service/multi-cluster-replication.mdx @@ -66,9 +66,9 @@ When there is a data conflict, a comparison will be made and Workflow Execution When a cluster is trying to mutate a Workflow Execution History, the version will be checked. A cluster can mutate a Workflow Execution History only if the following is true: -- The version in the Namespace belongs to this cluster, i.e. +- The version in the Namespace belongs to this cluster, that is `(version in namespace) % (shared version increment) == (this cluster's initial version)` -- The version of this Workflow Execution History's last entry (event) is equal or less than the version in the Namespace, i.e. +- The version of this Workflow Execution History's last entry (event) is equal or less than the version in the Namespace, that is `(last event's version) <= (version in namespace)`
diff --git a/docs/encyclopedia/workers/task-queues.mdx b/docs/encyclopedia/workers/task-queues.mdx index 2853ab9d76..ab159b62e4 100644 --- a/docs/encyclopedia/workers/task-queues.mdx +++ b/docs/encyclopedia/workers/task-queues.mdx @@ -148,7 +148,7 @@ Task Queues with a single partition are almost always first-in, first-out, with However, using a single partition limits you to low- and medium-throughput use cases. In Task Queues with multiple partitions, each task is assigned to a random partition. -Generally partitions will act as FIFO queues, so once a task queue builds up a backlog, the sync match (tasks that can be dispatched immediately) rate will drop to nearly zero because the task queue will instead dispatch tasks from the backlog (i.e. async matches) first. +Generally partitions will act as FIFO queues, so once a task queue builds up a backlog, the sync match (tasks that can be dispatched immediately) rate will drop to nearly zero because the task queue will instead dispatch tasks from the backlog (that is, async matches) first. :::note diff --git a/docs/encyclopedia/workers/worker-versioning.mdx b/docs/encyclopedia/workers/worker-versioning.mdx index 59951818b5..a055a461b4 100644 --- a/docs/encyclopedia/workers/worker-versioning.mdx +++ b/docs/encyclopedia/workers/worker-versioning.mdx @@ -51,7 +51,7 @@ A **Pinned** Workflow is guaranteed to complete on a single Worker Deployment Ve ### Auto-Upgrade Workflows {/* #auto-upgrade */} -An **Auto-Upgrade** Workflow will move to the latest Worker Deployment Version automatically whenever you change the current version. Auto-upgrade Workflows are not restricted to a single Deployment Version and need to be kept replay-safe manually, i.e. with [patching](/workflow-definition#workflow-versioning). +An **Auto-Upgrade** Workflow will move to the latest Worker Deployment Version automatically whenever you change the current version. Auto-upgrade Workflows are not restricted to a single Deployment Version and need to be kept replay-safe manually, that is with [patching](/workflow-definition#workflow-versioning). ### Activity behavior across versions @@ -89,7 +89,7 @@ A Worker Deployment Version moves through the following states: ## Continue-as-new, Child Workflow, and Retry Semantics {/* #inheritance-semantics */} -When Workflows start new runs (e.g. by continuing-as-new or retrying) the new run may inherit their versioning behavior. This section explains how inheritance works across different Workflow execution patterns. +When Workflows start new runs (for example, by continuing-as-new or retrying) the new run may inherit their versioning behavior. This section explains how inheritance works across different Workflow execution patterns. ### Ways Workflows Start New Runs @@ -140,7 +140,7 @@ This section provides more detail on specific inheritance scenarios. **Inheritance Conditions (all must be met):** - The retried run is effectively pinned at the time of retry -- The retried run inherited a pinned version when it started (i.e., it is a child of a pinned parent, or a Continue-As-New of a pinned run) +- The retried run inherited a pinned version when it started (that is, it is a child of a pinned parent, or a Continue-As-New of a pinned run) - The retried run is running on a Task Queue in the inherited version **When Conditions Not Met:** diff --git a/docs/encyclopedia/workflow-message-passing/handling-messages.mdx b/docs/encyclopedia/workflow-message-passing/handling-messages.mdx index cd4478402d..82283a50c6 100644 --- a/docs/encyclopedia/workflow-message-passing/handling-messages.mdx +++ b/docs/encyclopedia/workflow-message-passing/handling-messages.mdx @@ -74,7 +74,7 @@ In Go and TypeScript, register any message handlers only after completing initia ### Message handler patterns {/* #message-handler-patterns */} -Here are several common patterns for write operations, Signal and Update handlers. They don't apply to pure read operations, i.e. Queries or [Update Validators](/handling-messages#update-validators): +Here are several common patterns for write operations, Signal and Update handlers. They don't apply to pure read operations, that is Queries or [Update Validators](/handling-messages#update-validators): - Returning immediately from a handler - Waiting for the Workflow to be ready to process them diff --git a/docs/encyclopedia/workflow/workflow-overview.mdx b/docs/encyclopedia/workflow/workflow-overview.mdx index 82c56c3e8b..8dc4f5a0ff 100644 --- a/docs/encyclopedia/workflow/workflow-overview.mdx +++ b/docs/encyclopedia/workflow/workflow-overview.mdx @@ -48,7 +48,7 @@ In day-to-day conversations, the term Workflow might refer to Workflow Type, a W 1. A **Workflow Definition** is the code that defines your Workflow. 2. The **Workflow Type** is the name that maps to a Workflow Definition. It's an identifier that makes it possible to distinguish one type of Workflow (such as order processing) from another (such as customer onboarding). -3. A **Workflow Execution** is a running Workflow, which is created by combining a Workflow Definition with a request to execute it. You can execute a Workflow Definition any number of times, potentially providing different input each time (i.e., a Workflow Definition for order processing might process order #123 in one execution and order #567 in another execution). It is the actual instance of the Workflow Definition running in the Temporal Platform. +3. A **Workflow Execution** is a running Workflow, which is created by combining a Workflow Definition with a request to execute it. You can execute a Workflow Definition any number of times, potentially providing different input each time (that is, a Workflow Definition for order processing might process order #123 in one execution and order #567 in another execution). It is the actual instance of the Workflow Definition running in the Temporal Platform. You'll develop those Workflows by writing code in a general-purpose programming language such as Go, Java, TypeScript, or Python. The code you write is the same code that will be executed at runtime, so you can use your favorite tools and libraries to develop Temporal Workflows. diff --git a/docs/evaluate/development-production-features/core-application.mdx b/docs/evaluate/development-production-features/core-application.mdx index 3d39636ab4..ecbf353a7c 100644 --- a/docs/evaluate/development-production-features/core-application.mdx +++ b/docs/evaluate/development-production-features/core-application.mdx @@ -34,7 +34,7 @@ import { RelatedReadContainer, RelatedReadItem } from '@site/src/components'; You write it in your programming language of choice using the Temporal SDK. Conceptually, a Workflow specifies a sequence of steps and orchestrates the execution of Activities. -**Activities**: An Activity is a method or function that encapsulates business logic prone to failure (e.g., calling a service that may go down). +**Activities**: An Activity is a method or function that encapsulates business logic prone to failure (for example, calling a service that may go down). The system can automatically retry these Activities upon some failures. Activities perform a single, well-defined action, such as calling another service, transcoding a media file, or sending an email message. diff --git a/docs/evaluate/temporal-cloud/limits.mdx b/docs/evaluate/temporal-cloud/limits.mdx index 1f024487c3..f2aebe57df 100644 --- a/docs/evaluate/temporal-cloud/limits.mdx +++ b/docs/evaluate/temporal-cloud/limits.mdx @@ -135,7 +135,7 @@ When you exceed your APS, RPS, or OPS limits, Temporal Cloud throttles requests. - Default limit: 10 schedule requests per second (RPS) - How to increase: [Contact support](/cloud/support#support-ticket) -To avoid throttling, don't schedule all your Workflow Executions to start at the same time (daily, weekly, monthly, etc.). +To avoid throttling, don't schedule all your Workflow Executions to start at the same time (such as daily, weekly, or monthly). Every Temporal SDK supports jittering, which adds small random delays to Schedule specifications, helping to reduce load at any specific moment. Set the `jitter` value to the largest delay you will permit before your Workflow Execution must begin. This approach uniformly distributes the scheduled Workflow Execution launches through that period and reduces your Schedule Workflow Execution RPS load. @@ -240,8 +240,8 @@ The UI can display up to 100 Custom Roles. A single principal (such as a user) can be assigned up to 10 Custom Roles. A Custom Role can contain up 20 permissions. Each permission is a pair of -- A list of resource IDs of a single type (e.g., specific Namespace IDs) -- A list of actions that apply to those resources (e.g., cloud.namespace.get, cloud.namespace.update) +- A list of resource IDs of a single type (for example, specific Namespace IDs) +- A list of actions that apply to those resources (for example, cloud.namespace.get, cloud.namespace.update) For example, - 1 permission: Namespaces [ns-prod, ns-staging] with actions [cloud.namespace.get, cloud.namespace.update] - 2 permissions: Namespace [ns-prod] with action [cloud.namespace.get]; Namespace [ns-staging] with action [cloud.namespace.update] defined separately. diff --git a/docs/evaluate/temporal-cloud/pricing.mdx b/docs/evaluate/temporal-cloud/pricing.mdx index 7e82bf5e93..8f22131910 100644 --- a/docs/evaluate/temporal-cloud/pricing.mdx +++ b/docs/evaluate/temporal-cloud/pricing.mdx @@ -280,7 +280,7 @@ This can be calculated as 500 APS Per TRU * 3600 Seconds (1 Hour) * 20%= 360,000 For example: -If you have a namespace that requests 4 TRUs (ie 2,000 APS) for 4 hours and have usage as follows: +If you have a namespace that requests 4 TRUs (that is, 2,000 APS) for 4 hours and have usage as follows: * Hour 1: 2,000,000 Actions * Hour 2: 5,000,000 Actions * Hour 3: 4,000,000 Actions diff --git a/docs/evaluate/temporal-cloud/support.mdx b/docs/evaluate/temporal-cloud/support.mdx index 01cfb4feff..7815ce6ed6 100644 --- a/docs/evaluate/temporal-cloud/support.mdx +++ b/docs/evaluate/temporal-cloud/support.mdx @@ -115,7 +115,7 @@ All Cloud customers pay for support as part of their plan. ### Access Temporal Support 1. Go to [support.temporal.io](https://support.temporal.io/). -2. If prompted, log in to Temporal Cloud using the same method you normally use (e.g., Google, Microsoft, email-password, or other methods). +2. If prompted, log in to Temporal Cloud using the same method you normally use (for example, Google, Microsoft, email-password, or other methods). 3. You will be presented with a screen where you can view open and closed tickets for your Temporal account, as well as submit a new ticket. To request assistance from Temporal Support, see [Create a ticket](#support-ticket). @@ -132,7 +132,7 @@ If you need assistance and don't have paid support, post your request in the [Te To create a ticket in the Temporal Support Portal: 1. Go to [support.temporal.io](https://support.temporal.io/). -2. If prompted, log in to Temporal Cloud using the same method you normally use (e.g., Google, Microsoft, email-password, or other methods). +2. If prompted, log in to Temporal Cloud using the same method you normally use (for example, Google, Microsoft, email-password, or other methods). 3. Click the **Create Ticket** button in the top right corner. 4. On the **Submit a ticket** page, enter the details of your request into the form. **Name**, **Subject**, and **Description** are required. 5. At the bottom of the form, choose **Submit**. diff --git a/docs/guides/entity-pattern-loyalty-points.mdx b/docs/guides/entity-pattern-loyalty-points.mdx index 3e6c2b9eca..1fb7bde2bb 100644 --- a/docs/guides/entity-pattern-loyalty-points.mdx +++ b/docs/guides/entity-pattern-loyalty-points.mdx @@ -257,7 +257,7 @@ class RedemptionResult: reward: str ``` -`LoyaltyState` holds only what's needed to reconstruct the entity after a Continue-As-New transition. `processed_event_ids` enables idempotent Signal processing — in production, limit this to a recent window (e.g. last 1,000 IDs) and rely on an external store for long-term deduplication. `pending_events` carries any Signals that arrived but weren't processed before the transition. +`LoyaltyState` holds only what's needed to reconstruct the entity after a Continue-As-New transition. `processed_event_ids` enables idempotent Signal processing — in production, limit this to a recent window (for example, last 1,000 IDs) and rely on an external store for long-term deduplication. `pending_events` carries any Signals that arrived but weren't processed before the transition. ### Phase 2: Implement the Activities diff --git a/docs/guides/rate-limit-downstream-apis.mdx b/docs/guides/rate-limit-downstream-apis.mdx index 4cd08b1511..4f19f3e17a 100644 --- a/docs/guides/rate-limit-downstream-apis.mdx +++ b/docs/guides/rate-limit-downstream-apis.mdx @@ -63,7 +63,7 @@ The Python SDK provides three rate limiting controls: 2. **max_activities_per_second** (per-worker): Limits Activities per Worker. Can be combined with global limit for finer control. -3. **max_concurrent_activities** (concurrency): Limits concurrent executions. Use when API has concurrent connection limits (e.g., database pool size). +3. **max_concurrent_activities** (concurrency): Limits concurrent executions. Use when API has concurrent connection limits (for example, database pool size). 4. **disable_eager_activity_execution** (Client configuration): Set to `True` when starting Workflows to prevent Activities from being eagerly assigned to the Workflow Worker, ensuring they go through the rate-limited Task Queue instead. @@ -153,7 +153,7 @@ When activities are stuck at their maximum retry intervals: temporal activity reset --workflow-id --activity-id ``` -This is useful when downstream APIs recover from outages and you want to immediately retry activities that are waiting at long backoff intervals (e.g., 10 minutes). +This is useful when downstream APIs recover from outages and you want to immediately retry activities that are waiting at long backoff intervals (for example, 10 minutes). ## Target audience @@ -757,7 +757,7 @@ if __name__ == "__main__": By implementing rate-limited separate Task Queues for external APIs, you have achieved: -1. **Rate limit compliance:** Activities respect API rate limits (e.g., SendGrid 1.5/sec, OpenAI 0.9/sec), eliminating 429 errors and preventing account suspension +1. **Rate limit compliance:** Activities respect API rate limits (for example, SendGrid 1.5/sec, OpenAI 0.9/sec), eliminating 429 errors and preventing account suspension 2. **Improved reliability:** Workflows complete successfully without rate limit failures. Global rate limiting ensures that adding more Workers doesn't violate API limits. diff --git a/docs/guides/worker-execution-affinity.mdx b/docs/guides/worker-execution-affinity.mdx index 4cc6b462b0..0dadd755d0 100644 --- a/docs/guides/worker-execution-affinity.mdx +++ b/docs/guides/worker-execution-affinity.mdx @@ -49,14 +49,14 @@ Use Worker-specific Task Queues to ensure all Activities in a Workflow execute o ### Task Queue fundamentals -Task Queues in Temporal are dynamically created when first referenced. With this pattern a unique Task Queue is created per Worker instance (e.g., `file-processing-abc123`) that only that Worker polls. +Task Queues in Temporal are dynamically created when first referenced. With this pattern a unique Task Queue is created per Worker instance (for example, `file-processing-abc123`) that only that Worker polls. **Recommended practice:** Generate unique queue names using UUIDs (or the hostname if running in a containerized environment) to avoid collisions across Worker instances. ### Worker-specific vs Worker sessions - **Go SDK** has a built-in [Worker Sessions API](/develop/go/workers/sessions) that handles Worker-specific routing automatically -- **Other SDKs** (Python, TypeScript, etc.) must implement the pattern manually using unique Task Queue names +- **Other SDKs** (such as Python and TypeScript) must implement the pattern manually using unique Task Queue names This pattern provides the same guarantees as Go's Sessions API for non-Go SDKs. @@ -67,9 +67,9 @@ If a Worker crashes while processing Activities on its unique queue: - Retries and pending activities will wait in the unique queue until `schedule_to_start_timeout` expires - To recover, the Workflow catches the timeout error and can route to a different Worker (on a new unique task queue) -**Recommended practice:** Set a short `heartbeat_timeout` (e.g., 30s) to detect crashes quickly, and a short `schedule_to_start_timeout` (e.g., 1m) to stop waiting on dead queues. +**Recommended practice:** Set a short `heartbeat_timeout` (for example, 30s) to detect crashes quickly, and a short `schedule_to_start_timeout` (for example, 1m) to stop waiting on dead queues. -**Recommended practice:** Set appropriate `schedule_to_start_timeout` values to detect Worker failures quickly (e.g., 5 minutes for file processing). +**Recommended practice:** Set appropriate `schedule_to_start_timeout` values to detect Worker failures quickly (for example, 5 minutes for file processing). > Activity Executions in most Workflows are constrained by the Start-to-Close Timeout, which limits the maximum duration of a single attempt. Its value is set to slightly longer than the Activity should take to complete. The pattern described here also relies on the Schedule-to-Start Timeout, which limits the maximum amount of time that a Task may remain enqueued. Although otherwise seldom used, this Timeout is valuable here because it enables the system to detect a Worker crash. That is, when a Worker crashes, it will no longer dequeue Tasks and the Schedule-to-Start Timeout will be reached. @@ -366,7 +366,7 @@ if __name__ == "__main__": ``` **Deployment guidance:** -- Deploy multiple instances of this Worker (e.g., 5-10 instances) +- Deploy multiple instances of this Worker (for example, 5-10 instances) - Each instance generates its own unique queue UUID - Workers should have adequate disk space for file processing - Consider using local SSD storage for better I/O performance @@ -377,9 +377,9 @@ When a Worker crashes, Activities scheduled to its unique queue will wait. Imple **Failure Detection Mechanisms:** -1. **Heartbeat Timeout** (fastest): Activities periodically send heartbeats to signal they're alive. If a Worker crashes mid-execution, no Heartbeats are sent, and the Activity fails within seconds (e.g., 30s) rather than waiting for the full Task duration. +1. **Heartbeat Timeout** (fastest): Activities periodically send heartbeats to signal they're alive. If a Worker crashes mid-execution, no Heartbeats are sent, and the Activity fails within seconds (for example, 30s) rather than waiting for the full Task duration. -2. **Schedule-to-Start Timeout** (medium): If a Worker crashes before picking up a Task from its queue, this timeout detects it within minutes (e.g., 5 min) instead of waiting for the full Start-To-Close Timeout. This is critical for identifying dead Workers early. +2. **Schedule-to-Start Timeout** (medium): If a Worker crashes before picking up a Task from its queue, this timeout detects it within minutes (for example, 5 min) instead of waiting for the full Start-To-Close Timeout. This is critical for identifying dead Workers early. 3. **Workflow-Level Retries** (recovery): The `for` loop catches all exceptions and retries the entire Workflow sequence on a different Worker. This provides recovery after detecting a Worker failure—the Workflow doesn't retry on the failed Worker's queue, but instead requests a new unique queue from a healthy Worker. @@ -472,7 +472,7 @@ By implementing Worker-specific Task Queues for file processing, you have achiev 1. **Data locality:** Files downloaded in one Activity are immediately available to subsequent Activities on the same Worker, eliminating multi-GB network transfers -2. **Performance improvement:** Reduced execution time by 80%+ for Workflows processing large files (e.g., 10GB video file no longer transferred between Workers) +2. **Performance improvement:** Reduced execution time by 80%+ for Workflows processing large files (for example, 10GB video file no longer transferred between Workers) 3. **Resource efficiency:** Load expensive resources (ML models, database connections) once per Workflow instead of per Activity, reducing memory usage and initialization overhead diff --git a/docs/production-deployment/multi-tenant-patterns.mdx b/docs/production-deployment/multi-tenant-patterns.mdx index 0a60c886ee..08a044f18b 100644 --- a/docs/production-deployment/multi-tenant-patterns.mdx +++ b/docs/production-deployment/multi-tenant-patterns.mdx @@ -155,7 +155,7 @@ This section details the recommended pattern for most multi-tenant applications. When a [Worker](/workers) starts up: 1. **Load tenant configuration** - Retrieve the list of tenants this Worker should handle (from config file, API, or database) -2. **Create [Task Queues](/task-queue)** - For each tenant, generate a unique Task Queue name (e.g., `customer-{tenant-id}`) +2. **Create [Task Queues](/task-queue)** - For each tenant, generate a unique Task Queue name (for example, `customer-{tenant-id}`) 3. **Register [Workflows](/workflows) and [Activities](/activities)** - Register your Workflow and Activity implementations once, passing the tenant-specific Task Queue name 4. **Poll multiple Task Queues** - A single Worker process polls all assigned tenant Task Queues diff --git a/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx b/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx index 5d2a942e02..e74fc88f27 100644 --- a/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx +++ b/docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx @@ -53,9 +53,9 @@ When there is a data conflict, a comparison will be made and Workflow Execution When a cluster is trying to mutate a Workflow Execution History, the version will be checked. A cluster can mutate a Workflow Execution History only if the following is true: -- The version in the Namespace belongs to this cluster, i.e. +- The version in the Namespace belongs to this cluster, that is `(version in namespace) % (shared version increment) == (this cluster's initial version)` -- The version of this Workflow Execution History's last entry (event) is equal or less than the version in the Namespace, i.e. +- The version of this Workflow Execution History's last entry (event) is equal or less than the version in the Namespace, that is `(last event's version) <= (version in namespace)`
diff --git a/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx b/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx index 4992d29e9b..b50ffd8efe 100644 --- a/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx +++ b/docs/production-deployment/self-hosted-guide/temporal-nexus.mdx @@ -64,7 +64,7 @@ To enable Nexus in your deployment: # For production, restrict allowed hosts and set AllowInsecure to false # whenever HTTPS/TLS is supported. Allowing HTTP increases MITM and data exposure risk. - value: - - Pattern: "*" # Update to restrict allowed callers, e.g. "*.example.com" + - Pattern: "*" # Update to restrict allowed callers, for example "*.example.com" AllowInsecure: true # In production, set to false and ensure traffic is HTTPS/TLS encrypted ``` diff --git a/docs/production-deployment/temporal-proxy/configure.mdx b/docs/production-deployment/temporal-proxy/configure.mdx index 6c9e4c1043..d187d355a5 100644 --- a/docs/production-deployment/temporal-proxy/configure.mdx +++ b/docs/production-deployment/temporal-proxy/configure.mdx @@ -25,7 +25,7 @@ import { ReleaseNoteHeader } from '@site/src/components'; The proxy reads a single YAML file. Three sections are the core of it: the gateway listener (`hostPort`), `routing`, and the `upstreams` it forwards to. The optional `tls`, `auth`, `encryption`, and `extensionServers` sections add inbound TLS, inbound authentication, and payload encryption. Values support `${VAR}` and `$VAR` environment variable expansion, -and an upstream's `hostPort` can be a template that resolves per request (for example `{{ .RemoteNamespace }}`). +and an upstream's `hostPort` can be a template that resolves per request (for example, `{{ .RemoteNamespace }}`). The example below is the proxy's [Temporal Cloud example](https://github.com/temporalio/temporal-proxy/tree/main/examples/cloud), which connects a Worker diff --git a/docs/production-deployment/temporal-proxy/encrypt-payloads.mdx b/docs/production-deployment/temporal-proxy/encrypt-payloads.mdx index e5e09c8db9..fa3051e7bb 100644 --- a/docs/production-deployment/temporal-proxy/encrypt-payloads.mdx +++ b/docs/production-deployment/temporal-proxy/encrypt-payloads.mdx @@ -129,7 +129,7 @@ from every region. How you express that differs by provider: - **Azure:** Key Vault keys are regional. Use a separate vault per region (or geo-replication), and, because each vault gives the key a distinct URI, set each proxy's `uri` to its local vault and list the other vaults' keys in `decryptURIs`. -- **GCP:** create the key in a multi-region location (for example `locations/us`) or in `global`. The resource name is +- **GCP:** create the key in a multi-region location (for example, `locations/us`) or in `global`. The resource name is the same everywhere, so every proxy uses the identical `uri` and no `decryptURIs` are needed: `gcpkms://projects/my-project/locations/us/keyRings/codec/cryptoKeys/my-key`. diff --git a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx index ea95ab3b64..960ee1c7c6 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx @@ -474,7 +474,7 @@ The following parameters apply to all SDKs: | `--zip-file` | Path to your packaged deployment zip. | | `--timeout` | Invocation deadline in seconds. This is the maximum time each Lambda invocation can run before AWS terminates it. Set this high enough for the Worker to start, process Tasks, and [shut down gracefully](/serverless-workers#worker-lifecycle). | | `--memory-size` | Memory in MB allocated to each invocation. | -| `TEMPORAL_ADDRESS` | Temporal frontend address (e.g., `..tmprl.cloud:7233`). | +| `TEMPORAL_ADDRESS` | Temporal frontend address (for example, `..tmprl.cloud:7233`). | | `TEMPORAL_NAMESPACE` | Temporal Namespace. | | `TEMPORAL_TASK_QUEUE` | Task Queue name. The Worker package reads it at startup, before the configure callback runs, so a Task Queue set in the callback takes precedence. Set one or the other, or the Worker fails to start. | | `TEMPORAL_TLS_CLIENT_CERT_PATH` | Path to the TLS client certificate file for mTLS authentication. | diff --git a/docs/production-deployment/worker-deployments/worker-versioning/index.mdx b/docs/production-deployment/worker-deployments/worker-versioning/index.mdx index 01288f3b8d..03548a7804 100644 --- a/docs/production-deployment/worker-deployments/worker-versioning/index.mdx +++ b/docs/production-deployment/worker-deployments/worker-versioning/index.mdx @@ -86,7 +86,7 @@ To get started with Worker Versioning, you should understand some concepts aroun - A **Pinned** Workflow is guaranteed to complete on a single Worker Deployment Version. - An **Auto-Upgrade** Workflow will automatically move to a new code version as you roll it out, specifically its Target Worker Deployment Version (defined below). Therefore, Auto-Upgrade Workflows are not restricted to a single - Deployment Version and need to be kept replay-safe manually, i.e. with + Deployment Version and need to be kept replay-safe manually, that is with [patching](/workflow-definition#workflow-versioning). - Both Pinned and Auto-Upgrade Workflows are guaranteed to start only on the Current or Ramping Version of their Worker Deployment. diff --git a/docs/production-deployment/worker-deployments/worker-versioning/sunset-and-gc.mdx b/docs/production-deployment/worker-deployments/worker-versioning/sunset-and-gc.mdx index 5d29ca5d5d..a472eb41c5 100644 --- a/docs/production-deployment/worker-deployments/worker-versioning/sunset-and-gc.mdx +++ b/docs/production-deployment/worker-deployments/worker-versioning/sunset-and-gc.mdx @@ -168,7 +168,7 @@ which is currently set to 100 in Temporal Cloud, but that's a conservative numbe For example, when you deploy your 101st Worker Version in a Worker Deployment, the server looks at the oldest drained version in the Worker deployment. If it has had no pollers in the last 5 minutes, the server deletes it. If that version still has pollers, the server will try the next oldest version. If none of the 100 versions are eligible for deletion -(ie. none of them are drained with no pollers), then no version will be deleted and the poll from the 101st version +(that is, none of them are drained with no pollers), then no version will be deleted and the poll from the 101st version would fail. At that point, to successfully deploy your 101st version, you would need to increase `matching.maxVersionsInDeployment` diff --git a/docs/references/configuration.mdx b/docs/references/configuration.mdx index 7ac1a12214..55e5c187ba 100644 --- a/docs/references/configuration.mdx +++ b/docs/references/configuration.mdx @@ -253,7 +253,7 @@ Configures the source of signing keys used by the default `ClaimMapper` to verif - `keySourceURIs` - _list of strings_. URLs to fetch JWKS-formatted public keys from. The default `ClaimMapper` fetches and caches the union of keys returned by each URI. -- `refreshInterval` - _Go duration string_ (for example `1m`, `5m`) - _Default:_ `0`. +- `refreshInterval` - _Go duration string_ (for example, `1m`, `5m`) - _Default:_ `0`. How often the key set is refetched. Zero (the default) disables periodic refresh, so keys are loaded once at startup and never rotated. #### remoteClusterAuth @@ -348,7 +348,7 @@ Data store definitions must be either `cassandra` or `sql`. A `cassandra` data store definition can contain the following values: -- `hosts`: _Required_ - "," separated Cassandra endpoints, e.g. "192.168.1.2,192.168.1.3,192.168.1.4". +- `hosts`: _Required_ - "," separated Cassandra endpoints, for example "192.168.1.2,192.168.1.3,192.168.1.4". - `port`: Default: 9042 - Cassandra port used for connection by `gocql` client. - `user`: Cassandra username used for authentication by `gocql` client. - `password`: Cassandra password used for authentication by `gocql` client. @@ -366,7 +366,7 @@ A `sql` data store definition can contain the following values: - `pluginName`: _Required_ - SQL database type. - _Valid values_: `mysql` or `postgres`. - `databaseName` - _required_ - the name of SQL database to connect to. -- `connectAddr` - _required_ - the remote address of the database, e.g. "192.168.1.2". +- `connectAddr` - _required_ - the remote address of the database, for example "192.168.1.2". - `connectProtocol` - _required_ - the protocol that goes with the `connectAddr` - _Valid values_: `tcp` or `unix` - `connectAttributes` - an optional map of key-value attributes to be sent as part of connect `data_source_name` url. diff --git a/docs/references/events.mdx b/docs/references/events.mdx index b2bd6e95df..c2ddba2323 100644 --- a/docs/references/events.mdx +++ b/docs/references/events.mdx @@ -299,7 +299,7 @@ This [Event](/workflow-execution/event#event) type indicates that the Activity h | scheduled_event_id | The Id of the [ActivityTaskScheduled](#activitytaskscheduled) Event that this timeout Event corresponds to. | | started_event_id | The Id of the [ActivityTaskStarted](#activitytaskstarted) Event that this timeout corresponds to. | | retry_state | The reason provided for whether the Task should or shouldn't be retried. | -| timeout_type | The type of timeout that led to this Event, e.g., Start-to-Close, Schedule-to-Close, Schedule-to-Start. | +| timeout_type | The type of timeout that led to this Event, for example, Start-to-Close, Schedule-to-Close, Schedule-to-Start. | You can run a Workflow containing an Activity Execution that takes longer than the Start-to-Close Timeout you set and use a RetryPolicy that sets MaxAttempts to 1 so it does not retry indefinitely. When the Activity times out, you will observe that the `ActivityTaskTimedOut` Event contains other attributes missing from the documentation, including the type of timeout that led to the Event. diff --git a/docs/troubleshooting/performance-bottlenecks.mdx b/docs/troubleshooting/performance-bottlenecks.mdx index 302e3fa14f..3f96153e86 100644 --- a/docs/troubleshooting/performance-bottlenecks.mdx +++ b/docs/troubleshooting/performance-bottlenecks.mdx @@ -41,7 +41,7 @@ This metric represents the time between when a [Workflow Task](/tasks#workflow-t To diagnose and address high `temporal_workflow_task_schedule_to_start_latency`, you should: 1. Check Worker CPU and memory usage. -1. Review Worker configuration (number of pollers, Task slots, etc.). +1. Review Worker configuration (such as number of pollers and Task slots). 1. Look for any spikes in Workflow or Activity starts that might be overwhelming the system. 1. Ensure Workers are in the same region as the Temporal cluster if possible. @@ -59,7 +59,7 @@ Here are some potential causes: To diagnose and address high `temporal_activity_schedule_to_start_latency`: 1. Check Worker CPU and memory usage. -1. Review Worker configuration (number of pollers, Task slots, etc.). +1. Review Worker configuration (such as number of pollers and Task slots). 1. Look for any spikes in Workflow or Activity starts that might be overwhelming the system. 1. Ensure Workers are in the same region as the Temporal cluster if possible.