From 8dd383a006ba7db0f9bd31791ea5ec3d7b6cb6c2 Mon Sep 17 00:00:00 2001 From: Duncan Mackenzie Date: Fri, 31 Jul 2026 15:50:49 -0700 Subject: [PATCH 1/4] Normalize metrics terminology: tag (SDK/Server) vs label (Prometheus/OpenMetrics) Our docs used three different words for the same metrics dimension in different places: "tag" (SDK/self-hosted-Server docs, matching the real Go/Java SDK APIs like WithTags/.tagged() and the Server's tags/excludeTags config keys), "label" (Temporal Cloud's OpenMetrics docs, matching what OpenMetrics/PromQL/Grafana actually call it - OpenMetrics never uses "tag" at all), and even "key" in a few spots on the same reference page. - docs/references/sdk-metrics.mdx: normalize the stray "key(s)" (4 places) and one stray "label" to "tag(s)", matching the page's dominant convention and what bin/check-metrics-reference.js expects in its "Tags:" line parsing (verified the check still passes). - docs/design-patterns/retry-metrics.mdx: this page mixed both terms in one section ("Add dimension labels" heading, "Add labels (tags)" body, "adds default labels" prose) right next to Go/Java code samples calling the literal WithTags/.tagged() API. Normalized to "tags" throughout to match the code. - docs/glossary.md: added a Tag entry bridging the two terms, since no entry existed for either before. - docs/cloud/metrics/openmetrics/api-reference.mdx: cross-linked the Labels section back to the new glossary entry so the bridge works from both directions. Left docs/develop/java/activities/basics.mdx's "Prometheus may ignore metrics with tags..." as-is per feedback - out of scope for this pass. --- docs/cloud/metrics/openmetrics/api-reference.mdx | 1 + docs/design-patterns/retry-metrics.mdx | 6 +++--- docs/glossary.md | 7 +++++++ docs/references/sdk-metrics.mdx | 10 +++++----- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/cloud/metrics/openmetrics/api-reference.mdx b/docs/cloud/metrics/openmetrics/api-reference.mdx index 785ba15630..c7747b9d05 100644 --- a/docs/cloud/metrics/openmetrics/api-reference.mdx +++ b/docs/cloud/metrics/openmetrics/api-reference.mdx @@ -78,6 +78,7 @@ The list of metrics and their labels are available via the [List Descriptors](/c ### Labels A label is a key-value attribute associated with a metric data point. Labels can be used to filter or aggregate metrics. +Temporal SDKs and the Temporal Service call this same concept a [tag](/glossary#tag); it's called a label once scraped in OpenMetrics format. Common labels include: diff --git a/docs/design-patterns/retry-metrics.mdx b/docs/design-patterns/retry-metrics.mdx index aad747564a..ef39080a52 100644 --- a/docs/design-patterns/retry-metrics.mdx +++ b/docs/design-patterns/retry-metrics.mdx @@ -287,9 +287,9 @@ export async function monitoredRetryWorkflow(endpoint: string): Promise -### Add dimension labels to the metric +### Add dimension tags to the metric -Add labels (tags) to the metric to identify which Activity type, endpoint, or Workflow is producing the high attempt counts. +Add tags to the metric to identify which Activity type, endpoint, or Workflow is producing the high attempt counts. This makes the metric actionable in dashboards and alerts. @@ -356,7 +356,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 labels such as namespace and task queue automatically. +- **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. - **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. diff --git a/docs/glossary.md b/docs/glossary.md index 1cf3f9c3b4..d4fcd37cbc 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -613,6 +613,13 @@ Queue to listen on. +#### [Tag](/references/sdk-metrics) + +A Tag is a key-value pair that a Temporal SDK or the Temporal Service attaches to an emitted metric, such as `namespace` or `task_queue`. +Once a metric is scraped by Prometheus or another OpenMetrics-compatible system, the same key-value pair is called a label. + + + #### [Task](/tasks#task) A Task is the context needed to make progress with a specific Workflow Execution or Activity Execution. diff --git a/docs/references/sdk-metrics.mdx b/docs/references/sdk-metrics.mdx index dcaf0fd221..117ba36278 100644 --- a/docs/references/sdk-metrics.mdx +++ b/docs/references/sdk-metrics.mdx @@ -64,7 +64,7 @@ The Core SDK is a shared common core library used by several Temporal SDKs, incl ::: -Each metric may have some combination of the following keys attached to them: +Each metric may have some combination of the following [tags](/glossary#tag) attached to them: - `task_queue`: Task Queue that the Worker Entity is polling - `namespace`: Namespace the Worker is bound to @@ -82,7 +82,7 @@ Each metric may have some combination of the following keys attached to them: - `workflow_type`: The name of the Workflow Function the metric is associated with - `operation`: RPC method name; available for metrics related to Temporal Client gRPC requests -Some keys may not be available in every SDK, and Histogram metrics may have different buckets in each SDK. +Some tags may not be available in every SDK, and Histogram metrics may have different buckets in each SDK. | Metric name | Emitted by | Metric type | Availability | | -------------------------------------------------------------------------------------------- | -------------- | ----------- | -------------- | @@ -173,7 +173,7 @@ An Activity Worker poll for an Activity Task timed out, and no Activity Task is The Schedule-To-Start time of an Activity Task. A [Schedule-To-Start Timeout](/encyclopedia/detecting-activity-failures#schedule-to-start-timeout) can be set when an Activity Execution is spawned. Use this metric to check that Activity Tasks are being processed from the queue in a timely manner. -Some SDKs include the `activity_type` label, but the metric should not vary by type, because the type does not influence the rate at which tasks are pulled from the queue. +Some SDKs include the `activity_type` tag, but the metric should not vary by type, because the type does not influence the rate at which tasks are pulled from the queue. - Type: Histogram - Available in: Core, Go, Java @@ -435,7 +435,7 @@ A Worker Entity has been registered, created, or started. ### `worker_task_slots_available` The total number of Workflow, Activity, Local Activity, or Nexus Task execution slots that are currently available. -Use the `worker_type` key to differentiate execution slots. +Use the `worker_type` tag to differentiate execution slots. The Worker type specifies an ability to perform certain tasks. For example, Workflow Workers execute Workflow Tasks, Activity Workers execute Activity Tasks, and so forth. @@ -446,7 +446,7 @@ For example, Workflow Workers execute Workflow Tasks, Activity Workers execute A ### `worker_task_slots_used` The total number of Workflow, Activity, Local Activity, or Nexus Tasks execution slots in current use. -Use the `worker_type` key to differentiate execution slots. +Use the `worker_type` tag to differentiate execution slots. The Worker type specifies an ability to perform certain tasks. For example, Workflow Workers execute Workflow Tasks, Activity Workers execute Activity Tasks, and so forth. From d9caa087fc0046af7003d2ae98cb70df7d54d312 Mon Sep 17 00:00:00 2001 From: Duncan Mackenzie Date: Fri, 31 Jul 2026 15:53:21 -0700 Subject: [PATCH 2/4] Add a tags-vs-labels callout to the SDK and Service metrics references Short :::note near the top of both pages pointing to the new glossary entry, so a reader hits the terminology bridge before they get to the per-metric "Tags:" lines. --- docs/references/cluster-metrics.mdx | 6 ++++++ docs/references/sdk-metrics.mdx | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/docs/references/cluster-metrics.mdx b/docs/references/cluster-metrics.mdx index 0c33cb7887..4c3c4fbb31 100644 --- a/docs/references/cluster-metrics.mdx +++ b/docs/references/cluster-metrics.mdx @@ -21,6 +21,12 @@ See [SDK metrics](/references/sdk-metrics) for metrics emitted by the [SDKs](/en ::: +:::note Tags vs. labels + +Temporal SDKs and the Temporal Service attach these metric dimensions as [tags](/glossary#tag). Once a metric is scraped by Prometheus or another OpenMetrics-compatible system, the same dimensions are called labels. + +::: + A Temporal Service emits a range of metrics to help operators get visibility into the Temporal Service's performance and to set up alerts. All metrics emitted by the Temporal Service are listed in [metric_defs.go](https://github.com/temporalio/temporal/blob/main/common/metrics/metric_defs.go). diff --git a/docs/references/sdk-metrics.mdx b/docs/references/sdk-metrics.mdx index 117ba36278..bc483373d9 100644 --- a/docs/references/sdk-metrics.mdx +++ b/docs/references/sdk-metrics.mdx @@ -25,6 +25,12 @@ Treat any others as deprecated, inconsistent, or experimental. ::: +:::note Tags vs. labels + +Temporal SDKs and the Temporal Service attach these metric dimensions as [tags](/glossary#tag). Once a metric is scraped by Prometheus or another OpenMetrics-compatible system, the same dimensions are called labels. + +::: + The Temporal SDKs emit a set of metrics from Temporal Client usage and Worker Processes. - [How to emit metrics using the Go SDK](/develop/go/platform/observability#metrics) From fe8a48ff3e233908b2b2e2b7703256b25674551a Mon Sep 17 00:00:00 2001 From: Duncan Mackenzie Date: Fri, 31 Jul 2026 15:56:22 -0700 Subject: [PATCH 3/4] Fold tags-vs-labels note into the existing info callout, not a new one Two ::: admonitions back-to-back isn't the style here - merge the note into the page's existing top info block instead of stacking a second callout right after it. --- docs/references/cluster-metrics.mdx | 4 ---- docs/references/sdk-metrics.mdx | 4 ---- 2 files changed, 8 deletions(-) diff --git a/docs/references/cluster-metrics.mdx b/docs/references/cluster-metrics.mdx index 4c3c4fbb31..6ba151dc74 100644 --- a/docs/references/cluster-metrics.mdx +++ b/docs/references/cluster-metrics.mdx @@ -19,10 +19,6 @@ See [Cloud metrics](/cloud/metrics/) for metrics emitted by [Temporal Cloud](/cl See [SDK metrics](/references/sdk-metrics) for metrics emitted by the [SDKs](/encyclopedia/architecture/temporal-sdks). -::: - -:::note Tags vs. labels - Temporal SDKs and the Temporal Service attach these metric dimensions as [tags](/glossary#tag). Once a metric is scraped by Prometheus or another OpenMetrics-compatible system, the same dimensions are called labels. ::: diff --git a/docs/references/sdk-metrics.mdx b/docs/references/sdk-metrics.mdx index bc483373d9..0720495af3 100644 --- a/docs/references/sdk-metrics.mdx +++ b/docs/references/sdk-metrics.mdx @@ -23,10 +23,6 @@ Some SDKs emit metrics beyond what this reference lists. Only the metrics on this page have guaranteed, defined behavior. Treat any others as deprecated, inconsistent, or experimental. -::: - -:::note Tags vs. labels - Temporal SDKs and the Temporal Service attach these metric dimensions as [tags](/glossary#tag). Once a metric is scraped by Prometheus or another OpenMetrics-compatible system, the same dimensions are called labels. ::: From fea2b8a19682f7536fc3435308419ca5ecf15d7e Mon Sep 17 00:00:00 2001 From: Duncan Mackenzie Date: Fri, 31 Jul 2026 16:08:52 -0700 Subject: [PATCH 4/4] Update GitHub source links to trunk branches and consolidate SDK metric source links per SDK. - Move sdk-java temporal-opentracing and temporal-spring-ai README links to contrib/. - Replace renamed sdk-core repo with sdk-rust. --- docs/develop/go/workflows/selectors.mdx | 2 +- .../data-handling/data-encryption.mdx | 2 +- docs/develop/java/client/temporal-client.mdx | 2 +- docs/develop/java/integrations/spring-ai.mdx | 2 +- docs/develop/java/platform/observability.mdx | 2 +- docs/develop/rust/index.mdx | 2 +- .../data-conversion/codec-server.mdx | 2 +- .../data-conversion/remote-data-encoding.mdx | 2 +- .../temporal-service-configuration.mdx | 2 +- docs/production-deployment/data-encryption.mdx | 2 +- docs/references/sdk-metrics.mdx | 16 ++++------------ 11 files changed, 14 insertions(+), 22 deletions(-) diff --git a/docs/develop/go/workflows/selectors.mdx b/docs/develop/go/workflows/selectors.mdx index 76934f8fd4..b448376d82 100644 --- a/docs/develop/go/workflows/selectors.mdx +++ b/docs/develop/go/workflows/selectors.mdx @@ -101,7 +101,7 @@ If multiple items are available, the order of matching is not defined. An important use case of futures is setting up a race between a timer and a pending activity, effectively adding a "soft" timeout that doesn't result in any errors or retries of that activity. -For example, [the Timer sample](https://github.com/temporalio/samples-go/blob/master/timer) shows how you can write a long running order processing operation where: +For example, [the Timer sample](https://github.com/temporalio/samples-go/tree/main/timer) shows how you can write a long running order processing operation where: - if processing takes too long, we send out a notification email to user about the delay, but we won't cancel the operation - if the operation finishes before the timer fires, then we want to cancel the timer. diff --git a/docs/develop/java/best-practices/data-handling/data-encryption.mdx b/docs/develop/java/best-practices/data-handling/data-encryption.mdx index a388ad08dd..4027019592 100644 --- a/docs/develop/java/best-practices/data-handling/data-encryption.mdx +++ b/docs/develop/java/best-practices/data-handling/data-encryption.mdx @@ -163,4 +163,4 @@ You create, operate, and manage access to your Codec Server in your own environm The Temporal CLI and the Web UI in turn provide built-in hooks to call the Codec Server to decode encrypted payloads on demand. Refer to the [Codec Server](/production-deployment/data-encryption) documentation for information on how to design and deploy a Codec Server. -For reference, see the [Codec server](https://github.com/temporalio/sdk-java/tree/master/temporal-remote-data-encoder) sample. +For reference, see the [Codec server](https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder) sample. diff --git a/docs/develop/java/client/temporal-client.mdx b/docs/develop/java/client/temporal-client.mdx index 2b67b1a48c..42af8a16f3 100644 --- a/docs/develop/java/client/temporal-client.mdx +++ b/docs/develop/java/client/temporal-client.mdx @@ -669,7 +669,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/master/temporal-sdk/src/main/java/io/temporal/client/WorkflowClient.java) + [`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 Workflows asynchronously. diff --git a/docs/develop/java/integrations/spring-ai.mdx b/docs/develop/java/integrations/spring-ai.mdx index 235af9725c..672b113ee9 100644 --- a/docs/develop/java/integrations/spring-ai.mdx +++ b/docs/develop/java/integrations/spring-ai.mdx @@ -395,6 +395,6 @@ new McpPlugin(); ## Resources -- [`temporal-spring-ai` README](https://github.com/temporalio/sdk-java/blob/master/temporal-spring-ai/README.md) — full reference for the module +- [`temporal-spring-ai` README](https://github.com/temporalio/sdk-java/blob/main/contrib/temporal-spring-ai/README.md) — full reference for the module - [Spring Boot integration](/develop/java/integrations/spring-boot-integration) — required companion module - [Plugin system](/develop/plugins-guide) — how integrations are registered with Workers and Clients diff --git a/docs/develop/java/platform/observability.mdx b/docs/develop/java/platform/observability.mdx index 0e447b9d66..de3714d861 100644 --- a/docs/develop/java/platform/observability.mdx +++ b/docs/develop/java/platform/observability.mdx @@ -116,7 +116,7 @@ WorkerFactoryOptions factoryOptions = WorkerFactory factory = WorkerFactory.newInstance(client, factoryOptions); ``` -For more information, see the Temporal [OpenTracing module](https://github.com/temporalio/sdk-java/blob/master/temporal-opentracing/README.md). +For more information, see the Temporal [OpenTracing module](https://github.com/temporalio/sdk-java/blob/main/contrib/temporal-opentracing/README.md). ### Context Propagation Over Nexus Operation Calls diff --git a/docs/develop/rust/index.mdx b/docs/develop/rust/index.mdx index a67e3cfa48..87766ba2f2 100644 --- a/docs/develop/rust/index.mdx +++ b/docs/develop/rust/index.mdx @@ -63,7 +63,7 @@ Once your local Temporal Service is set up, continue building with the following - [Rust SDK Quickstart - Setup Guide](/develop/rust/quickstart) - [Rust API Documentation](https://docs.rs/temporalio-sdk/latest/temporalio_sdk/) -- [Rust SDK GitHub](https://github.com/temporalio/sdk-core/tree/master/crates/sdk) +- [Rust SDK GitHub](https://github.com/temporalio/sdk-rust/tree/main/crates/sdk) ### Get Connected with the Temporal Rust Community diff --git a/docs/encyclopedia/data-conversion/codec-server.mdx b/docs/encyclopedia/data-conversion/codec-server.mdx index ce0b966711..a1f1d13858 100644 --- a/docs/encyclopedia/data-conversion/codec-server.mdx +++ b/docs/encyclopedia/data-conversion/codec-server.mdx @@ -208,7 +208,7 @@ Codec Server. Most Temporal SDKs provide example Codec Server implementations: - [Go](https://github.com/temporalio/samples-go/tree/main/codec-server) -- [Java](https://github.com/temporalio/sdk-java/tree/master/temporal-remote-data-encoder) +- [Java](https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder) - [Python](https://github.com/temporalio/samples-python/blob/main/encryption/codec_server.py) | [Python with External Storage](https://github.com/temporalio/samples-python/tree/main/external_storage) - [TypeScript](https://github.com/temporalio/samples-typescript/blob/main/encryption/src/codec-server.ts) - [.NET](https://github.com/temporalio/samples-dotnet/blob/main/src/Encryption/CodecServer/Program.cs) diff --git a/docs/encyclopedia/data-conversion/remote-data-encoding.mdx b/docs/encyclopedia/data-conversion/remote-data-encoding.mdx index 13d87b7630..4e62143fe2 100644 --- a/docs/encyclopedia/data-conversion/remote-data-encoding.mdx +++ b/docs/encyclopedia/data-conversion/remote-data-encoding.mdx @@ -52,6 +52,6 @@ Evaluate and ensure that your remote data encoder endpoints are secured and only Samples: - [Go](https://github.com/temporalio/samples-go/tree/main/codec-server) -- [Java](https://github.com/temporalio/sdk-java/tree/master/temporal-remote-data-encoder) +- [Java](https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder) - [Python](https://github.com/temporalio/samples-python/tree/main/encryption) - [TypeScript](https://github.com/temporalio/samples-typescript/tree/main/encryption) diff --git a/docs/encyclopedia/temporal-service/temporal-service-configuration.mdx b/docs/encyclopedia/temporal-service/temporal-service-configuration.mdx index 0b7084f58d..e56f610d4f 100644 --- a/docs/encyclopedia/temporal-service/temporal-service-configuration.mdx +++ b/docs/encyclopedia/temporal-service/temporal-service-configuration.mdx @@ -66,7 +66,7 @@ Use dynamic configuration keys to fine-tune your self-deployed Temporal Service For details on dynamic configuration keys, see [Dynamic configuration reference](/references/dynamic-configuration). -For dynamic configuration examples, see [https://github.com/temporalio/temporal/tree/master/config/dynamicconfig](https://github.com/temporalio/temporal/tree/master/config/dynamicconfig). +For dynamic configuration examples, see [https://github.com/temporalio/temporal/tree/main/config/dynamicconfig](https://github.com/temporalio/temporal/tree/main/config/dynamicconfig). ## What is Temporal Service security configuration? {/* #temporal-cluster-security-configuration */} diff --git a/docs/production-deployment/data-encryption.mdx b/docs/production-deployment/data-encryption.mdx index 08c3437994..22af6ff243 100644 --- a/docs/production-deployment/data-encryption.mdx +++ b/docs/production-deployment/data-encryption.mdx @@ -82,7 +82,7 @@ The Web UI and CLI send POST requests to the following endpoints on your Codec S For examples on how to create your Codec Server, see the following Codec Server implementation samples: - [Go](https://github.com/temporalio/samples-go/tree/main/codec-server) -- [Java](https://github.com/temporalio/sdk-java/tree/master/temporal-remote-data-encoder) +- [Java](https://github.com/temporalio/sdk-java/tree/main/temporal-remote-data-encoder) - [Python](https://github.com/temporalio/samples-python/blob/main/encryption/codec_server.py) - [TypeScript](https://github.com/temporalio/samples-typescript/blob/main/encryption/src/codec-server.ts) - [.NET](https://github.com/temporalio/samples-dotnet/blob/main/src/Encryption/CodecServer/Program.cs) diff --git a/docs/references/sdk-metrics.mdx b/docs/references/sdk-metrics.mdx index 0720495af3..ccf4939ec9 100644 --- a/docs/references/sdk-metrics.mdx +++ b/docs/references/sdk-metrics.mdx @@ -40,19 +40,11 @@ The Temporal SDKs emit a set of metrics from Temporal Client usage and Worker Pr All metrics are prefixed with `temporal_` before being exported to their configured destination. Section headings on this page omit the prefix. Some metrics are specific to certain SDKs. +The Availability column in the table below refers to where a metric is defined: -TypeScript, Python, .NET, and Ruby SDK metrics are defined in the Core SDK. - -PHP and Go metrics are defined in the Go SDK. - -Java metrics are defined in the Java SDK. -Metrics are defined in the following locations. - -- [Core SDK Worker metrics](https://github.com/temporalio/sdk-rust/blob/main/crates/sdk-core/src/telemetry/metrics.rs) -- [Core SDK Client metrics](https://github.com/temporalio/sdk-rust/blob/main/crates/client/src/metrics.rs) -- [Java SDK Worker metrics](https://github.com/temporalio/sdk-java/blob/master/temporal-sdk/src/main/java/io/temporal/worker/MetricsType.java) -- [Java SDK Client metrics](https://github.com/temporalio/sdk-java/blob/master/temporal-serviceclient/src/main/java/io/temporal/serviceclient/MetricsType.java) -- [Go SDK Worker and Client metrics](https://github.com/temporalio/sdk-go/blob/c32b04729cc7691f80c16f80eed7f323ee5ce24f/internal/common/metrics/constants.go) +- **Core**: TypeScript, Python, .NET, and Ruby SDK metrics are defined in the Core SDK, in [Worker metrics](https://github.com/temporalio/sdk-rust/blob/main/crates/sdk-core/src/telemetry/metrics.rs) and [Client metrics](https://github.com/temporalio/sdk-rust/blob/main/crates/client/src/metrics.rs). +- **Go**: Go and PHP SDK metrics are defined in the Go SDK, in [Worker and Client metrics](https://github.com/temporalio/sdk-go/blob/main/internal/common/metrics/constants.go). +- **Java**: Java SDK metrics are defined in the Java SDK, in [Worker metrics](https://github.com/temporalio/sdk-java/blob/main/temporal-sdk/src/main/java/io/temporal/worker/MetricsType.java) and [Client metrics](https://github.com/temporalio/sdk-java/blob/main/temporal-serviceclient/src/main/java/io/temporal/serviceclient/MetricsType.java). :::note Metric units across SDKs