Task List Commands

The tasklist command group provides operations for inspecting task list status and managing task list partitions.

Command Overview

cadence tasklist [command] [flags]

Short alias: tl

cadence tl describe  # Same as: cadence tasklist describe

What is a Task List?

A task list is a queue where Cadence places tasks (decisions or activities) for workers to consume. Key concepts:

Decision Tasks: Workflow logic execution tasks
Activity Tasks: Activity execution tasks
Pollers: Workers polling for tasks
Partitions: Task list can be partitioned for scalability

Task List Operations

describe

Show task list information including active pollers.

cadence tasklist describe --tasklist my-tasklist

# Describe activity task list
cadence tasklist describe \
  --tasklist my-activities \
  --tasklisttype activity

--tasklist

string

required

Task list name

--tasklisttype

string

default:"decision"

Task list type: decision or activity

Example Output:

{
  "pollers": [
    {
      "identity": "worker-1@hostname-a",
      "lastAccessTime": "2024-01-15T10:30:45Z",
      "ratePerSecond": 10.5
    },
    {
      "identity": "worker-2@hostname-b",
      "lastAccessTime": "2024-01-15T10:30:44Z",
      "ratePerSecond": 12.3
    }
  ],
  "taskListStatus": {
    "backlogCountHint": 15,
    "readLevel": 12345,
    "ackLevel": 12340,
    "ratePerSecond": 22.8
  }
}

list-partition

List task list partitions and their host assignments.

cadence tasklist list-partition --tasklist my-tasklist

# List activity task list partitions
cadence tasklist list-partition \
  --tasklist high-throughput-activities \
  --tasklisttype activity

--tasklist

string

required

Task list name

--tasklisttype

string

default:"decision"

Task list type: decision or activity

Example Output:

Task List Partitions:
  Partition 0: hostname-a:7935
  Partition 1: hostname-b:7935
  Partition 2: hostname-c:7935
  Partition 3: hostname-a:7935

Understanding Task List Output

Poller Information

identity: Worker identifier (format: <worker-name>@<hostname>)
lastAccessTime: Last time worker polled for tasks
ratePerSecond: Polling rate in requests per second

Task List Status

backlogCountHint: Approximate number of pending tasks
readLevel: Current read position in task queue
ackLevel: Last acknowledged task position
ratePerSecond: Overall task processing rate

Common Use Cases

Check Worker Health

Verify workers are actively polling:

cadence tasklist describe --tasklist my-workers

Healthy output should show:

Multiple active pollers
Recent lastAccessTime (< 30s ago)
Stable ratePerSecond values

Monitor Task Backlog

Check for task accumulation:

cadence tasklist describe --tasklist slow-activities --tasklisttype activity

Look for:

High backlogCountHint: May need more workers
Large gap between readLevel and ackLevel: Processing delays

Verify Task Distribution

Check partition distribution for scaled task lists:

cadence tasklist list-partition --tasklist high-volume-tasklist

Ensure:

Partitions are evenly distributed across hosts
All partitions have assigned hosts

Decision vs Activity Task Lists

Decision Task Lists

Used for workflow decision tasks:

cadence tasklist describe \
  --tasklist workflow-decisions \
  --tasklisttype decision

Characteristics:

Typically higher throughput
Shorter execution time
One decision task per workflow state change

Activity Task Lists

Used for activity tasks:

cadence tasklist describe \
  --tasklist long-running-activities \
  --tasklisttype activity

Characteristics:

Variable execution time
Can have dedicated task lists per activity type
May require different scaling

Task List Patterns

Single Task List

Simple setup for low-volume workflows:

# Start workflow
cadence workflow start \
  --workflow_type MyWorkflow \
  --tasklist default-tasklist

# Check task list
cadence tasklist describe --tasklist default-tasklist

Activity-Specific Task Lists

Separate task lists for different activity types:

# Fast activities
cadence tasklist describe --tasklist fast-activities --tasklisttype activity

# Slow activities
cadence tasklist describe --tasklist slow-activities --tasklisttype activity

Partitioned Task Lists

High-throughput scenarios with multiple partitions:

cadence tasklist list-partition --tasklist high-volume-decisions

