Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

23.6 KB
Raw Blame

Tasks Backend Instrumentation

All analytics events tracked from the tasks backend via posthoganalytics.capture().

Update this document whenever a new event or property is added.

All events include group analytics via groups() from posthog.event_usage, which sets instance, organization, customer, and project groups where available.

Standard Properties

Task events

All events captured via Task.capture_event() automatically include:

Property Type Description
task_id str UUID of the task
team_id int Team ID
title str Task title
description str Task description (truncated to 500 chars)
origin_product str Origin product enum value
repository str? Repository in org/repo format (nullable)

TaskRun events

All events captured via TaskRun.capture_event() automatically include:

Property Type Description
task_id str UUID of the task
run_id str UUID of the run
team_id int Team ID
repository str? Repository in org/repo format (nullable)
environment str cloud or local (defaults to cloud)
mode str Execution mode (e.g. background)

Task Model Events

Source: products/tasks/backend/models.py

task_created

Tracked when a new Task is saved. Additional properties:

Property Type Description
has_json_schema bool Whether a JSON schema is attached

task_run_created

Tracked when Task.create_run() is called. Additional properties:

Property Type Description
run_id str UUID of the created run
mode str Execution mode
environment str cloud or local
is_resume bool Whether this resumes a previous run
has_pending_message bool Whether there's a pending message

task_deleted

Tracked when Task.soft_delete() is called. Additional properties:

Property Type Description
duration_seconds float Seconds since task creation

Facade events

Source: products/tasks/backend/facade/api.py

task_handed_off

Tracked when a task controller hands the task off to a colleague (ownership moves to the recipient). Captured under the handoff actor's identity rather than the recipient's, even though the task's created_by has moved by then. Additional properties:

Property Type Description
from_user_id int? User ID of the previous owner
to_user_id int User ID of the recipient (new owner)

Channel / Space Configuration Events

Source: repository_config_analytics.py, called from facade/api.py, models.py, and presentation/views/channels_api.py.

These do not go through Task.capture_event(), so the "Task events" standard-property table above does not apply — they carry only the properties listed here plus groups(). distinct_id is the acting user, falling back to the team UUID.

Neither Channel nor Task has an activity log, so before these events the only trace of a repository change was the row's own updated_at.

repository_config_changed

Fires when a Space's or a Task's repository configuration changes. Nothing is captured when a write resubmits the same repository set and the same integration.

Property Type Description
subject str space or task
trigger str space_settings_edit, task_settings_edit, task_created, or github_integration_disconnected
team_id int
channel_id str? Always set for subject=space; set for subject=task when the task has a channel
task_id str? subject=task only
origin_product str? subject=task only
previous_repository_count int The "from"
repository_count int The "to"
added_count / removed_count int
is_first_configuration bool Previous list was empty
is_cleared bool New list is empty
github_integration_changed bool
github_integration_id int? PostHog-side integration id
previous_github_integration_id int?
space_repository_count int? subject=task only — the channel's current list size
diverged_from_space bool? subject=task only — the new task list differs from the channel's
was_inherited_from_space bool? subject=task only — this edit is what broke inheritance
affected_space_count int? trigger=github_integration_disconnected only

trigger=task_created fires only when the caller overrode the Space default. A task that inherits its channel's repositories is already counted by task_created.

trigger=github_integration_disconnected is one aggregate row for the whole pre_delete sweep, not one row per Space.

Reading note: ticking "Use these repositories for the whole space" in the desktop repository dialog fires both a task-level and a space-level change from a single click. Two rows is correct — they are two config objects — but a "changes per user" metric counts objects, not intents.

space_context_changed

Fires when a Space's CONTEXT.md is published or cleared. Carries byte counts only; CONTEXT.md is customer-authored free text.

Property Type Description
action str published or cleared
source str user or agent
storage str legacy_instructions or context_wiki
actor_type str? user_or_api or task_agent for context-wiki edits
team_id int
channel_id str
previous_version int? 0 when there was none; null for context-wiki commits
new_version int? Null on cleared
is_first_version bool
content_bytes int Length only, never content
previous_content_bytes int? Gives edit magnitude
base_version_provided bool Whether the client used the optimistic-concurrency guard
versions_deleted int? cleared only

source is load-bearing: agent runs republish often, so filter to source=user for any human-edit question.

TaskRun Model Events

Source: products/tasks/backend/models.py

task_run_completed

Tracked when TaskRun.mark_completed() is called. Additional properties:

Property Type Description
duration_seconds float Time from creation to completion

task_run_failed

Captured exactly once per failed run, by whichever component performs the DB transition to FAILED: TaskRun.mark_failed() (janitor sweeps via the facade), the update_task_run_status Temporal activity (workflow failures), the facade run PATCH path (agent-reported failures), or _terminalize_unstarted_task_run (workflow dispatch failures). Additional properties:

Property Type Description
error_type str Stable failure source: exception class name (workflow failures), agent_reported, stale_queued_cleanup, workflow_start_failed, followup_delivery_failed, stale_run_reaped; unspecified when unknown
error_message str Error message (truncated to the last 500 chars — the root cause sits at the tail)
duration_seconds float Time from creation to failure

Workflow Events

Source: products/tasks/backend/temporal/process_task/workflow.py

These events are tracked via _track_workflow_event() which calls the track_workflow_event Temporal activity. All workflow events include organization and project group analytics and are enriched with Temporal context properties (see Temporal Context).

task_run_started

Tracked when the workflow begins execution.

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
repository str Repository in org/repo format
team_id int Team ID

sandbox_started

