Evolve observability documentation (#797)

Author: dandavison

.github/workflows/ci.yml

@@ -109,9 +109,8 @@ jobs:
 
   # Runs the sdk features repo tests with this repo's current SDK code
   features-tests:
-    uses: temporalio/features/.github/workflows/python.yaml@uv
+    uses: temporalio/features/.github/workflows/python.yaml@main
     with:
       python-repo-path: ${{github.event.pull_request.head.repo.full_name}}
       version: ${{github.event.pull_request.head.ref}}
       version-is-repo-ref: true
-      features-repo-ref: uv

README.md

@@ -97,7 +97,9 @@ informal introduction to the features and their implementation.
         - [Worker Shutdown](#worker-shutdown)
       - [Testing](#testing-1)
     - [Workflow Replay](#workflow-replay)
-    - [OpenTelemetry Support](#opentelemetry-support)
+    - [Observability](#observability)
+      - [Metrics](#metrics)
+      - [OpenTelemetry Tracing](#opentelemetry-tracing)
     - [Protobuf 3.x vs 4.x](#protobuf-3x-vs-4x)
     - [Known Compatibility Issues](#known-compatibility-issues)
       - [gevent Patching](#gevent-patching)
@@ -1344,10 +1346,30 @@ async def check_past_histories(my_client: Client):
   )
 ```
 
-### OpenTelemetry Support
+### Observability
 
-OpenTelemetry support requires the optional `opentelemetry` dependencies which are part of the `opentelemetry` extra.
-When using `pip`, running
+See https://github.com/temporalio/samples-python/tree/main/open_telemetry for a sample demonstrating collection of
+metrics and tracing data emitted by the SDK.
+
+#### Metrics
+
+The SDK emits various metrics by default: see https://docs.temporal.io/references/sdk-metrics. To configure additional
+attributes to be emitted with all metrics, pass
+[global_tags](https://python.temporal.io/temporalio.runtime.TelemetryConfig.html#global_tags) when creating the
+[TelemetryConfig](https://python.temporal.io/temporalio.runtime.TelemetryConfig.html).
+
+For emitting custom metrics, the SDK makes a metric meter available:
+- In Workflow code, use https://python.temporal.io/temporalio.workflow.html#metric_meter
+- In Activity code, use https://python.temporal.io/temporalio.activity.html#metric_meter
+- In normal application code, use https://python.temporal.io/temporalio.runtime.Runtime.html#metric_meter
+
+The attributes emitted by these default to `namespace`, `task_queue`, and `workflow_type`/`activity_type`; use
+`with_additional_attributes` to create a meter emitting additional attributes.
+
+#### OpenTelemetry Tracing
+
+Tracing support requires the optional `opentelemetry` dependencies which are part of the `opentelemetry` extra. When
+using `pip`, running
 
     pip install 'temporalio[opentelemetry]'
 

tests/worker/test_activity.py

@@ -611,7 +611,12 @@ async def some_activity(param1: SomeClass2, param2: str) -> str:
     assert activity_param1 == SomeClass2(foo="str1", bar=SomeClass1(foo=123))
 
 
-async def test_activity_heartbeat_details(client: Client, worker: ExternalWorker):
+async def test_activity_heartbeat_details(
+    client: Client, worker: ExternalWorker, env: WorkflowEnvironment
+):
+    if env.supports_time_skipping:
+        pytest.skip("https://github.com/temporalio/sdk-java/issues/2459")
+
     @activity.defn
     async def some_activity() -> str:
         info = activity.info()
@@ -698,8 +703,11 @@ def picklable_heartbeat_details_activity() -> str:
 
 
 async def test_sync_activity_thread_heartbeat_details(
-    client: Client, worker: ExternalWorker
+    client: Client, worker: ExternalWorker, env: WorkflowEnvironment
 ):
+    if env.supports_time_skipping:
+        pytest.skip("https://github.com/temporalio/sdk-java/issues/2459")
+
     with concurrent.futures.ThreadPoolExecutor(
         max_workers=default_max_concurrent_activities
     ) as executor:
@@ -714,8 +722,11 @@ async def test_sync_activity_thread_heartbeat_details(
 
 
 async def test_sync_activity_process_heartbeat_details(
-    client: Client, worker: ExternalWorker
+    client: Client, worker: ExternalWorker, env: WorkflowEnvironment
 ):
+    if env.supports_time_skipping:
+        pytest.skip("https://github.com/temporalio/sdk-java/issues/2459")
+
     with concurrent.futures.ProcessPoolExecutor() as executor:
         result = await _execute_workflow_with_activity(
             client,
@@ -1066,8 +1077,14 @@ async def test_activity_async_success(
 
 @pytest.mark.parametrize("use_task_token", [True, False])
 async def test_activity_async_heartbeat_and_fail(
-    client: Client, worker: ExternalWorker, use_task_token: bool
+    client: Client,
+    worker: ExternalWorker,
+    env: WorkflowEnvironment,
+    use_task_token: bool,
 ):
+    if env.supports_time_skipping:
+        pytest.skip("https://github.com/temporalio/sdk-java/issues/2459")
+
     wrapper = AsyncActivityWrapper()
     # Start task w/ max attempts 2, wait for info, send heartbeat, fail
     task = asyncio.create_task(

tests/worker/test_workflow.py

@@ -222,7 +222,7 @@ async def test_workflow_info(client: Client, env: WorkflowEnvironment):
         assert info["retry_policy"] == json.loads(
             json.dumps(dataclasses.asdict(retry_policy), default=str)
         )
-        assert uuid.UUID(info["run_id"]).version == 4
+        assert uuid.UUID(info["run_id"]).version == 7
         assert info["run_timeout"] is None
         datetime.fromisoformat(info["start_time"])
         assert info["task_queue"] == worker.task_queue