Improve anonymous OSS telemetry (#823)

Author: santoshkumarradha

README.md

@@ -510,6 +510,8 @@ The control plane is a stateless Go service. Agents connect from anywhere - your
 
 ## Learn More
 
+AgentField sends privacy-minimized installation and lifecycle telemetry by default; no prompts or execution payloads are sent. Set `AGENTFIELD_TELEMETRY_ENABLED=false` to disable it. [Telemetry details](docs/ENVIRONMENT_VARIABLES.md#anonymous-telemetry).
+
 The thinking behind AgentField - essays on AI backends, harness orchestration, and the infrastructure production agents actually need.
 
 <table>

control-plane/cmd/af/main.go

@@ -59,6 +59,7 @@ func runServer(cmd *cobra.Command, args []string) {
 	if err != nil {
 		logger.Logger.Fatal().Err(err).Msg("Failed to load configuration")
 	}
+	cfg.Telemetry.AgentFieldVersion = version
 
 	// Override port from flag if provided
 	if cmd.Flags().Lookup("port").Changed {

control-plane/cmd/agentfield-server/main.go

@@ -73,6 +73,7 @@ func runServer(cmd *cobra.Command, args []string) {
 	if err != nil {
 		log.Fatalf("Failed to load configuration: %v", err)
 	}
+	cfg.Telemetry.AgentFieldVersion = version
 
 	// Re-initialize logger with configured level now that config is loaded.
 	// The CLI root command sets a default (info/debug based on --verbose),

control-plane/cmd/agentfield-server/main_test.go

@@ -302,6 +302,9 @@ func TestRunServer_AppliesFlagOverrides(t *testing.T) {
 	if gotCfg.AgentField.Port != 12345 {
 		t.Fatalf("expected env override port 12345, got %d", gotCfg.AgentField.Port)
 	}
+	if gotCfg.Telemetry.AgentFieldVersion != version {
+		t.Fatalf("expected telemetry build version %q, got %q", version, gotCfg.Telemetry.AgentFieldVersion)
+	}
 	if gotCfg.UI.Enabled {
 		t.Fatal("backend-only flag should disable UI")
 	}

control-plane/config/agentfield.yaml

@@ -50,6 +50,8 @@ type TelemetryConfig struct {
 	InstallIDPath string        `yaml:"install_id_path" mapstructure:"install_id_path"`
 	InstallID     string        `yaml:"install_id" mapstructure:"install_id"`
 	Timeout       time.Duration `yaml:"timeout" mapstructure:"timeout"`
+	// AgentFieldVersion is runtime build metadata and is never read from config.
+	AgentFieldVersion string `yaml:"-" mapstructure:"-"`
 }
 
 // IsEnabled returns true unless telemetry was explicitly disabled.

control-plane/internal/config/config.go

@@ -188,6 +188,9 @@ func TestTelemetryConfigDefaultsAndEnvOverrides(t *testing.T) {
 	if cfg.Telemetry.Timeout != 800*time.Millisecond {
 		t.Fatalf("unexpected timeout %s", cfg.Telemetry.Timeout)
 	}
+	if cfg.Telemetry.InstallIDPath != "" {
+		t.Fatalf("default install ID path must resolve under AgentField home, got %q", cfg.Telemetry.InstallIDPath)
+	}
 
 	t.Setenv("AGENTFIELD_TELEMETRY_ENABLED", "false")
 	t.Setenv("AGENTFIELD_TELEMETRY_ENDPOINT", "https://example.test/telemetry")

control-plane/internal/config/config_additional_test.go

@@ -262,6 +262,7 @@ func (c *executionController) handleSync(ctx *gin.Context) {
 		writeExecutionError(ctx, err)
 		return
 	}
+	plan.executionMode = "sync"
 
 	if plan.replayHit != nil {
 		if err := c.completeReplayHit(reqCtx, plan); err != nil {
@@ -692,6 +693,7 @@ func (c *executionController) handleAsync(ctx *gin.Context) {
 		writeExecutionError(ctx, err)
 		return
 	}
+	plan.executionMode = "async"
 
 	if plan.replayHit != nil {
 		if err := c.completeReplayHit(reqCtx, plan); err != nil {
@@ -984,8 +986,9 @@ func (c *executionController) handleStatusUpdate(ctx *gin.Context) {
 	}
 
 	eventData := map[string]interface{}{
-		"error":    req.Error,
-		"progress": req.Progress,
+		"error":             req.Error,
+		"progress":          req.Progress,
+		"transition_source": "status_callback",
 	}
 	if req.StatusReason != nil && strings.TrimSpace(*req.StatusReason) != "" {
 		eventData["status_reason"] = strings.TrimSpace(*req.StatusReason)
@@ -1053,6 +1056,65 @@ func (c *executionController) publishExecutionEvent(exec *types.Execution, statu
 	c.publishExecutionEventWithReasonerInfo(exec, status, data, nil, nil)
 }
 
+// enrichExecutionLifecycleData adds low-cardinality lifecycle dimensions used by
+// observability consumers. It does not mutate execution state or include payloads.
+func enrichExecutionLifecycleData(data map[string]interface{}, exec *types.Execution, status string) {
+	if data == nil || exec == nil {
+		return
+	}
+
+	data["is_root_execution"] = exec.ParentExecutionID == nil || strings.TrimSpace(*exec.ParentExecutionID) == ""
+	if _, ok := data["workflow_depth"]; !ok {
+		if data["is_root_execution"] == true {
+			data["workflow_depth"] = 0
+		}
+	}
+	if exec.DurationMS != nil {
+		data["duration_ms"] = *exec.DurationMS
+	}
+
+	switch status {
+	case string(types.ExecutionStatusSucceeded):
+		data["outcome"] = "succeeded"
+	case string(types.ExecutionStatusFailed):
+		data["outcome"] = "failed"
+		data["failure_category"] = canonicalFailureCategory(exec.StatusReason, "unknown")
+	case string(types.ExecutionStatusCancelled):
+		data["outcome"] = "cancelled"
+		data["failure_category"] = "cancelled"
+	case string(types.ExecutionStatusTimeout):
+		data["outcome"] = "timeout"
+		data["failure_category"] = "timeout"
+	}
+}
+
+func canonicalFailureCategory(statusReason *string, fallback string) string {
+	if statusReason == nil {
+		return fallback
+	}
+	category := strings.TrimSpace(*statusReason)
+	if separator := strings.Index(category, ":"); separator >= 0 {
+		category = strings.TrimSpace(category[:separator])
+	}
+	switch category {
+	case string(ErrorCategoryLLMUnavailable),
+		string(ErrorCategoryConcurrencyLimit),
+		string(ErrorCategoryAgentTimeout),
+		string(ErrorCategoryAgentError),
+		string(ErrorCategoryAgentUnreachable),
+		string(ErrorCategoryBadResponse),
+		string(ErrorCategoryInternal),
+		"agent_restart_orphaned",
+		"validation",
+		"permission_denied",
+		"node_unavailable",
+		"target_not_found":
+		return category
+	default:
+		return fallback
+	}
+}
+
 func (c *executionController) publishExecutionEventWithReasonerInfo(exec *types.Execution, status string, data map[string]interface{}, agent *types.AgentNode, reasonerID *string) {
 	if exec == nil {
 		return
@@ -1074,6 +1136,7 @@ func (c *executionController) publishExecutionEventWithReasonerInfo(exec *types.
 	if data == nil {
 		data = make(map[string]interface{})
 	}
+	enrichExecutionLifecycleData(data, exec, status)
 
 	// Add reasoner_id to the event data
 	rID := exec.ReasonerID
@@ -1114,6 +1177,7 @@ func (c *executionController) publishExecutionEventWithReasonerInfo(exec *types.
 	}
 	if workflowExec, err := c.store.GetWorkflowExecution(context.Background(), exec.ExecutionID); err == nil && workflowExec != nil {
 		data["retry_count"] = workflowExec.RetryCount
+		data["workflow_depth"] = workflowExec.WorkflowDepth
 	}
 
 	// Add reasoner definitions if agent info is available
@@ -1200,7 +1264,9 @@ func (c *executionController) publishExecutionStartedEvent(plan *preparedExecuti
 	}
 
 	data := map[string]interface{}{
-		"target_type": plan.targetType,
+		"target_type":       plan.targetType,
+		"execution_mode":    plan.executionMode,
+		"transition_source": "execution_controller",
 	}
 
 	// Include input payload info (not the full payload, just metadata)
@@ -1362,6 +1428,7 @@ type preparedExecution struct {
 	agent             *types.AgentNode
 	target            *parsedTarget
 	targetType        string
+	executionMode     string
 	llmEndpoint       string
 	webhookRegistered bool
 	webhookError      *string
@@ -1723,6 +1790,9 @@ func (c *executionController) completeReplayHit(ctx context.Context, plan *prepa
 	}
 
 	eventData := map[string]interface{}{
+		"target_type":       plan.targetType,
+		"execution_mode":    plan.executionMode,
+		"transition_source": "replay",
 		"replay": map[string]interface{}{
 			"source_execution_id": plan.replayHit.SourceExecutionID,
 			"source_run_id":       plan.replayHit.SourceRunID,
@@ -1905,7 +1975,11 @@ func (c *executionController) completeExecution(ctx context.Context, plan *prepa
 			if plan.webhookRegistered || (updated != nil && updated.WebhookRegistered) {
 				c.triggerWebhook(plan.exec.ExecutionID)
 			}
-			eventData := map[string]interface{}{}
+			eventData := map[string]interface{}{
+				"target_type":       plan.targetType,
+				"execution_mode":    plan.executionMode,
+				"transition_source": "execution_controller",
+			}
 			if !c.redactPayloads {
 				if payload := decodeJSON(result); payload != nil {
 					eventData["result"] = payload
@@ -1990,7 +2064,11 @@ func (c *executionController) failExecution(ctx context.Context, plan *preparedE
 				c.triggerWebhook(plan.exec.ExecutionID)
 			}
 			eventData := map[string]interface{}{
-				"error": errMsg,
+				"error":             errMsg,
+				"target_type":       plan.targetType,
+				"execution_mode":    plan.executionMode,
+				"failure_category":  string(category),
+				"transition_source": "execution_controller",
 			}
 			if !c.redactPayloads {
 				if payload := decodeJSON(result); payload != nil {

control-plane/internal/handlers/execute.go

@@ -115,7 +115,15 @@ func CancelExecutionHandler(store ExecutionStore) gin.HandlerFunc {
 			}
 		}
 
-		events.PublishExecutionCancelled(executionID, exec.RunID, exec.AgentNodeID, map[string]interface{}{"reason": reason})
+		eventData := map[string]interface{}{
+			"reason":            reason,
+			"transition_source": "cancel_api",
+		}
+		enrichExecutionLifecycleData(eventData, exec, string(types.ExecutionStatusCancelled))
+		if wfExec != nil {
+			eventData["workflow_depth"] = wfExec.WorkflowDepth
+		}
+		events.PublishExecutionCancelled(executionID, exec.RunID, exec.AgentNodeID, eventData)
 
 		payload, marshalErr := json.Marshal(map[string]interface{}{
 			"reason": reason,

control-plane/internal/handlers/execute_cancel.go

@@ -212,10 +212,16 @@ func cancelOneExecution(
 		}
 	}
 
-	events.PublishExecutionCancelled(updated.ExecutionID, updated.RunID, updated.AgentNodeID, map[string]interface{}{
-		"reason": reasonRaw,
-		"source": "cancel_tree",
-	})
+	eventData := map[string]interface{}{
+		"reason":            reasonRaw,
+		"source":            "cancel_tree",
+		"transition_source": "cancel_tree",
+	}
+	enrichExecutionLifecycleData(eventData, updated, string(types.ExecutionStatusCancelled))
+	if wfExec != nil {
+		eventData["workflow_depth"] = wfExec.WorkflowDepth
+	}
+	events.PublishExecutionCancelled(updated.ExecutionID, updated.RunID, updated.AgentNodeID, eventData)
 
 	payload, marshalErr := json.Marshal(map[string]interface{}{
 		"reason": reasonRaw,