Monitoring and Troubleshooting

No active pollers

Problem: pollers array is emptyCauses:

Workers are not running
Workers are polling different task list
Network connectivity issues

Solution:

# Check worker configuration
# Verify task list name matches
# Check worker logs for errors

High backlog

Problem: backlogCountHint is very highCauses:

Insufficient worker capacity
Slow activity/decision execution
Worker resource constraints

Solutions:

Scale up worker instances
Optimize activity code
Use separate task lists for slow operations
Consider task list partitioning

Stale pollers

Problem: lastAccessTime is old (> 60s)Causes:

Worker crashed but not cleaned up
Worker stuck in long operation
Network issues

Solution:

Check worker health/logs
Restart workers if necessary
Verify network connectivity

Uneven partition distribution

Problem: Partitions concentrated on few hostsCauses:

Host failures not detected
Cluster rebalancing needed

Solution:

Check matching service health
Wait for automatic rebalancing
Contact admin if persistent

Performance Metrics

Key Metrics to Monitor

Active Pollers: Should be > 0, ideally multiple
Backlog Count: Should be low relative to processing rate
Rate Per Second: Should be stable and match expected load
Last Access Time: Should be recent (< 10s for active systems)

Example Health Check Script

#!/bin/bash
# check-tasklist.sh

TASKLIST=$1
OUTPUT=$(cadence tasklist describe --tasklist $TASKLIST --format json)

POLLERS=$(echo $OUTPUT | jq '.pollers | length')
BACKLOG=$(echo $OUTPUT | jq '.taskListStatus.backlogCountHint')

if [ $POLLERS -eq 0 ]; then
  echo "CRITICAL: No active pollers"
  exit 2
elif [ $BACKLOG -gt 1000 ]; then
  echo "WARNING: High backlog: $BACKLOG"
  exit 1
else
  echo "OK: $POLLERS pollers, backlog: $BACKLOG"
  exit 0
fi

Usage:

./check-tasklist.sh my-tasklist

Best Practices

Naming: Use descriptive task list names (e.g., payments-processor, email-sender)
Monitoring: Regularly check task list health in production
Separation: Use different task lists for different activity types/priorities
Scaling: Monitor backlog and scale workers accordingly
Partitioning: Enable for high-throughput task lists (> 1000 tasks/sec)
Worker Identity: Use meaningful worker identities for debugging

Worker Configuration

When configuring workers, ensure task list names match:

// Worker code example
worker.New(serviceClient, "my-tasklist", worker.Options{
    Identity: "my-worker@" + hostname,
})

Verify configuration:

cadence tasklist describe --tasklist my-tasklist

Next Steps

Workflow Commands

Start workflows using task lists

Admin Task List

Advanced task list administration

Go SDK Workers

Configure workers for task lists

Scaling Guide

Learn about scaling workers

Overview

Commands

​Command Overview

​What is a Task List?

​Task List Operations

​describe

​list-partition

​Understanding Task List Output

​Poller Information

​Task List Status

​Common Use Cases

​Check Worker Health

​Monitor Task Backlog

​Verify Task Distribution

​Decision vs Activity Task Lists

​Decision Task Lists

​Activity Task Lists

​Task List Patterns

​Single Task List

​Activity-Specific Task Lists

​Partitioned Task Lists

​Monitoring and Troubleshooting

​Performance Metrics

​Key Metrics to Monitor

​Example Health Check Script

​Best Practices

​Worker Configuration

​Next Steps

Workflow Commands

Admin Task List

Go SDK Workers

Scaling Guide

Build docs developers (and LLMs) love

Command Overview

What is a Task List?

Task List Operations

describe

list-partition

Understanding Task List Output

Poller Information

Task List Status

Common Use Cases

Check Worker Health

Monitor Task Backlog

Verify Task Distribution

Decision vs Activity Task Lists

Decision Task Lists

Activity Task Lists

Task List Patterns

Single Task List

Activity-Specific Task Lists

Partitioned Task Lists

Monitoring and Troubleshooting

Performance Metrics

Key Metrics to Monitor

Example Health Check Script

Best Practices

Worker Configuration

Next Steps