Skip to content

update-status

Updates job status in DynamoDB workflow-state table. Called by Step Functions at key workflow transitions (RUNNING, COMPLETED, FAILED).

Overview

Property Value
Trigger Step Functions task callback
Runtime Python 3.11
Timeout 30 seconds
Memory 256 MB

Input Schema

{
    "job_id": "run-abc-123",                    # Required: unique job identifier
    "status": "RUNNING",                         # Required: RUNNING | COMPLETED | FAILED | CANCELLED
    "trace_id": "trace-xyz-789",                # Optional: E2E correlation ID
    "execution_arn": "arn:aws:states:...",       # Optional: Step Functions execution ARN
    "started_at": "2024-02-07T12:00:00Z",       # Optional: ISO timestamp
    "completed_at": "2024-02-07T12:30:00Z",     # Optional: ISO timestamp
    "ecs_task_arn": "arn:aws:ecs:...",           # Optional: ECS task ARN
    "error": {                                   # Optional: error details (for FAILED)
        "Error": "States.TaskFailed",
        "Cause": "Container exited with code 1"
    }
}

Output Schema

{
    "statusCode": 200,
    "body": {
        "job_id": "run-abc-123",
        "status": "RUNNING",
        "updated": true
    }
}

Environment Variables

Variable Required Default Description
WORKFLOW_STATE_TABLE Yes - DynamoDB table for workflow state
REGION No us-east-1 AWS region
ENVIRONMENT No dev Environment name

State Transition Guards

The lambda enforces valid state transitions using DynamoDB conditional expressions:

Target Status Allowed From
PENDING PENDING
RUNNING PENDING, RUNNING
COMPLETED RUNNING, COMPLETED
FAILED PENDING, RUNNING, FAILED
CANCELLED PENDING, RUNNING, CANCELLED

Invalid transitions are rejected with a ConditionalCheckFailedException and logged as warnings. The response indicates updated: false with reason stale_or_invalid_transition.

Key Features

  • Validates status transitions to prevent stale updates
  • Truncates error messages to 2000 chars (DynamoDB item size limits)
  • Tracks trace_id for E2E correlation across workflow steps
  • Guards against duplicate execution ARN updates
  • Publishes CloudWatch metrics for status update success/failure
  • Tracks terminal states (COMPLETED, FAILED) separately via JobsTerminated metric

CloudWatch Metrics

Metric Dimensions Description
StatusUpdates Status, Success, Environment Count of status update attempts
JobsTerminated Status, Environment Count of jobs reaching terminal state

Step Functions Integration

This lambda is called at multiple points in the backtest workflow (v11):

  1. UpdateStatusRunning — Before ECS task launch
  2. UpdateStatusCompleted — After successful backtest (inside HandleSuccess parallel state)
  3. UpdateStatusFailed — On any failure, after cleanup
  4. UpdateStatusValidationFailed — On strategy validation failure

See Also

Related Lambdas:

Architecture:

SDK: