Skip to main content

Task status tracking (Redis events + optional S3 history)

This document describes how Alakai tracks automation tasks.

What is tracked​

For each tracked execution, Alakai emits lifecycle events with:

  • taskName
  • status (in_progress, success, error)
  • project (owner/repo)
  • actor (creator/provider reference, Slack or GitHub)
  • prLinks (created PR URLs when available)
  • visibility.responsibleUsers (from config.json)
  • executionId, eventId, occurredAt, flow

Runtime topology​

Task tracking runtime is always active. src/main.ts wires:

  1. Publisher (RedisTaskTrackingService)
    App routes emit task lifecycle events into a Redis Stream.
  2. Projector worker (RedisTaskStatusProjector)
    Reads stream events and stores latest status by execution in Redis.
  3. Archiver worker (S3TaskHistoryArchiver, optional)
    When enabled by env, reads stream events and writes immutable JSONL batches to S3.

Workers run in-process with the HTTP service and are started/stopped with server lifecycle.

Configuration​

Required​

  • TASK_TRACKING_REDIS_URL

Optional (with defaults)​

  • TASK_TRACKING_REDIS_STREAM_KEY (task-events:v1)
  • TASK_TRACKING_REDIS_PROJECTOR_CONSUMER_GROUP (task-status-projector)
  • TASK_TRACKING_REDIS_ARCHIVER_CONSUMER_GROUP (task-history-archiver)
  • TASK_TRACKING_REDIS_CONSUMER_NAME (alakai)
  • TASK_TRACKING_S3_ARCHIVE_ENABLED (false)
  • TASK_TRACKING_S3_BUCKET (required when TASK_TRACKING_S3_ARCHIVE_ENABLED=true)
  • TASK_TRACKING_S3_PREFIX (task-tracking)

Additional prerequisite:

  • Redis Node client package must be installed in runtime: yarn add redis

Redis data layout​

Input stream​

  • Stream key: TASK_TRACKING_REDIS_STREAM_KEY (default task-events:v1)
  • Message field: event (JSON string)

Projected status (latest state)​

  • Per execution hash: task-tracking:execution:{executionId}
  • Per project sorted set index: task-tracking:project:{project}:executions
    • score: occurredAt timestamp (ms)
    • value: executionId

Ordering rule:

  • Older out-of-order events do not overwrite newer projected state.

S3 archive layout​

When TASK_TRACKING_S3_ARCHIVE_ENABLED=true, archived events are grouped by project/day and stored as newline-delimited JSON:

{TASK_TRACKING_S3_PREFIX}/{project}/{YYYY-MM-DD}/events-{timestamp}-{suffix}.jsonl

Example:

task-tracking/my-org/my-repo/2026-03-15/events-1700000000000-ab12cd.jsonl

Each file is immutable and contains one JSON event per line.

If TASK_TRACKING_S3_ARCHIVE_ENABLED=false, archival is skipped and only Redis stream + projection remain active.

Rollout plan​

  1. Provision Redis connectivity and runtime dependency (redis) where Alakai runs.
  2. Validate in staging:
    • service starts without runtime init errors
    • stream receives events
    • projector keys are updated
  3. If historical archive is needed, enable:
    • TASK_TRACKING_S3_ARCHIVE_ENABLED=true
    • TASK_TRACKING_S3_BUCKET + permissions
  4. Validate S3 JSONL object creation when archival is enabled.
  5. Roll out to production.

Rollback​

Rollback for archival only:

  1. Set TASK_TRACKING_S3_ARCHIVE_ENABLED=false
  2. Restart Alakai

Effect: task tracking stream + projection continue; only S3 archival is disabled.

Dashboard snapshot + realtime SSE read paths are documented in Task Dashboard.