observability/search-attributes

47 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Creating custom Search Attributes in Temporal Service

Custom Search Attributes are created in the Temporal Service using the CLI or Web UI. Example CLI command: temporal operator search-attribute create --name CustomKeywordField --type Text. The name should be replaced with the Search Attribute name, and the type should be one of: Text, Keyword, Int, Double, Bool, Datetime, or KeywordList.

Setting Search Attributes when starting a Workflow

To set custom Search Attributes when starting a Workflow, use the TypedSearchAttributes property on WorkflowOptions for StartWorkflowAsync or ExecuteWorkflowAsync. Typed search attributes are a SearchAttributeCollection created with a builder: ```csharp var myKeywordAttributeKey = SearchAttributeKey.CreateKeyword("MyKeywordAttribute"); var handle = await client.StartWorkflowAsync( (MyWorkflow wf) => wf.RunAsync(), new(id: "my-workflow-id", taskQueue: "my-task-queue") { TypedSearchAttributes = new SearchAttributeCollection.Builder(). Set(myKeywordAttributeKey, "SomeKeywordValue"). ToSearchAttributeCollection(), }); ```

Upsert Search Attributes from Workflow code

Search Attributes can be upserted from within Workflow code to add, update, or remove Search Attributes. Use the UpsertTypedSearchAttributes() method with a set of updates: ```csharp var myKeywordAttributeKey = SearchAttributeKey.CreateKeyword("MyKeywordAttribute"); var myTextAttributeKey = SearchAttributeKey.CreateText("MyTextAttribute"); Workflow.UpsertTypedSearchAttributes( myKeywordAttributeKey.ValueSet("SomeKeywordValue"), myTextAttributeKey.ValueUnset()); ```

Listing Workflow Executions with ListWorkflowsAsync

Use the ListWorkflowsAsync() method on the Client and pass a List Filter as an argument to filter the listed Workflows. The result is an async enumerable: ```csharp await foreach (var wf in client.ListWorkflowsAsync("WorkflowType='GreetingWorkflow'")) { Console.WriteLine("Workflow: {0}", wf.Id); } ```

setStaticDetails() for workflow startup

When creating WorkflowOptions, use setStaticDetails() to set multi-line comprehensive information that appears in the Workflow details view in the Temporal UI. The limit is 20K bytes. The input format is standard Markdown excluding images, HTML, and scripts.

setStaticSummary() for workflow startup

When creating WorkflowOptions, use setStaticSummary() to set a single-line description that appears in the Workflow list view in the Temporal UI. The limit is 200 bytes. The input format is standard Markdown excluding images, HTML, and scripts.

Set custom Search Attributes when starting Workflow

When starting a Workflow Execution with a Client, include custom Search Attributes in WorkflowOptions using setTypedSearchAttributes(). Example: WorkflowOptions options = WorkflowOptions.newBuilder().setWorkflowId(workflowID).setTaskQueue(taskQueue).setTypedSearchAttributes(searchAttributes).build();

Upsert Search Attributes in Workflow

Within Workflow code, dynamically add or update Search Attributes using Workflow.upsertTypedSearchAttributes(). Example: Workflow.upsertTypedSearchAttributes(Constants.IS_ORDER_FAILED.valueSet(false));

Query Workflow Executions by Search Attribute

Query Workflow Executions by Search Attribute using a List Filter in the Temporal CLI with the workflow list command, or in code by calling ListWorkflowExecutions on the Temporal Client.

SearchAttributeKey types supported in Java SDK

The following SearchAttributeKey types are supported: Boolean, Double, Long, KeyWord, KeyWordList, and Text.

Java SDK custom Search Attributes setup example

public static final SearchAttributeKey<Boolean> IS_ORDER_FAILED = SearchAttributeKey.forBoolean("isOrderFailed"); WorkflowOptions options = WorkflowOptions.newBuilder() .setWorkflowId(workflowID) .setTaskQueue(Constants.TASK_QUEUE_NAME) .setTypedSearchAttributes(SearchAttributes.newBuilder().set(Constants.IS_ORDER_FAILED, false).build()) .build();

withStaticSummary() sets workflow UI summary

The withStaticSummary() method sets a single-line description that appears in the Workflow list view. The summary is limited to 200 bytes and uses standard Markdown format excluding images, HTML, and scripts.

Workflow summaries and details displayed in three UI locations

Workflow-level metadata appears in three key locations in the Temporal Web UI: Summary & Details (displays static summary and details set when starting the workflow), Current Details (displays dynamic details updated during workflow execution), and Timeline (renders each Activity and Timer as a horizontal bar).

withStaticDetails() sets workflow UI details