Tracked after sandbox and agent server are provisioned.

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
sandbox_id str Sandbox identifier
sandbox_url str URL of the sandbox
used_snapshot bool Whether a snapshot was used
repository str Repository in org/repo format
boot_path str Classic or overlapping clone boot
boot_total_ms int Infrastructure boot time, excluding setup agent execution
sandbox_create_ms int Sandbox creation time
repo_clone_ms int Repository clone time
branch_checkout_ms int Branch checkout time
agent_launch_ms int Agent server launch time
agent_prepare_ms int Backend launch configuration time
agent_invoke_ms int Sandbox launcher and process start time
agent_health_poll_ms int Time spent polling the agent health endpoint
agent_ready_wait_ms int Time spent waiting for the agent server
agent_session_init_ms int Agent session initialization time
agent_server_total_ms int Agent server initialization time
agent_server_http_ready_ms int Time from agent process start to HTTP listen
agent_launcher_to_process_ms int Time from sandbox launch command to agent process start
agent_context_fetch_ms int Task and run context fetch time inside agent-server
agent_acp_initialize_ms int ACP process handshake time
agent_repository_ready_ms int Time waiting on the repository-ready barrier
agent_session_dependencies_ms int Skill, resume, relay, and PR checkout preparation
agent_session_create_ms int ACP session creation or resumption time

agent_shadow_observed

Tracked after the shadow observer finishes or the result read times out. Use run_id, task_id, and sandbox_id to correlate this event with sandbox_started.

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
sandbox_id str Sandbox identifier
launched bool Whether the matching observer launch started
outcome str Observer outcome: ready or failed
observed_ready_ms int Observer readiness time on ready outcomes
production_ready_ms int Production readiness time on ready outcomes
failure_class str Allowlisted observer failure category
read_timed_out bool Whether result collection timed out

agent_first_command_dispatched

Tracked once when the first non-steering agent command is dispatched.

agent_first_activity_observed

Tracked once when the first agent-generated message, thought, or tool call is observed.

Both first-interaction events include:

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
sandbox_id str Sandbox identifier
elapsed_ms int Time from the workflow start
since_agent_ready_ms int Time from agent readiness
boot_path str Classic or overlapping clone boot
image_source str Sandbox image source
origin_product str Product that created the task
mode str Background or interactive
task_runtime str ACP or Pi runtime
runtime_adapter str Runtime adapter
provider str Model provider
sandbox_backend str Sandbox provider
transport str SSE or sequenced event ingest
prewarmed bool Whether the run was prewarmed

Modal VM rollout payload

The tasks-modal-vm-sandbox payload supports gradual rollout by origin product:

{
  "default_base_origin_products": ["user_created"],
  "origin_product_rollout_percentages": { "signals_scout": 10 },
  "default_custom_image": "posthog-dev-stack"
}

Each percentage uses a stable hash of the origin product and run ID. The same run keeps its runtime choice across activity retries.

Agent server readiness retry metric

posthog_tasks_process_agent_server_readiness_retry_total counts readiness retries that re-enter the start path in the existing sandbox. The start path keeps a process that became healthy between attempts and replaces one that remains unready.

Label Description
attempt Temporal activity attempt number
outcome succeeded or failed
boot_path Classic or overlapping clone boot
origin_product Product that created the task
runtime Sandbox runtime, currently gvisor or vm

task_run_cancelled

Tracked when the workflow is cancelled via CancelledError.

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
repository str Repository in org/repo format
team_id int Team ID

task_run_failed (workflow, metrics only)

Recorded when the workflow fails with an exception — not captured as an analytics event (the update_task_run_status activity owns the analytics capture on the DB transition, see above). The workflow emission feeds the posthog_tasks_task_run_failed_total Prometheus counter and structured logging with these properties:

Property Type Description
run_id str UUID of the run
task_id str UUID of the task
error_type str Exception class name
error_message str Error message (truncated to last 500 chars)
sandbox_id str Sandbox identifier (if available)

Webhook Events

Source: products/tasks/backend/webhooks.py

These events use TaskRun.capture_event() so include all TaskRun standard properties.

pr_created

Tracked when a GitHub pull_request.opened webhook is received. Additional properties:

Property Type Description
pr_url str GitHub PR URL
pr_title str PR title
pr_body str PR description, capped at 10,000 characters
pr_body_truncated bool Whether the cap removed part of the description
pr_labels list[str] Label names on the PR
pr_requested_reviewers list[str] GitHub logins of the requested reviewers
pr_is_draft bool Whether the PR is a draft

The pr_title, pr_body, pr_labels, pr_requested_reviewers, and pr_is_draft properties carry a value only on task-authored PRs. An external PR's own words are customer business context, so those events get the same keys as null.

pr_merged

Tracked when a GitHub pull_request.closed webhook is received with merged=true. Same additional properties as pr_created.

pr_closed

Tracked when a GitHub pull_request.closed webhook is received with merged=false. Same additional properties as pr_created.

Activity Observability Events

Source: products/tasks/backend/temporal/observability.py

These events are tracked via log_activity_execution() context manager and are enriched with Temporal context properties. Groups can be passed through to track_event().

process_task_activity_started

Property Type Description
activity_name str Name of the activity
...context Any Additional context kwargs passed to log_activity_execution()

process_task_activity_completed

Same properties as process_task_activity_started.

process_task_activity_failed

Property Type Description
activity_name str Name of the activity
error_type str Exception class name
error_message str Error message (truncated to 500 chars)
...context Any Additional context kwargs passed to log_activity_execution()

Temporal Context Enrichment

Events tracked from Temporal activities or workflows are automatically enriched with context properties by track_event() in observability.py:

When in an activity:

Property Type
temporal_activity_id str
temporal_activity_type str
temporal_workflow_id str
temporal_workflow_run_id str
temporal_attempt int

When in a workflow (non-replay):

Property Type
temporal_workflow_id str
temporal_workflow_run_id str
temporal_workflow_type str