: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.
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 |