The withStaticDetails() method sets multi-line comprehensive information that appears in the Workflow details view. The details support a larger limit of 20K bytes and use standard Markdown format excluding images, HTML, and scripts.

Query Workflow Executions example in PHP

Example of querying Workflow Executions: ```php $paginator = $workflowClient->listWorkflowExecutions('WorkflowType="GreetingWorkflow"'); foreach ($paginator as $info) { echo "Workflow ID: {$info->execution->getID()}\n"; } ```

Set custom Search Attributes example in PHP

Example of setting custom Search Attributes when starting a Workflow: ```php $keyDestinationTime = SearchAttributeKey::forDatetime('DestinationTime'); $keyOrderId = SearchAttributeKey::forKeyword('OrderId'); $workflow = $workflowClient->newWorkflowStub( OrderWorkflowInterface::class, WorkflowOptions::new() ->withWorkflowExecutionTimeout('10 minutes') ->withTypedSearchAttributes( TypedSearchAttributes::empty() ->withValue($keyOrderId, $orderid) ->withValue($keyDestinationTime, new \DateTimeImmutable('2028-11-05T00:10:07Z')) ), ); ```

Upsert Search Attributes in Workflow code with PHP

Within Workflow code, use upsertTypedSearchAttributes method to dynamically add or update Search Attributes. This is useful for Workflows whose attributes need to change based on internal logic or external events.

Upsert Search Attributes example in PHP

Example of upserting Search Attributes in a Workflow: ```php #[Workflow\UpdateMethod] public function postponeDestinationTime(\DateInterval $interval) { // Get the key for the DestinationTime attribute $keyDestinationTime = SearchAttributeKey::forDatetime('DestinationTime'); /** @var DateTimeImmutable $destinationTime */ $destinationTime = Workflow::getInfo()->typedSearchAttributes->get($keyDestinationTime); Workflow::upsertTypedSearchAttributes( $keyDestinationTime->valueSet($destinationTime->add($interval)), ); } ```

Remove Search Attribute from Workflow in PHP

To remove a Search Attribute that was previously set, set it to an empty Map using the valueUnset() method.

Remove Search Attribute example in PHP

Example of removing a Search Attribute from a Workflow: ```php #[Workflow\UpdateMethod] public function unsetDestinationTime() { // Get the key for the DestinationTime attribute $keyDestinationTime = SearchAttributeKey::forDatetime('DestinationTime'); Workflow::upsertTypedSearchAttributes( $keyDestinationTime->valueUnset(), ); } ```

Search Attributes default and custom types in PHP

Default Search Attributes like WorkflowType, StartTime, and ExecutionStatus are automatically added to Workflow Executions. Custom Search Attributes can contain domain-specific data like customerId or numItems and must be created in the Temporal Service before use.

Query Workflow Executions with listWorkflowExecutions

Use the listWorkflowExecutions() method on the Client and pass a List Filter as an argument to filter the listed Workflows. The result is an iterable paginator that can be used with a foreach loop.

Set custom Search Attributes when starting Workflow in PHP

Use the withTypedSearchAttributes method on WorkflowOptions to set custom Search Attributes when starting a Workflow. Pass a TypedSearchAttributes collection created with SearchAttributeKey instances.

Python custom Search Attributes example

from temporalio.client import SearchAttributeKey, SearchAttributePair, TypedSearchAttributes customer_id_key = SearchAttributeKey.for_keyword("CustomerId") misc_data_key = SearchAttributeKey.for_text("MiscData") handle = await client.start_workflow( GreetingWorkflow.run, id="search-attributes-workflow-id", task_queue="search-attributes-task-queue", search_attributes=TypedSearchAttributes([ SearchAttributePair(customer_id_key, "customer_1"), SearchAttributePair(misc_data_key, "customer_1_data") ]), )

Python describe Workflow Search Attributes example

handle_description = await handle.describe() attribute_value = handle_description.search_attributes.get("CustomKeywordField")

Describe Workflow to read Search Attributes

On the Client, call handle.describe() to read the Search Attributes of a Workflow Execution. Access specific Search Attribute values using the search_attributes dictionary.

Python list_workflows() example

async for workflow in client.list_workflows('WorkflowType="GreetingWorkflow"'): print(f"Workflow: {workflow.id}")

Query Workflows using list_workflows()

Use the client.list_workflows() method to query Workflow Executions by Search Attributes. Pass a List Filter as a string argument to filter the listed Workflows. For example, pass 'WorkflowType="GreetingWorkflow"' to filter by Workflow type.

Python upsert Search Attributes example

workflow.upsert_search_attributes([ customer_id_key.value_set("customer_2") ])

Remove Search Attribute from Workflow

To remove a Search Attribute that was previously set, use the value_unset() call on the Search Attribute key and pass it to workflow.upsert_search_attributes().

