The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix: align telemetry client payload and dimensions with backend schema
dotta53dbcd185eed
diff --git a/cli/src/commands/onboard.ts b/cli/src/commands/onboard.tsindex cd7b6fe88b..c6bc08c899 100644--- a/cli/src/commands/onboard.ts+++ b/cli/src/commands/onboard.ts@@ -359,7 +359,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {}const tc = getTelemetryClient();- if (tc) trackInstallStarted(tc, { setupMode });+ if (tc) trackInstallStarted(tc);let llm: PaperclipConfig["llm"] | undefined;const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv();@@ -510,9 +510,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {writeConfig(config, opts.config);if (tc) trackInstallCompleted(tc, {- setupMode,- dbMode: database.mode,- deploymentMode: server.deploymentMode,+ adapterType: server.deploymentMode,});p.note(diff --git a/packages/shared/src/telemetry/client.ts b/packages/shared/src/telemetry/client.tsindex e4503c4fde..939a32ed05 100644--- a/packages/shared/src/telemetry/client.ts+++ b/packages/shared/src/telemetry/client.ts@@ -1,8 +1,7 @@-import os from "node:os";import { createHash } from "node:crypto";import type {TelemetryConfig,- TelemetryEventEnvelope,+ TelemetryEvent,TelemetryEventName,TelemetryState,} from "./types.js";@@ -12,11 +11,10 @@ const BATCH_SIZE = 50;const SEND_TIMEOUT_MS = 5_000;export class TelemetryClient {- private queue: TelemetryEventEnvelope[] = [];+ private queue: TelemetryEvent[] = [];private readonly config: TelemetryConfig;private readonly stateFactory: () => TelemetryState;private readonly version: string;- private readonly sessionId: string;private state: TelemetryState | null = null;private flushInterval: ReturnType<typeof setInterval> | null = null;@@ -24,22 +22,16 @@ export class TelemetryClient {this.config = config;this.stateFactory = stateFactory;this.version = version;- this.sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;}track(eventName: TelemetryEventName, dimensions?: Record<string, string | number | boolean>): void {if (!this.config.enabled) return;- const state = this.getState();+ this.getState(); // ensure state is initialised (side-effect: creates state file on first call)this.queue.push({- installId: state.installId,- sessionId: this.sessionId,- event: eventName,+ name: eventName,+ occurredAt: new Date().toISOString(),dimensions: dimensions ?? {},- timestamp: new Date().toISOString(),- version: this.version,- os: os.platform(),- arch: os.arch(),});if (this.queue.length >= BATCH_SIZE) {@@ -51,7 +43,10 @@ export class TelemetryClient {if (!this.config.enabled || this.queue.length === 0) return;const events = this.queue.splice(0);+ const state = this.getState();const endpoint = this.config.endpoint ?? DEFAULT_ENDPOINT;+ const app = this.config.app ?? "paperclip";+ const schemaVersion = this.config.schemaVersion ?? "1";const controller = new AbortController();const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);@@ -59,7 +54,12 @@ export class TelemetryClient {await fetch(endpoint, {method: "POST",headers: { "Content-Type": "application/json" },- body: JSON.stringify({ events }),+ body: JSON.stringify({+ app,+ schemaVersion,+ installId: state.installId,+ events,+ }),signal: controller.signal,});} catch {diff --git a/packages/shared/src/telemetry/events.ts b/packages/shared/src/telemetry/events.tsindex f44f7908a5..1ed96bb6a6 100644--- a/packages/shared/src/telemetry/events.ts+++ b/packages/shared/src/telemetry/events.ts@@ -1,14 +1,14 @@import type { TelemetryClient } from "./client.js";-export function trackInstallStarted(client: TelemetryClient, dims: { setupMode: string }): void {- client.track("install.started", dims);+export function trackInstallStarted(client: TelemetryClient): void {+ client.track("install.started");}export function trackInstallCompleted(client: TelemetryClient,- dims: { setupMode: string; dbMode: string; deploymentMode: string },+ dims: { adapterType: string },): void {- client.track("install.completed", dims);+ client.track("install.completed", { adapter_type: dims.adapterType });}export function trackCompanyImported(@@ -17,33 +17,29 @@ export function trackCompanyImported(): void {const ref = dims.isPrivate ? client.hashPrivateRef(dims.sourceRef) : dims.sourceRef;client.track("company.imported", {- sourceType: dims.sourceType,- sourceRef: ref,- sourceRefHashed: dims.isPrivate,+ source_type: dims.sourceType,+ source_ref: ref,+ source_ref_hashed: dims.isPrivate,});}export function trackAgentFirstHeartbeat(client: TelemetryClient,- dims: { adapterType: string },+ dims: { agentRole: string },): void {- client.track("agent.first_heartbeat", dims);+ client.track("agent.first_heartbeat", { agent_role: dims.agentRole });}export function trackAgentTaskCompleted(client: TelemetryClient,- dims: { adapterType: string },+ dims: { agentRole: string },): void {- client.track("agent.task_completed", dims);+ client.track("agent.task_completed", { agent_role: dims.agentRole });}export function trackErrorHandlerCrash(client: TelemetryClient,- dims: { errorName: string; route: string; method: string },+ dims: { errorCode: string },): void {- client.track("error.handler_crash", {- errorName: dims.errorName,- route: dims.route,- method: dims.method,- });+ client.track("error.handler_crash", { error_code: dims.errorCode });}diff --git a/packages/shared/src/telemetry/index.ts b/packages/shared/src/telemetry/index.tsindex 520a56af90..1757276ec4 100644--- a/packages/shared/src/telemetry/index.ts+++ b/packages/shared/src/telemetry/index.ts@@ -12,6 +12,7 @@ export {export type {TelemetryConfig,TelemetryState,+ TelemetryEvent,TelemetryEventEnvelope,TelemetryEventName,} from "./types.js";diff --git a/packages/shared/src/telemetry/types.ts b/packages/shared/src/telemetry/types.tsindex f5df091495..cb0fed735f 100644--- a/packages/shared/src/telemetry/types.ts+++ b/packages/shared/src/telemetry/types.ts@@ -8,17 +8,23 @@ export interface TelemetryState {export interface TelemetryConfig {enabled: boolean;endpoint?: string;+ app?: string;+ schemaVersion?: string;}+/** Per-event object inside the backend envelope */+export interface TelemetryEvent {+ name: string;+ occurredAt: string;+ dimensions: Record<string, string | number | boolean>;+}++/** Full payload sent to the backend ingest endpoint */export interface TelemetryEventEnvelope {+ app: string;+ schemaVersion: string;installId: string;- sessionId: string;- event: string;- dimensions: Record<string, string | number | boolean>;- timestamp: string;- version: string;- os: string;- arch: string;+ events: TelemetryEvent[];}export type TelemetryEventName =diff --git a/server/src/__tests__/issue-telemetry-routes.test.ts b/server/src/__tests__/issue-telemetry-routes.test.tsindex 9e6b5fb6dd..ff51f722de 100644--- a/server/src/__tests__/issue-telemetry-routes.test.ts+++ b/server/src/__tests__/issue-telemetry-routes.test.ts@@ -100,7 +100,7 @@ describe("issue telemetry routes", () => {expect(res.status).toBe(200);expect(mockTrackAgentTaskCompleted).toHaveBeenCalledWith(expect.anything(), {- adapterType: "codex_local",+ agentRole: "codex_local",});});diff --git a/server/src/middleware/error-handler.ts b/server/src/middleware/error-handler.tsindex d68789ef31..032b5e1f19 100644--- a/server/src/middleware/error-handler.ts+++ b/server/src/middleware/error-handler.ts@@ -47,7 +47,7 @@ export function errorHandler(err,);const tc = getTelemetryClient();- if (tc) trackErrorHandlerCrash(tc, { errorName: err.name, route: req.route?.path ?? req.path, method: req.method });+ if (tc) trackErrorHandlerCrash(tc, { errorCode: err.name });}res.status(err.status).json({error: err.message,@@ -72,7 +72,7 @@ export function errorHandler();const tc = getTelemetryClient();- if (tc) trackErrorHandlerCrash(tc, { errorName: rootError.name, route: req.route?.path ?? req.path, method: req.method });+ if (tc) trackErrorHandlerCrash(tc, { errorCode: rootError.name });res.status(500).json({ error: "Internal server error" });}diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex 7c031c8b13..e815f8aec3 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -1184,7 +1184,7 @@ export function issueRoutes(db: Db, storage: StorageService) {if (tc && actor.agentId) {const actorAgent = await agentsSvc.getById(actor.agentId);if (actorAgent) {- trackAgentTaskCompleted(tc, { adapterType: actorAgent.adapterType });+ trackAgentTaskCompleted(tc, { agentRole: actorAgent.adapterType });}}}diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex e64c216c9f..507bf66396 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -1832,7 +1832,7 @@ export function heartbeatService(db: Db) {if (isFirstHeartbeat && updated) {const tc = getTelemetryClient();- if (tc) trackAgentFirstHeartbeat(tc, { adapterType: updated.adapterType });+ if (tc) trackAgentFirstHeartbeat(tc, { agentRole: updated.adapterType });}if (updated) {