Python remove Search Attribute example

workflow.upsert_search_attributes([ customer_id_key.value_unset() ])

Search Attributes types in Python

Custom Search Attributes can have the following types: Text, Keyword, Int, Double, Bool, Datetime, or KeywordList. Create Search Attributes using the temporal operator search-attribute create command with the --type parameter.

Set custom Search Attributes when starting Workflow

When starting a Workflow with client.start_workflow(), include custom Search Attributes by passing a TypedSearchAttributes list containing SearchAttributePair instances to the search_attributes parameter. Create SearchAttributeKey instances using for_keyword(), for_text(), and other type-specific methods for each attribute.

Upsert Search Attributes in Workflow

Use the workflow.upsert_search_attributes() method to add or update Search Attributes from within Workflow code. Pass a list of SearchAttributeUpdate objects created via value_set() calls on Search Attribute keys.

Set custom Search Attributes when starting a Workflow example in Ruby

Example of setting custom Search Attributes when starting a Workflow in Ruby: ```ruby MY_KEYWORD_KEY = Temporalio::SearchAttributes::Key.new( 'my-keyword', Temporalio::SearchAttributes::IndexedValueType::KEYWORD ) handle = my_client.start_workflow( MyWorkflow, 'some-input', id: 'my-workflow-id', task_queue: 'my-task-queue', search_attributes: Temporalio::SearchAttributes.new({ MY_KEYWORD_KEY => 'some-value' }) ) ```

Search Attributes types in Ruby

Custom Search Attributes can have the following types: Text, Keyword, Int, Double, Bool, Datetime, or KeywordList. These types are specified when creating a Search Attribute using the CLI command: `temporal operator search-attribute create --name CustomKeywordField --type Text`

Upsert Search Attributes in Workflow in Ruby

To upsert (add, update, or remove) Search Attributes from within Workflow code in Ruby, use the `Temporalio::Workflow.upsert_search_attributes` method with a set of updates. Keys should be predefined for reuse.

Upsert Search Attributes in Workflow example in Ruby

Example of upserting Search Attributes in a Workflow in Ruby: ```ruby MY_KEYWORD_KEY = Temporalio::SearchAttributes::Key.new( 'my-keyword', Temporalio::SearchAttributes::IndexedValueType::KEYWORD ) class MyWorkflow < Temporalio::Workflow::Definition def execute Temporalio::Workflow.upsert_search_attributes(MY_KEYWORD_KEY.value_set('some-new-value')) end end ```

List Workflow Executions by filter in Ruby

Use the `list_workflows` method on the Client and pass a List Filter as an argument to filter Workflows. The result is a lazy enumerator/enumerable. Example: `my_client.list_workflows("WorkflowType='GreetingWorkflow'").each { |wf| puts "Workflow: #{wf.id}" }`

Activity summary truncation on Timeline

In the Temporal UI Timeline tab, activity and timer summary labels that exceed 120 characters are truncated with an ellipsis.

Activity summary support in Temporal UI Timeline

Activity summary support on the Timeline shipped in Temporal UI v2.34.6 and is available on Temporal Cloud and on self-hosted UI builds at that version or later.

staticDetails parameter for workflow start

When starting a workflow using client.workflow.start() or client.workflow.execute(), you can provide a staticDetails parameter. This can be multi-line and provides comprehensive information that appears in the workflow details view, with a limit of 20K bytes. The format is standard Markdown excluding images, HTML, and scripts.

staticSummary parameter for workflow start

When starting a workflow using client.workflow.start() or client.workflow.execute(), you can provide a staticSummary parameter. This is a single-line description that appears in the workflow list view and is limited to 200 bytes.

Fan-out workflow use of activity summaries

Setting a distinct summary for each activity is especially useful for fan-out workflows that schedule many instances of the same activity type. When each activity has a unique summary, it becomes possible to distinguish individual activity instances on the Timeline, where the activity type alone would not provide sufficient differentiation.

Event history display of summaries

Individual events in the workflow's Event History display their associated summaries when available. Workflow, activity, and timer summaries appear in purple text next to their corresponding events, providing immediate context without requiring event expansion. When an event is expanded, the summary is also prominently displayed in the detailed view.

Search Attributes billing for Workflow start

Search Attributes provided at Workflow start do not count as billable Actions. If Search Attribute values are known before starting the Workflow, provide them at Workflow start to eliminate these costs entirely.

UpsertSearchAttributes billing behavior

For Search Attributes that must be updated during Workflow Execution, each UpsertSearchAttributes call counts as 1 Action regardless of how many attributes are updated. Batch multiple related attribute updates into single operations to reduce Actions consumed.

Give your agent this brain