mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
feat(telemetry): send Cloud server telemetry directly to PostHog (#22006)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The server sends first-party telemetry events through a collector. The collector anonymizes the events and copies them into PostHog. > - Paperclip Cloud is our own service. It needs real IDs (workspace, user, agent, task) so that a person can go from a PostHog event to the exact workspace and task. > - The collector path hashes these IDs. It also cannot link a server event to the browser session that caused it. > - This pull request adds a server-owned direct sender for Cloud only. Self-hosted installs keep the collector path with no change. > - The benefit is real IDs and session links on Cloud, and no change to self-hosted privacy. ## Linked Issues or Issue Description **Subsystem affected** Server telemetry (`packages/shared/src/telemetry`, `server/src/telemetry.ts`). **Problem or motivation** All Cloud telemetry goes through the collector. The collector hashes the install ID, agent IDs and task IDs. So, on Cloud, you cannot find the workspace, user or task of an event. Server events also cannot show in a browser session replay. **Proposed solution** On a Cloud-managed server that has `PAPERCLIP_POSTHOG_PROJECT_TOKEN`, `PAPERCLIP_CLOUD_STACK_ID` and `PAPERCLIP_POSTHOG_ENVIRONMENT`, send each telemetry batch straight to PostHog with `posthog-node`. Use the same event shape that the telemetry backend loader makes today, and add the real IDs. Keep every other install on the collector. **Alternatives considered** Send real IDs through the collector. We did not do this, because the collector exists to anonymize self-hosted data. **Roadmap alignment** This is Cloud analytics infrastructure. It does not change a core product feature. ## What Changed - Add `server/src/services/cloud-posthog-config.ts`. `resolveCloudPostHogConfig()` returns `null` unless the instance is Cloud-managed and has a token and a stack ID. `isPostHogDirectDeliveryEnabled()` also requires an environment and the kill switch on (`PAPERCLIP_POSTHOG_DIRECT` is not `0`). - Add a narrow `TelemetryTransport` seam to `TelemetryClient` in `packages/shared`. With a transport, each flushed batch goes to the transport and never to the collector. Without one, the client does what it did before. A transport can capture per-event context at track time. The context does not go into the collector envelope. - Typed helpers hash `task_id` unless the transport sets `hashesPrivateRefs: false`. Private `source_ref` values (for example a private repository name) are customer content, so they stay hashed on every path, Cloud included, with `source_ref_hashed: true`. - Add `server/src/services/posthog-direct/`: - `event-shape.ts` builds PostHog messages with the loader's event names, metadata keys and key order, the deterministic event uuid formula, and the unknown-enum fallback. It drops events that the backend quarantines (unregistered names). - `enum-fallbacks.generated.ts` holds the backend fallback rules. Enum values come from the shared generated contract. - `transport.ts` loads `posthog-node` with dynamic `import()` only on the first Cloud send. - `request-context.ts` is Cloud-only Express middleware. It reads only `X-POSTHOG-SESSION-ID` and `X-POSTHOG-WINDOW-ID`. It ignores `X-POSTHOG-DISTINCT-ID`. The acting user comes only from the authenticated request actor. Context stops when the response finishes, so later background work does not use that user. - `server/src/telemetry.ts` selects exactly one sender per process. On start, the Cloud sender sends `$groupidentify` (group `workspace`, key = stack ID) and one `cloud.workspace_started` event with `install_hash` (sha256 of the raw install ID). Both go straight to `posthog-node` and are not in `PAPERCLIP_EVENTS`. - `distinct_id` is the acting user ID, else `workspace:<stackId>`. Events without an acting user keep `$process_person_profile: false`. GeoIP stays off on all server events. - Shutdown flushes the client and then shuts down `posthog-node`. - Add `scripts/generate-posthog-direct-fixtures.mjs`. It runs the telemetry backend's own ingest and loader on one envelope and writes the golden fixture and the fallback table. The script header tells how to regenerate them. - Update `packages/shared/src/telemetry/README.md` with a "Cloud Direct Delivery" section about the privacy boundary. - Add `posthog-node@5.38.2` to `server/package.json`. This PR does not change `pnpm-lock.yaml`, because the lockfile refresh workflow owns it. Intended differences from the loader output on Cloud: `distinct_id` (user or workspace, not the HMAC install ID), raw `agent_id`, raw `task_id` (private `source_ref` stays hashed), and these added properties: `stack_id`, `company_id` and `user_id` when known, `environment`, `$groups`, `$session_id` and `$window_id`. The uuid formula is the same. The uuid is different only when the dimensions are different (raw `task_id`). ## Verification - `pnpm verify` returned exit 2 (a global CI input changed: the new script). I ran focused checks. Required CI supplies the broad coverage. - Focused tests pass: `packages/shared` `src/telemetry` (6 files, 42 tests). Server: `posthog-direct-telemetry`, `posthog-direct-event-shape`, `cloud-posthog-config`, `shared-telemetry-events`, `heartbeat-status-preserving-telemetry`, `issue-thread-interactions-telemetry`, `native-run-finalizer-telemetry`, `agent-task-run-telemetry`, `error-handler` (9 files, 115 tests), and `server-startup-feedback-export` (133 tests). - `tsc --noEmit` passes for `packages/shared`, `server` and `cli`. - New tests: - Config matrix: not Cloud, no token, no stack ID, no environment, kill switch, browser and replay flags. - Self-hosted: `posthog-node` is never loaded, the collector gets the batch, and the envelope bytes are the same as before (with `task_id` hashed). Tracing headers are ignored. - Cloud: a private `source_ref` stays hashed and the raw repository name never reaches the sender. - Cloud: one batch goes only to PostHog. Real IDs, `$groups`, `environment` on every event. `cloud.workspace_started` reaches the PostHog sender with `install_hash`. No other event has `install_hash`. - Golden: our builder output equals the backend loader output, except the intended differences above. Key order is the same. - `distinct_id`: user, agent and anonymous requests. A spoofed `X-POSTHOG-DISTINCT-ID` never changes `distinct_id` or `user_id`. A bad session header is dropped. Work after the response ends does not keep the user (red without the response-end guard, green with it). - Kill switch and a missing environment both fall back to the collector. - Local run with a real server and a local capture server (no real PostHog project): - Cloud mode (authenticated, local Postgres, `PAPERCLIP_POSTHOG_HOST` set to the capture server): the capture server got `$groupidentify`, `cloud.workspace_started`, `server.started` and `goal.created` on `/batch/`. `goal.created` from a Cloud tenant user had `distinct_id` = that user, `user_id`, `company_id`, `$session_id`, `$window_id`, `$groups` and no `$process_person_profile`. The spoofed distinct ID header was not used. Nothing went to `/ingest`. `SIGTERM` ran the `telemetry_flush` step and sent the queued events. - Self-hosted mode (same token variables but no Cloud signal): the capture server got only `/ingest` with the normal envelope. Nothing went to `/batch/`. - Runtime dependency note: `posthog-node` loads with dynamic `import()` only on Cloud with direct delivery on. The load happens after startup, outside the boot path. The unit test mocks the package to count loads. The local run used the real package. ## Risks - Medium. This is a telemetry change, so a privacy review is requested. Self-hosted output does not change. The direct path is off unless all three Cloud variables are set, so a merge does nothing until fleet config sets them. - Cloud events with an acting user create PostHog person profiles keyed by the Paperclip user ID. This is intended under the Cloud terms. - The fallback table can drift if the backend adds a new normalization rule. A test fails when a rule does not match the shared enum contract. Enum values come from the shared contract, so new enum values do not drift. - `posthog-node` keeps network failures in its own queue and drops events that PostHog rejects. The client does not resend these, so events are not sent twice. - `pnpm-lock.yaml` is not in this PR. The lockfile refresh workflow adds `posthog-node` after merge. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude Code with tool use (shell, file edits, local server runs). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
35c4526887
commit
55b692d532
22 files changed
+2270
-23
No files matched your search
@@ -120,6 +120,47 @@ value with a salted hash of the per-installation secret.
|
||||
Use `trackAgentTaskRun()` to emit this event. The generated contract remains
|
||||
the authority for its exact dimensions and optionality.
|
||||
|
||||
## Cloud Direct Delivery
|
||||
|
||||
Self-hosted installs are unchanged. They post every batch to the collector,
|
||||
private references stay hashed by `hashPrivateRef()`, and the collector and
|
||||
its loader apply their anonymization. A self-hosted server never loads
|
||||
`posthog-node`.
|
||||
|
||||
A Paperclip Cloud stack can send telemetry straight to PostHog instead. The
|
||||
server turns this on only when the instance is Cloud-managed and
|
||||
`PAPERCLIP_POSTHOG_PROJECT_TOKEN`, `PAPERCLIP_CLOUD_STACK_ID`, and
|
||||
`PAPERCLIP_POSTHOG_ENVIRONMENT` are set.
|
||||
`PAPERCLIP_POSTHOG_DIRECT=0` sends through the collector again. The server owns
|
||||
this transport (`server/src/services/posthog-direct/`). This package only
|
||||
exposes the `TelemetryTransport` seam on `TelemetryClient`:
|
||||
|
||||
- With a transport, each flushed batch goes to the transport and never to the
|
||||
collector. One batch has exactly one sender.
|
||||
- A transport with `hashesPrivateRefs: false` makes the typed helpers emit raw
|
||||
task ids. Private source refs (for example a private repository name) are
|
||||
customer content, not identifiers, so they stay hashed on every path and
|
||||
`source_ref_hashed` stays `true` for them.
|
||||
- The transport can capture per-event context at track time. That context is
|
||||
never added to the collector envelope.
|
||||
|
||||
Cloud is Paperclip's own service under the Cloud terms, so its events carry
|
||||
real identifiers: raw agent and task ids, the stack id, and the company and
|
||||
acting user ids when known. Event names, dimension names, metadata keys, the
|
||||
deterministic event uuid, and enum fallback normalization stay the same as the
|
||||
collector path, so existing insights keep working. Request headers from the
|
||||
browser SDK only link an event to a browser session. They never set identity
|
||||
or grant access. Do not use this path to send fields that are not in the
|
||||
generated contract.
|
||||
|
||||
On each start, a Cloud server with direct delivery also sends one
|
||||
`cloud.workspace_started` event and a workspace `$groupidentify`, straight
|
||||
through the PostHog client. Neither is in the generated contract, and neither
|
||||
goes through `TelemetryClient` or the collector. The event carries
|
||||
`install_hash`, the sha256 of the install id, which is the same value the
|
||||
collector stores as `install_id`. It lets an offline job join a workspace's
|
||||
pre-switch history. No other event carries `install_hash`.
|
||||
|
||||
### Other Data Paths
|
||||
|
||||
This document covers Paperclip Telemetry only. The generated Telemetry
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { TelemetryClient } from "./client.js";
|
||||
import { TelemetryClient, type TelemetryOutgoingBatch, type TelemetrySendResult, type TelemetryTransport } from "./client.js";
|
||||
import { trackAgentTaskRun, trackCompanyImported } from "./events.js";
|
||||
import { resolveTelemetryConfig } from "./config.js";
|
||||
import type { TelemetryConfig, TelemetryDimensions, TelemetryState } from "./types.js";
|
||||
|
||||
@@ -626,3 +627,96 @@ describe("TelemetryClient bounded pending-retry store", () => {
|
||||
client.stop();
|
||||
});
|
||||
});
|
||||
|
||||
describe("TelemetryClient transport seam", () => {
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
function makeTransport(overrides: Partial<TelemetryTransport> = {}) {
|
||||
const send = vi.fn(async (_batch: TelemetryOutgoingBatch): Promise<TelemetrySendResult> => ({ kind: "ok" }));
|
||||
const transport: TelemetryTransport = {
|
||||
hashesPrivateRefs: false,
|
||||
captureEventContext: vi.fn(() => ({ tag: "ctx" })),
|
||||
send,
|
||||
...overrides,
|
||||
};
|
||||
return { transport, send };
|
||||
}
|
||||
|
||||
it("keeps hashing private refs on the default collector path", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue({ ok: true });
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
const { client } = makeClient();
|
||||
expect(client.privateRefsHashed).toBe(true);
|
||||
|
||||
trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" });
|
||||
await client.flush();
|
||||
|
||||
const body = sentBody();
|
||||
expect(body.events[0].dimensions.task_id).toBe(client.hashPrivateRef("task-raw-id"));
|
||||
expect(body.events[0].dimensions.task_id).not.toBe("task-raw-id");
|
||||
expect(Object.keys(body).sort()).toEqual([...CONTRACT_KEYS].sort());
|
||||
});
|
||||
|
||||
it("sends each batch to the transport only, never to the collector", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue({ ok: true });
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
const { transport, send } = makeTransport();
|
||||
const client = new TelemetryClient(
|
||||
{ enabled: true, endpoint: "http://localhost:9999/ingest" },
|
||||
() => TEST_STATE,
|
||||
"0.0.0-test",
|
||||
() => 0.5,
|
||||
transport,
|
||||
);
|
||||
|
||||
trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" });
|
||||
trackCompanyImported(client, { sourceType: "github", sourceRef: "acme/private", isPrivate: true });
|
||||
await client.flush();
|
||||
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
expect(send).toHaveBeenCalledTimes(1);
|
||||
const batch = send.mock.calls[0]![0];
|
||||
expect(batch.installId).toBe("test-install");
|
||||
expect(batch.events.map(({ event }) => event.dimensions)).toEqual([
|
||||
{ agent_id: "agent-1", state: "succeeded", task_id: "task-raw-id" },
|
||||
// Private source refs are customer content and stay hashed on Cloud too.
|
||||
{ source_type: "github", source_ref: client.hashPrivateRef("acme/private"), source_ref_hashed: true },
|
||||
]);
|
||||
expect(batch.events.map(({ context }) => context)).toEqual([{ tag: "ctx" }, { tag: "ctx" }]);
|
||||
// The per-event context never leaks into the event object itself.
|
||||
expect(Object.keys(batch.events[0]!.event).sort()).toEqual(["dimensions", "name", "occurredAt"]);
|
||||
});
|
||||
|
||||
it("retries a transport batch with the same events instead of switching sender", async () => {
|
||||
vi.useFakeTimers();
|
||||
try {
|
||||
const fetchMock = vi.fn().mockResolvedValue({ ok: true });
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
vi.spyOn(console, "warn").mockImplementation(() => {});
|
||||
const send = vi
|
||||
.fn<(batch: TelemetryOutgoingBatch) => Promise<TelemetrySendResult>>()
|
||||
.mockResolvedValueOnce({ kind: "network" })
|
||||
.mockResolvedValue({ kind: "ok" });
|
||||
const client = new TelemetryClient(
|
||||
{ enabled: true },
|
||||
() => TEST_STATE,
|
||||
"0.0.0-test",
|
||||
() => 0.5,
|
||||
{ hashesPrivateRefs: false, send },
|
||||
);
|
||||
client.track("routine.created", {});
|
||||
await client.flush();
|
||||
await vi.advanceTimersByTimeAsync(2_000);
|
||||
|
||||
expect(send).toHaveBeenCalledTimes(2);
|
||||
expect(send.mock.calls[1]![0].batchId).toBe(send.mock.calls[0]![0].batchId);
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
client.stop();
|
||||
} finally {
|
||||
vi.useRealTimers();
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -74,6 +74,43 @@ const BATCH_ID_HEX_LENGTH = 32;
|
||||
* so it can be cancelled when the batch is evicted from the bounded store,
|
||||
* otherwise the timer would keep firing for a batch that no longer exists.
|
||||
*/
|
||||
/** Outcome of delivering one batch, as classified by the client's retry logic. */
|
||||
export type TelemetrySendResult =
|
||||
| { kind: "ok" }
|
||||
| { kind: "status"; status: number; retryAfterMs?: number }
|
||||
| { kind: "network" };
|
||||
|
||||
/**
|
||||
* One wire-ready batch handed to a custom transport. `events` pairs each event
|
||||
* with the opaque context the transport captured when the event was tracked.
|
||||
*/
|
||||
export interface TelemetryOutgoingBatch {
|
||||
app: string;
|
||||
schemaVersion: string;
|
||||
installId: string;
|
||||
version: string;
|
||||
batchId: string;
|
||||
events: ReadonlyArray<{ event: TelemetryEvent; context: unknown }>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Narrow seam for a host that delivers telemetry somewhere other than the
|
||||
* default collector. When a client has a transport, every flushed batch goes
|
||||
* to `send` and never to the collector endpoints, so each batch has exactly
|
||||
* one sender. Without a transport the client behaves exactly as before.
|
||||
*/
|
||||
export interface TelemetryTransport {
|
||||
/**
|
||||
* Whether typed helpers hash private task ids before emission. The default
|
||||
* collector path always hashes. Private source refs stay hashed on every
|
||||
* path, because they are customer content rather than identifiers.
|
||||
*/
|
||||
readonly hashesPrivateRefs: boolean;
|
||||
/** Captures per-event context at track time (for example the acting request). */
|
||||
captureEventContext?(): unknown;
|
||||
send(batch: TelemetryOutgoingBatch): Promise<TelemetrySendResult>;
|
||||
}
|
||||
|
||||
interface PendingBatch {
|
||||
events: TelemetryEvent[];
|
||||
batchId: string;
|
||||
@@ -95,6 +132,10 @@ export class TelemetryClient {
|
||||
// `maxPendingRetryBatches`. Insertion order == age (oldest at the front).
|
||||
private pending: PendingBatch[] = [];
|
||||
private readonly retryTimers = new Set<ReturnType<typeof setTimeout>>();
|
||||
private readonly transport: TelemetryTransport | null;
|
||||
// Per-event transport context, kept off the event object so the collector
|
||||
// envelope stays byte-identical whether or not a transport is configured.
|
||||
private readonly eventContexts = new WeakMap<TelemetryEvent, unknown>();
|
||||
|
||||
constructor(
|
||||
config: TelemetryConfig,
|
||||
@@ -103,12 +144,16 @@ export class TelemetryClient {
|
||||
// Injectable RNG for backoff jitter — defaults to `Math.random`; tests pass
|
||||
// a seeded function for deterministic backoff. Callers keep the 3-arg form.
|
||||
random: () => number = Math.random,
|
||||
// Optional custom delivery. Omitted on self-hosted installs, which keep the
|
||||
// default collector path unchanged.
|
||||
transport?: TelemetryTransport,
|
||||
) {
|
||||
this.config = config;
|
||||
this.caps = resolveCaps(config);
|
||||
this.stateFactory = stateFactory;
|
||||
this.version = version;
|
||||
this.random = random;
|
||||
this.transport = transport ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -144,11 +189,15 @@ export class TelemetryClient {
|
||||
if (!this.config.enabled) return;
|
||||
this.getState(); // ensure state is initialised (side-effect: creates state file on first call)
|
||||
|
||||
this.queue.push({
|
||||
const event: TelemetryEvent = {
|
||||
name: eventName,
|
||||
occurredAt: new Date().toISOString(),
|
||||
dimensions: { ...dimensions } as TelemetryDimensions,
|
||||
});
|
||||
};
|
||||
if (this.transport?.captureEventContext) {
|
||||
this.eventContexts.set(event, this.transport.captureEventContext());
|
||||
}
|
||||
this.queue.push(event);
|
||||
|
||||
if (this.queue.length >= BATCH_SIZE) {
|
||||
void this.flush();
|
||||
@@ -269,8 +318,7 @@ export class TelemetryClient {
|
||||
* terminal failure or after `maxAttempts` the batch is dropped-and-logged.
|
||||
*/
|
||||
private async attemptSend(batch: PendingBatch): Promise<void> {
|
||||
const body = JSON.stringify(this.buildEnvelope(batch.events, batch.batchId));
|
||||
const outcome = this.classifyOutcome(await this.postEnvelope(body));
|
||||
const outcome = this.classifyOutcome(await this.deliver(batch));
|
||||
|
||||
if (outcome.kind === "ok") return;
|
||||
|
||||
@@ -305,8 +353,26 @@ export class TelemetryClient {
|
||||
});
|
||||
}
|
||||
|
||||
/** Sends one batch through exactly one sender: the transport, or else the collector. */
|
||||
private async deliver(batch: PendingBatch): Promise<TelemetrySendResult> {
|
||||
const envelope = this.buildEnvelope(batch.events, batch.batchId);
|
||||
if (!this.transport) return this.postEnvelope(JSON.stringify(envelope));
|
||||
try {
|
||||
return await this.transport.send({
|
||||
app: envelope.app,
|
||||
schemaVersion: envelope.schemaVersion,
|
||||
installId: envelope.installId,
|
||||
version: envelope.version,
|
||||
batchId: envelope.batchId,
|
||||
events: batch.events.map((event) => ({ event, context: this.eventContexts.get(event) })),
|
||||
});
|
||||
} catch {
|
||||
return { kind: "network" };
|
||||
}
|
||||
}
|
||||
|
||||
private classifyOutcome(
|
||||
result: { kind: "ok" } | { kind: "status"; status: number; retryAfterMs?: number } | { kind: "network" },
|
||||
result: TelemetrySendResult,
|
||||
): { kind: "ok" } | { kind: "retry"; retryAfterMs?: number } | { kind: "terminal"; status: number } {
|
||||
if (result.kind === "ok") return { kind: "ok" };
|
||||
if (result.kind === "network") return { kind: "retry" };
|
||||
@@ -408,9 +474,7 @@ export class TelemetryClient {
|
||||
* surface the last transient status if every endpoint returns one — matching
|
||||
* the pre-retry loop's endpoint-fallback behavior.
|
||||
*/
|
||||
private async postEnvelope(
|
||||
body: string,
|
||||
): Promise<{ kind: "ok" } | { kind: "status"; status: number; retryAfterMs?: number } | { kind: "network" }> {
|
||||
private async postEnvelope(body: string): Promise<TelemetrySendResult> {
|
||||
const endpoints = this.resolveEndpoints();
|
||||
let lastTransient: { kind: "status"; status: number; retryAfterMs?: number } | undefined;
|
||||
for (const endpoint of endpoints) {
|
||||
@@ -481,6 +545,14 @@ export class TelemetryClient {
|
||||
.slice(0, 16);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether typed helpers hash private references on this client. Always true
|
||||
* on the default collector path; only a transport can turn it off.
|
||||
*/
|
||||
get privateRefsHashed(): boolean {
|
||||
return this.transport?.hashesPrivateRefs ?? true;
|
||||
}
|
||||
|
||||
private getState(): TelemetryState {
|
||||
if (!this.state) {
|
||||
this.state = this.stateFactory();
|
||||
|
||||
@@ -7,6 +7,15 @@ function asEventDimension<T extends string>(value: RawDimension<T>): T {
|
||||
return value as T;
|
||||
}
|
||||
|
||||
/**
|
||||
* Emitted form of a private task reference. The default collector path always
|
||||
* hashes it with `hashPrivateRef()`. Only a client whose transport declares
|
||||
* `hashesPrivateRefs: false` (Paperclip Cloud direct delivery) emits the raw id.
|
||||
*/
|
||||
function emitPrivateRef(client: TelemetryClient, value: string): string {
|
||||
return client.privateRefsHashed === false ? value : client.hashPrivateRef(value);
|
||||
}
|
||||
|
||||
export function trackInstallStarted(client: TelemetryClient): void {
|
||||
client.track("install.started", {});
|
||||
}
|
||||
@@ -28,6 +37,8 @@ export function trackCompanyImported(
|
||||
isPrivate: boolean;
|
||||
},
|
||||
): void {
|
||||
// A private source ref is customer content (for example a private repository
|
||||
// name), not an identifier. It stays hashed on every path, Cloud included.
|
||||
const ref = dims.isPrivate ? client.hashPrivateRef(dims.sourceRef) : dims.sourceRef;
|
||||
client.track("company.imported", {
|
||||
source_type: asEventDimension(dims.sourceType),
|
||||
@@ -120,7 +131,7 @@ export function trackAgentTaskCompleted(
|
||||
agent_id: dims.agentId,
|
||||
adapter_type: asEventDimension(dims.adapterType),
|
||||
...(dims.model ? { model: dims.model } : {}),
|
||||
...(dims.taskId ? { task_id: client.hashPrivateRef(dims.taskId) } : {}),
|
||||
...(dims.taskId ? { task_id: emitPrivateRef(client, dims.taskId) } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -149,7 +160,7 @@ export function trackAgentTaskRun(
|
||||
...(dims.inputTokens === undefined ? {} : { input_tokens: dims.inputTokens }),
|
||||
...(dims.outputTokens === undefined ? {} : { output_tokens: dims.outputTokens }),
|
||||
...(dims.cachedTokens === undefined ? {} : { cached_tokens: dims.cachedTokens }),
|
||||
...(dims.taskId ? { task_id: client.hashPrivateRef(dims.taskId) } : {}),
|
||||
...(dims.taskId ? { task_id: emitPrivateRef(client, dims.taskId) } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
export { TelemetryClient } from "./client.js";
|
||||
export type { TelemetryOutgoingBatch, TelemetrySendResult, TelemetryTransport } from "./client.js";
|
||||
export { resolveTelemetryConfig, resolveCaps, TELEMETRY_DEFAULTS } from "./config.js";
|
||||
export type { TelemetryConfigOverrides } from "./config.js";
|
||||
export { loadOrCreateState } from "./state.js";
|
||||
@@ -40,5 +41,6 @@ export type {
|
||||
EventDimensionsMap,
|
||||
PaperclipEventName,
|
||||
} from "./generated/paperclip-telemetry.js";
|
||||
export { PAPERCLIP_EVENTS, PAPERCLIP_ENUM_DESCRIPTIONS } from "./generated/paperclip-telemetry.js";
|
||||
export { EVENT_RETENTION_CLASS, RETENTION_DAYS } from "./retention.js";
|
||||
export type { RetentionClass } from "./retention.js";
|
||||
@@ -0,0 +1,163 @@
|
||||
#!/usr/bin/env node
|
||||
// Regenerates the Paperclip Cloud direct PostHog delivery fixtures from a
|
||||
// checkout of the private telemetry-backend repository.
|
||||
//
|
||||
// Usage:
|
||||
// git -C <telemetry-backend> fetch origin
|
||||
// git -C <telemetry-backend> archive --format=tar --prefix=tb/ origin/HEAD | tar -x -C <tmp>
|
||||
// node scripts/generate-posthog-direct-fixtures.mjs <tmp>/tb
|
||||
//
|
||||
// It writes two files under server/src/services/posthog-direct/:
|
||||
// - enum-fallbacks.generated.ts: the backend's unknown-enum fallback rules
|
||||
// (`x-normalize.unknown_enum_value`). Enum domains come from the shared
|
||||
// generated contract, so only the fallback rule lives here.
|
||||
// - __fixtures__/loader-golden.json: one collector envelope, the canonical
|
||||
// records the backend ingest produces for it, and the PostHog capture
|
||||
// messages its loader builds from them. The golden test compares the
|
||||
// server's direct builder against these messages.
|
||||
//
|
||||
// The backend modules used here have no external dependencies, so a plain
|
||||
// source checkout is enough. No network or AWS access is needed: Firehose and
|
||||
// DynamoDB are replaced by in-memory test clients the backend already supports.
|
||||
|
||||
import { writeFile, mkdir } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { pathToFileURL, fileURLToPath } from "node:url";
|
||||
import { createRequire } from "node:module";
|
||||
|
||||
const backendDir = process.argv[2];
|
||||
if (!backendDir) {
|
||||
console.error("usage: node scripts/generate-posthog-direct-fixtures.mjs <telemetry-backend-dir>");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
||||
const outDir = path.join(repoRoot, "server/src/services/posthog-direct");
|
||||
const backendUrl = (rel) => pathToFileURL(path.join(path.resolve(backendDir), rel)).href;
|
||||
|
||||
const manifest = createRequire(import.meta.url)(path.join(path.resolve(backendDir), "src/registry/generated/manifest.json"));
|
||||
|
||||
// --- enum fallback table ---------------------------------------------------
|
||||
const fallbacks = {};
|
||||
for (const [eventName, spec] of Object.entries(manifest.events).sort(([a], [b]) => a.localeCompare(b))) {
|
||||
const required = new Set(spec.required ?? []);
|
||||
for (const [key, prop] of Object.entries(spec.properties ?? {})) {
|
||||
const fallback = prop?.["x-normalize"]?.unknown_enum_value;
|
||||
if (fallback === undefined) continue;
|
||||
(fallbacks[eventName] ??= {})[key] = { fallback, required: required.has(key) };
|
||||
}
|
||||
}
|
||||
const fallbackSource = `// GENERATED by scripts/generate-posthog-direct-fixtures.mjs from the telemetry
|
||||
// backend's event manifest (x-normalize.unknown_enum_value). DO NOT EDIT.
|
||||
// Enum domains come from PAPERCLIP_ENUM_DESCRIPTIONS in @paperclipai/shared.
|
||||
|
||||
export const UNKNOWN_ENUM_FALLBACKS = ${JSON.stringify(fallbacks, null, 2)} as const;
|
||||
`;
|
||||
await writeFile(path.join(outDir, "enum-fallbacks.generated.ts"), fallbackSource);
|
||||
|
||||
// --- golden loader output ----------------------------------------------------
|
||||
const { processV2Ingest, setV2IngestAwsClientsForTest } = await import(backendUrl("src/v2/ingest-core.mjs"));
|
||||
const { buildPostHogEvent } = await import(backendUrl("src/loader/sinks/posthog.mjs"));
|
||||
|
||||
const NOW = "2026-11-17T12:00:00.000Z";
|
||||
const HMAC_SECRET = "fixture-only-hmac-secret";
|
||||
const RAW_TASK_ID = "6f1f3c2a-9b8e-4d7c-a1b2-c3d4e5f60718";
|
||||
const HASHED_TASK_ID = "9c1e5b7a3d2f4e60"; // what hashPrivateRef emits on the collector path
|
||||
|
||||
const envelope = {
|
||||
app: "paperclip",
|
||||
schemaVersion: "1",
|
||||
installId: "11111111-2222-4333-8444-555555555555",
|
||||
version: "2026.1117.0",
|
||||
batchId: "fixture-batch-0001",
|
||||
events: [
|
||||
{ name: "server.started", occurredAt: "2026-11-17T11:58:00.000Z", dimensions: { os_platform: "linux" } },
|
||||
{
|
||||
name: "agent.task_run",
|
||||
occurredAt: "2026-11-17T11:58:01.000Z",
|
||||
dimensions: {
|
||||
agent_id: "2f6c7d1e-0a4b-4c3d-9e8f-112233445566",
|
||||
state: "succeeded",
|
||||
adapter_type: "claude_local",
|
||||
agent_role: "engineer",
|
||||
model: "claude-opus-5-5",
|
||||
duration_seconds: 42,
|
||||
input_tokens: 1200,
|
||||
output_tokens: 300,
|
||||
task_id: HASHED_TASK_ID,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "agent.created",
|
||||
occurredAt: "2026-11-17T11:58:02.000Z",
|
||||
dimensions: { agent_id: "3a7b8c9d-1e2f-4a5b-8c6d-778899aabbcc", agent_role: "astronaut" },
|
||||
},
|
||||
{
|
||||
name: "install.completed",
|
||||
occurredAt: "2026-11-17T11:58:03.000Z",
|
||||
dimensions: { adapter_type: "future_adapter" },
|
||||
},
|
||||
{
|
||||
name: "skill.imported",
|
||||
occurredAt: "2026-11-17T11:58:04.000Z",
|
||||
dimensions: { source_type: "mystery_source" },
|
||||
},
|
||||
{
|
||||
name: "interaction.resolved",
|
||||
occurredAt: "2026-11-17T11:58:05.000Z",
|
||||
dimensions: {
|
||||
interaction_kind: "suggest_tasks",
|
||||
status: "accepted",
|
||||
resolved_by_kind: "user",
|
||||
option_count: 3,
|
||||
selected_option_count: 2,
|
||||
legacy_inherited_restriction: false,
|
||||
},
|
||||
},
|
||||
{ name: "routine.created", occurredAt: "2026-11-17T11:58:06.000Z", dimensions: {} },
|
||||
{
|
||||
// Unregistered names are quarantined by the backend and never reach PostHog.
|
||||
name: "question_response.delivery",
|
||||
occurredAt: "2026-11-17T11:58:07.000Z",
|
||||
dimensions: { outcome: "delivered" },
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
const canonicalRecords = [];
|
||||
setV2IngestAwsClientsForTest({
|
||||
firehose: {
|
||||
async send(command) {
|
||||
for (const record of command.input.Records ?? []) {
|
||||
const parsed = JSON.parse(Buffer.from(record.Data).toString("utf-8"));
|
||||
if (command.input.DeliveryStreamName === "canonical") canonicalRecords.push(parsed);
|
||||
}
|
||||
return { FailedPutCount: 0, RequestResponses: [] };
|
||||
},
|
||||
},
|
||||
dynamoDb: { async send() { return {}; } },
|
||||
});
|
||||
process.env.V2_CANONICAL_FIREHOSE_STREAM_NAME = "canonical";
|
||||
process.env.V2_QUARANTINE_FIREHOSE_STREAM_NAME = "quarantine";
|
||||
process.env.V2_BATCH_LEDGER_TABLE_NAME = "ledger";
|
||||
delete process.env.AGENT_ID_HASH_SECRET;
|
||||
|
||||
const originalInfo = console.info;
|
||||
console.info = () => {}; // silence the backend's metric lines
|
||||
const response = await processV2Ingest(
|
||||
{ requestContext: { http: { method: "POST" } }, headers: {}, isBase64Encoded: false, body: JSON.stringify(envelope) },
|
||||
{ source: "client", route: "/v2/ingest", now: new Date(NOW), deploymentSource: "cloud" },
|
||||
);
|
||||
console.info = originalInfo;
|
||||
if (response.statusCode !== 202) {
|
||||
throw new Error(`backend ingest rejected the fixture envelope: ${response.statusCode} ${response.body}`);
|
||||
}
|
||||
|
||||
const loaderEvents = canonicalRecords.map((record) => buildPostHogEvent(record, { distinctIdHmacSecret: HMAC_SECRET }));
|
||||
|
||||
await mkdir(path.join(outDir, "__fixtures__"), { recursive: true });
|
||||
await writeFile(
|
||||
path.join(outDir, "__fixtures__/loader-golden.json"),
|
||||
`${JSON.stringify({ ingestedAt: NOW, rawTaskId: RAW_TASK_ID, hashedTaskId: HASHED_TASK_ID, envelope, canonicalRecords, loaderEvents }, null, 2)}\n`,
|
||||
);
|
||||
console.log(`wrote ${loaderEvents.length} loader events and ${Object.keys(fallbacks).length} fallback rule sets`);
|
||||
@@ -112,6 +112,7 @@
|
||||
"pino": "^10.0.0",
|
||||
"pino-http": "^11.0.0",
|
||||
"pino-pretty": "^13.1.3",
|
||||
"posthog-node": "5.38.2",
|
||||
"sharp": "^0.35.4",
|
||||
"smol-toml": "^1.9.1",
|
||||
"ssh2": "^1.17.0",
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "../services/cloud-posthog-config.js";
|
||||
|
||||
const CLOUD = {
|
||||
PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-token",
|
||||
PAPERCLIP_CLOUD_STACK_ID: "stack-123",
|
||||
PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test",
|
||||
};
|
||||
|
||||
describe("resolveCloudPostHogConfig", () => {
|
||||
it("is null on a self-hosted install, even with a PostHog token", () => {
|
||||
expect(resolveCloudPostHogConfig({})).toBeNull();
|
||||
expect(
|
||||
resolveCloudPostHogConfig({ PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test", PAPERCLIP_CLOUD_STACK_ID: "stack-123" }),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
it("is null on Cloud without a token or without a stack id", () => {
|
||||
expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_PROJECT_TOKEN: "" })).toBeNull();
|
||||
expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_PROJECT_TOKEN: " " })).toBeNull();
|
||||
expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_CLOUD_STACK_ID: undefined })).toBeNull();
|
||||
});
|
||||
|
||||
it("resolves defaults on a Cloud stack with a token", () => {
|
||||
expect(resolveCloudPostHogConfig(CLOUD)).toEqual({
|
||||
token: "phc_test",
|
||||
host: "https://us.i.posthog.com",
|
||||
environment: null,
|
||||
stackId: "stack-123",
|
||||
directEnabled: true,
|
||||
browserEnabled: false,
|
||||
replayEnabled: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts the legacy managed-config Cloud signal", () => {
|
||||
const { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: _omit, ...rest } = CLOUD;
|
||||
expect(resolveCloudPostHogConfig({ ...rest, PAPERCLIP_MANAGED_CONFIG: "{}" })?.stackId).toBe("stack-123");
|
||||
});
|
||||
|
||||
it("reads host, environment and the switches", () => {
|
||||
const config = resolveCloudPostHogConfig({
|
||||
...CLOUD,
|
||||
PAPERCLIP_POSTHOG_HOST: "http://127.0.0.1:9999/",
|
||||
PAPERCLIP_POSTHOG_ENVIRONMENT: "staging",
|
||||
PAPERCLIP_POSTHOG_DIRECT: "0",
|
||||
PAPERCLIP_POSTHOG_BROWSER_ENABLED: "1",
|
||||
});
|
||||
expect(config).toMatchObject({
|
||||
host: "http://127.0.0.1:9999",
|
||||
environment: "staging",
|
||||
directEnabled: false,
|
||||
browserEnabled: true,
|
||||
replayEnabled: true,
|
||||
});
|
||||
});
|
||||
|
||||
it("turns replay off with its own switch and never without the browser switch", () => {
|
||||
expect(
|
||||
resolveCloudPostHogConfig({
|
||||
...CLOUD,
|
||||
PAPERCLIP_POSTHOG_BROWSER_ENABLED: "1",
|
||||
PAPERCLIP_POSTHOG_REPLAY_ENABLED: "0",
|
||||
})?.replayEnabled,
|
||||
).toBe(false);
|
||||
expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_REPLAY_ENABLED: "1" })?.replayEnabled).toBe(false);
|
||||
});
|
||||
|
||||
it("turns direct delivery on only with the switch on and an environment", () => {
|
||||
expect(isPostHogDirectDeliveryEnabled(null)).toBe(false);
|
||||
expect(isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig(CLOUD))).toBe(false);
|
||||
expect(
|
||||
isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_ENVIRONMENT: "staging" })),
|
||||
).toBe(true);
|
||||
expect(
|
||||
isPostHogDirectDeliveryEnabled(
|
||||
resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_ENVIRONMENT: "staging", PAPERCLIP_POSTHOG_DIRECT: "0" }),
|
||||
),
|
||||
).toBe(false);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,109 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { PAPERCLIP_ENUM_DESCRIPTIONS, type TelemetryEvent } from "@paperclipai/shared/telemetry";
|
||||
import golden from "../services/posthog-direct/__fixtures__/loader-golden.json" with { type: "json" };
|
||||
import { UNKNOWN_ENUM_FALLBACKS } from "../services/posthog-direct/enum-fallbacks.generated.js";
|
||||
import {
|
||||
buildPostHogDirectEvent,
|
||||
resolveDistinctId,
|
||||
} from "../services/posthog-direct/event-shape.js";
|
||||
|
||||
// The golden fixture is produced by running the telemetry backend's own ingest
|
||||
// and loader on one collector envelope. Regenerate it with
|
||||
// `node scripts/generate-posthog-direct-fixtures.mjs <telemetry-backend-dir>`.
|
||||
|
||||
const config = { stackId: "stack-123", environment: "staging" };
|
||||
const meta = {
|
||||
app: golden.envelope.app,
|
||||
schemaVersion: golden.envelope.schemaVersion,
|
||||
installId: golden.envelope.installId,
|
||||
version: golden.envelope.version,
|
||||
ingestedAt: golden.ingestedAt,
|
||||
};
|
||||
|
||||
type LoaderEvent = (typeof golden.loaderEvents)[number];
|
||||
|
||||
// The Cloud direct path emits the raw task id where the collector path emits
|
||||
// its salted hash. Everything else in the event is the same input.
|
||||
function directInput(event: (typeof golden.envelope.events)[number]): TelemetryEvent {
|
||||
const dimensions = { ...event.dimensions } as Record<string, string | number | boolean>;
|
||||
if (dimensions.task_id === golden.hashedTaskId) dimensions.task_id = golden.rawTaskId;
|
||||
return { name: event.name, occurredAt: event.occurredAt, dimensions };
|
||||
}
|
||||
|
||||
describe("Cloud direct PostHog event shape", () => {
|
||||
const direct = golden.envelope.events.map((event) =>
|
||||
buildPostHogDirectEvent(directInput(event), undefined, meta, config),
|
||||
);
|
||||
const sent = direct.filter((event) => event !== null);
|
||||
|
||||
it("drops exactly the events the backend quarantines", () => {
|
||||
expect(sent.map((event) => event!.event)).toEqual(golden.loaderEvents.map((event) => event.event));
|
||||
expect(direct.find((_, i) => golden.envelope.events[i]!.name === "question_response.delivery")).toBeNull();
|
||||
});
|
||||
|
||||
it("matches the loader output except for the intended Cloud differences", () => {
|
||||
golden.loaderEvents.forEach((loader: LoaderEvent, index) => {
|
||||
const ours = sent[index]!;
|
||||
const inputDims = golden.envelope.events.find((e) => e.name === loader.event)!.dimensions as Record<string, unknown>;
|
||||
const hasPrivateRef = "task_id" in inputDims;
|
||||
|
||||
// Same envelope-level fields; uuid differs only when the dimensions do.
|
||||
expect(ours.event).toBe(loader.event);
|
||||
expect(ours.timestamp).toBe(loader.timestamp);
|
||||
expect(ours.disableGeoip).toBe(loader.disableGeoip);
|
||||
expect(ours.sendFeatureFlags).toBe(loader.sendFeatureFlags);
|
||||
if (hasPrivateRef) expect(ours.uuid).not.toBe(loader.uuid);
|
||||
else expect(ours.uuid).toBe(loader.uuid);
|
||||
|
||||
// Intended differences: real ids and Cloud workspace properties.
|
||||
const intended = {
|
||||
distinct_id: "workspace:stack-123",
|
||||
stack_id: "stack-123",
|
||||
environment: "staging",
|
||||
$groups: { workspace: "stack-123" },
|
||||
...("agent_id" in inputDims ? { agent_id: inputDims.agent_id } : {}),
|
||||
...(hasPrivateRef ? { task_id: golden.rawTaskId } : {}),
|
||||
};
|
||||
expect(ours.distinct_id).toBe("workspace:stack-123");
|
||||
expect(ours.properties).toEqual({ ...loader.properties, ...intended });
|
||||
// Key order matches too, so the stored property layout is identical.
|
||||
expect(Object.keys(ours.properties).slice(0, Object.keys(loader.properties).length - 2)).toEqual(
|
||||
Object.keys(loader.properties).filter((key) => key !== "distinct_id" && key !== "$process_person_profile"),
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
it("uses the acting user as distinct_id and links the browser session", () => {
|
||||
const event = buildPostHogDirectEvent(
|
||||
{ name: "routine.created", occurredAt: "2026-11-17T11:58:06.000Z", dimensions: {} },
|
||||
{ userId: "user-1", companyId: "company-1", sessionId: "sess-1", windowId: "win-1" },
|
||||
meta,
|
||||
config,
|
||||
)!;
|
||||
expect(event.distinct_id).toBe("user-1");
|
||||
expect(event.properties).toMatchObject({
|
||||
distinct_id: "user-1",
|
||||
user_id: "user-1",
|
||||
company_id: "company-1",
|
||||
$session_id: "sess-1",
|
||||
$window_id: "win-1",
|
||||
$groups: { workspace: "stack-123" },
|
||||
});
|
||||
expect(event.properties).not.toHaveProperty("$process_person_profile");
|
||||
});
|
||||
|
||||
it("falls back to the workspace id without an acting user", () => {
|
||||
expect(resolveDistinctId(config, undefined)).toBe("workspace:stack-123");
|
||||
expect(resolveDistinctId(config, { companyId: "company-1", sessionId: "sess-1" })).toBe("workspace:stack-123");
|
||||
expect(resolveDistinctId(config, { userId: "user-9" })).toBe("user-9");
|
||||
});
|
||||
|
||||
it("keeps every generated fallback rule tied to an enum in the shared contract", () => {
|
||||
const domains = PAPERCLIP_ENUM_DESCRIPTIONS as Record<string, Record<string, Record<string, string>>>;
|
||||
for (const [eventName, rules] of Object.entries(UNKNOWN_ENUM_FALLBACKS)) {
|
||||
for (const [key, rule] of Object.entries(rules)) {
|
||||
expect(Object.keys(domains[eventName]?.[key] ?? {}), `${eventName}.${key}`).toContain(rule.fallback);
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,348 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import express from "express";
|
||||
import request from "supertest";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { trackAgentTaskRun, trackCompanyImported, trackRoutineCreated } from "@paperclipai/shared/telemetry";
|
||||
|
||||
const hoisted = vi.hoisted(() => ({ instanceRoot: "", posthogNodeLoads: 0 }));
|
||||
|
||||
vi.mock("../home-paths.js", () => ({
|
||||
resolvePaperclipInstanceRoot: () => hoisted.instanceRoot,
|
||||
}));
|
||||
|
||||
// Counts real loads of the package. Self-hosted servers must never load it.
|
||||
vi.mock("posthog-node", () => {
|
||||
hoisted.posthogNodeLoads += 1;
|
||||
return { PostHog: class {} };
|
||||
});
|
||||
|
||||
import {
|
||||
getTelemetryClient,
|
||||
initTelemetry,
|
||||
isPostHogDirectTelemetryActive,
|
||||
resetTelemetryForTests,
|
||||
shutdownTelemetry,
|
||||
} from "../telemetry.js";
|
||||
import type { PostHogNodeClient } from "../services/posthog-direct/index.js";
|
||||
import {
|
||||
capturePostHogEventContext,
|
||||
postHogRequestContextMiddlewareForEnv,
|
||||
} from "../services/posthog-direct/request-context.js";
|
||||
import { serverVersion } from "../version.js";
|
||||
|
||||
const COLLECTOR = "http://collector.test/ingest";
|
||||
const CLOUD_ENV = {
|
||||
PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-token",
|
||||
PAPERCLIP_CLOUD_STACK_ID: "stack-123",
|
||||
PAPERCLIP_STACK_SLUG: "acme",
|
||||
PAPERCLIP_PRIMARY_HOST: "acme.paperclip.app",
|
||||
PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test",
|
||||
PAPERCLIP_POSTHOG_ENVIRONMENT: "staging",
|
||||
};
|
||||
|
||||
function fakePostHog() {
|
||||
const captured: Array<Parameters<PostHogNodeClient["capture"]>[0]> = [];
|
||||
const groups: Array<Parameters<PostHogNodeClient["groupIdentify"]>[0]> = [];
|
||||
const client: PostHogNodeClient & { shutdownCalls: number } = {
|
||||
shutdownCalls: 0,
|
||||
capture: (message) => void captured.push(message),
|
||||
groupIdentify: (message) => void groups.push(message),
|
||||
flush: async () => {},
|
||||
shutdown: async () => {
|
||||
client.shutdownCalls += 1;
|
||||
},
|
||||
};
|
||||
const factory = vi.fn(async () => client);
|
||||
return { client, captured, groups, factory };
|
||||
}
|
||||
|
||||
function readState() {
|
||||
return JSON.parse(readFileSync(path.join(hoisted.instanceRoot, "telemetry", "state.json"), "utf-8")) as {
|
||||
installId: string;
|
||||
salt: string;
|
||||
};
|
||||
}
|
||||
|
||||
describe("server telemetry sender selection", () => {
|
||||
let fetchMock: ReturnType<typeof vi.fn>;
|
||||
|
||||
beforeEach(() => {
|
||||
hoisted.instanceRoot = mkdtempSync(path.join(os.tmpdir(), "paperclip-posthog-direct-"));
|
||||
hoisted.posthogNodeLoads = 0;
|
||||
for (const name of ["CI", "CONTINUOUS_INTEGRATION", "BUILD_NUMBER", "GITHUB_ACTIONS", "GITLAB_CI", "DO_NOT_TRACK", "PAPERCLIP_TELEMETRY_DISABLED"]) {
|
||||
vi.stubEnv(name, "");
|
||||
}
|
||||
vi.stubEnv("PAPERCLIP_TELEMETRY_ENDPOINT", COLLECTOR);
|
||||
fetchMock = vi.fn().mockResolvedValue({ ok: true });
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
resetTelemetryForTests();
|
||||
vi.unstubAllEnvs();
|
||||
vi.unstubAllGlobals();
|
||||
rmSync(hoisted.instanceRoot, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it("self-hosted: posts the unchanged hashed envelope to the collector and never loads posthog-node", async () => {
|
||||
const client = initTelemetry({ enabled: true }, { env: {} })!;
|
||||
expect(isPostHogDirectTelemetryActive()).toBe(false);
|
||||
trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" });
|
||||
await shutdownTelemetry();
|
||||
|
||||
expect(hoisted.posthogNodeLoads).toBe(0);
|
||||
expect(fetchMock).toHaveBeenCalledTimes(1);
|
||||
expect(fetchMock.mock.calls[0]![0]).toBe(COLLECTOR);
|
||||
const body = String((fetchMock.mock.calls[0]![1] as RequestInit).body);
|
||||
const parsed = JSON.parse(body);
|
||||
const state = readState();
|
||||
const hashedTaskId = createHash("sha256").update(state.salt + "task-raw-id").digest("hex").slice(0, 16);
|
||||
// Byte-identical to the envelope the collector path has always sent.
|
||||
expect(body).toBe(
|
||||
JSON.stringify({
|
||||
app: "paperclip",
|
||||
schemaVersion: "1",
|
||||
installId: state.installId,
|
||||
version: serverVersion,
|
||||
events: [
|
||||
{ name: "server.started", occurredAt: parsed.events[0].occurredAt, dimensions: { os_platform: process.platform } },
|
||||
{
|
||||
name: "agent.task_run",
|
||||
occurredAt: parsed.events[1].occurredAt,
|
||||
dimensions: { agent_id: "agent-1", state: "succeeded", task_id: hashedTaskId },
|
||||
},
|
||||
],
|
||||
batchId: parsed.batchId,
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it("self-hosted: ignores posthog-js tracing headers", async () => {
|
||||
expect(postHogRequestContextMiddlewareForEnv({})).toBeNull();
|
||||
expect(postHogRequestContextMiddlewareForEnv({ PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test" })).toBeNull();
|
||||
const app = express();
|
||||
let context: unknown = "unset";
|
||||
app.get("/probe", (_req, res) => {
|
||||
context = capturePostHogEventContext();
|
||||
res.json({});
|
||||
});
|
||||
await request(app).get("/probe").set("X-POSTHOG-SESSION-ID", "sess-1").expect(200);
|
||||
expect(context).toBeUndefined();
|
||||
});
|
||||
|
||||
it("Cloud: sends each batch only to PostHog with real ids, and identifies the workspace group", async () => {
|
||||
const posthog = fakePostHog();
|
||||
const client = initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory })!;
|
||||
expect(isPostHogDirectTelemetryActive()).toBe(true);
|
||||
trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" });
|
||||
trackCompanyImported(client, { sourceType: "github", sourceRef: "acme/private-repo", isPrivate: true });
|
||||
await shutdownTelemetry();
|
||||
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
expect(posthog.captured.map((message) => message.event).sort()).toEqual([
|
||||
"agent.task_run",
|
||||
"cloud.workspace_started",
|
||||
"company.imported",
|
||||
"server.started",
|
||||
]);
|
||||
// A private source ref is customer content: it stays hashed on Cloud too.
|
||||
const imported = posthog.captured.find((message) => message.event === "company.imported")!;
|
||||
const salt = readState().salt;
|
||||
expect(imported.properties).toMatchObject({
|
||||
source_ref: createHash("sha256").update(salt + "acme/private-repo").digest("hex").slice(0, 16),
|
||||
source_ref_hashed: true,
|
||||
});
|
||||
expect(JSON.stringify(imported)).not.toContain("acme/private-repo");
|
||||
const run = posthog.captured.find((message) => message.event === "agent.task_run")!;
|
||||
expect(run.distinctId).toBe("workspace:stack-123");
|
||||
expect(run.groups).toEqual({ workspace: "stack-123" });
|
||||
expect(run.disableGeoip).toBe(true);
|
||||
expect(run.properties).toMatchObject({
|
||||
agent_id: "agent-1",
|
||||
task_id: "task-raw-id",
|
||||
stack_id: "stack-123",
|
||||
environment: "staging",
|
||||
deployment_source: "cloud",
|
||||
$groups: { workspace: "stack-123" },
|
||||
$process_person_profile: false,
|
||||
});
|
||||
expect(run.properties).not.toHaveProperty("install_hash");
|
||||
|
||||
const installHash = createHash("sha256").update(readState().installId).digest("hex");
|
||||
const started = posthog.captured.find((message) => message.event === "cloud.workspace_started")!;
|
||||
expect(started.distinctId).toBe("workspace:stack-123");
|
||||
expect(started.groups).toEqual({ workspace: "stack-123" });
|
||||
expect(started.properties).toMatchObject({
|
||||
app: "paperclip",
|
||||
schema_version: "1",
|
||||
source: "client",
|
||||
deployment_source: "cloud",
|
||||
version: serverVersion,
|
||||
stack_id: "stack-123",
|
||||
install_hash: installHash,
|
||||
environment: "staging",
|
||||
distinct_id: "workspace:stack-123",
|
||||
$process_person_profile: false,
|
||||
});
|
||||
for (const message of posthog.captured) {
|
||||
expect(message.properties?.environment, message.event).toBe("staging");
|
||||
if (message.event !== "cloud.workspace_started") expect(message.properties).not.toHaveProperty("install_hash");
|
||||
}
|
||||
expect(posthog.groups).toEqual([
|
||||
{
|
||||
groupType: "workspace",
|
||||
groupKey: "stack-123",
|
||||
disableGeoip: true,
|
||||
properties: { stack_slug: "acme", primary_host: "acme.paperclip.app", environment: "staging" },
|
||||
},
|
||||
]);
|
||||
expect(posthog.client.shutdownCalls).toBe(1);
|
||||
});
|
||||
|
||||
it("Cloud: stays on the collector when PAPERCLIP_POSTHOG_ENVIRONMENT is unset", async () => {
|
||||
const posthog = fakePostHog();
|
||||
const { PAPERCLIP_POSTHOG_ENVIRONMENT: _omit, ...noEnvironment } = CLOUD_ENV;
|
||||
const client = initTelemetry({ enabled: true }, { env: noEnvironment, postHogFactory: posthog.factory })!;
|
||||
expect(isPostHogDirectTelemetryActive()).toBe(false);
|
||||
trackRoutineCreated(client);
|
||||
await shutdownTelemetry();
|
||||
|
||||
expect(posthog.factory).not.toHaveBeenCalled();
|
||||
expect(fetchMock).toHaveBeenCalledTimes(1);
|
||||
expect(fetchMock.mock.calls[0]![0]).toBe(COLLECTOR);
|
||||
expect(postHogRequestContextMiddlewareForEnv(noEnvironment)).toBeNull();
|
||||
});
|
||||
|
||||
it("Cloud: the kill switch falls back to the collector", async () => {
|
||||
const posthog = fakePostHog();
|
||||
const client = initTelemetry(
|
||||
{ enabled: true },
|
||||
{ env: { ...CLOUD_ENV, PAPERCLIP_POSTHOG_DIRECT: "0" }, postHogFactory: posthog.factory },
|
||||
)!;
|
||||
expect(isPostHogDirectTelemetryActive()).toBe(false);
|
||||
trackRoutineCreated(client);
|
||||
await shutdownTelemetry();
|
||||
|
||||
expect(posthog.factory).not.toHaveBeenCalled();
|
||||
expect(fetchMock).toHaveBeenCalledTimes(1);
|
||||
expect(postHogRequestContextMiddlewareForEnv({ ...CLOUD_ENV, PAPERCLIP_POSTHOG_DIRECT: "0" })).toBeNull();
|
||||
});
|
||||
|
||||
it("Cloud: links request events to the acting user and browser session", async () => {
|
||||
const posthog = fakePostHog();
|
||||
initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory });
|
||||
const middleware = postHogRequestContextMiddlewareForEnv(CLOUD_ENV);
|
||||
expect(middleware).not.toBeNull();
|
||||
|
||||
const app = express();
|
||||
app.use(middleware!);
|
||||
app.use((req, _res, next) => {
|
||||
const as = req.header("x-test-actor");
|
||||
req.actor =
|
||||
as === "user"
|
||||
? { type: "board", userId: "user-1", source: "session" }
|
||||
: as === "agent"
|
||||
? { type: "agent", agentId: "agent-1", companyId: "company-1", source: "agent_key" }
|
||||
: { type: "none", source: "none" };
|
||||
next();
|
||||
});
|
||||
app.post("/companies/:companyId/routines", (_req, res) => {
|
||||
trackRoutineCreated(getTelemetryClient()!);
|
||||
res.json({});
|
||||
});
|
||||
|
||||
await request(app)
|
||||
.post("/companies/company-9/routines")
|
||||
.set("x-test-actor", "user")
|
||||
.set("X-POSTHOG-SESSION-ID", "0190f6b2-7c1d-7a3e-9f00-123456789abc")
|
||||
.set("X-POSTHOG-WINDOW-ID", "0190f6b2-7c1d-7a3e-9f00-abcdefabcdef")
|
||||
// Never used for identity.
|
||||
.set("X-POSTHOG-DISTINCT-ID", "spoofed-person")
|
||||
.expect(200);
|
||||
await request(app).post("/companies/company-9/routines").set("x-test-actor", "agent").expect(200);
|
||||
await request(app)
|
||||
.post("/companies/company-9/routines")
|
||||
.set("X-POSTHOG-SESSION-ID", "bad id with spaces")
|
||||
// An anonymous request cannot claim a person through the header either.
|
||||
.set("X-POSTHOG-DISTINCT-ID", "spoofed-person")
|
||||
.expect(200);
|
||||
await shutdownTelemetry();
|
||||
|
||||
const routines = posthog.captured.filter((message) => message.event === "routine.created");
|
||||
expect(routines).toHaveLength(3);
|
||||
expect(routines[0]!.distinctId).toBe("user-1");
|
||||
expect(routines[0]!.properties).toMatchObject({
|
||||
user_id: "user-1",
|
||||
company_id: "company-9",
|
||||
$session_id: "0190f6b2-7c1d-7a3e-9f00-123456789abc",
|
||||
$window_id: "0190f6b2-7c1d-7a3e-9f00-abcdefabcdef",
|
||||
});
|
||||
expect(routines[0]!.properties).not.toHaveProperty("$process_person_profile");
|
||||
expect(JSON.stringify(routines)).not.toContain("spoofed-person");
|
||||
|
||||
expect(routines[1]!.distinctId).toBe("workspace:stack-123");
|
||||
expect(routines[1]!.properties).toMatchObject({ company_id: "company-1", $process_person_profile: false });
|
||||
expect(routines[1]!.properties).not.toHaveProperty("user_id");
|
||||
|
||||
expect(routines[2]!.distinctId).toBe("workspace:stack-123");
|
||||
expect(routines[2]!.properties).not.toHaveProperty("$session_id");
|
||||
expect(routines[2]!.properties).not.toHaveProperty("user_id");
|
||||
expect(routines[2]!.properties).toMatchObject({ distinct_id: "workspace:stack-123", $process_person_profile: false });
|
||||
});
|
||||
|
||||
it("Cloud: uses a board user's only company on routes without a company id", async () => {
|
||||
const posthog = fakePostHog();
|
||||
initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory });
|
||||
const app = express();
|
||||
app.use(postHogRequestContextMiddlewareForEnv(CLOUD_ENV)!);
|
||||
app.use((req, _res, next) => {
|
||||
const companyIds = req.header("x-test-companies")!.split(",");
|
||||
req.actor = { type: "board", userId: "user-1", companyIds, source: "cloud_tenant" };
|
||||
next();
|
||||
});
|
||||
app.post("/issues/:id/interactions/:interactionId/reject", (_req, res) => {
|
||||
trackRoutineCreated(getTelemetryClient()!);
|
||||
res.json({});
|
||||
});
|
||||
await request(app).post("/issues/i-1/interactions/x-1/reject").set("x-test-companies", "company-1").expect(200);
|
||||
await request(app)
|
||||
.post("/issues/i-1/interactions/x-1/reject")
|
||||
.set("x-test-companies", "company-1,company-2")
|
||||
.expect(200);
|
||||
await shutdownTelemetry();
|
||||
|
||||
const routines = posthog.captured.filter((message) => message.event === "routine.created");
|
||||
expect(routines[0]!.properties).toMatchObject({ company_id: "company-1", user_id: "user-1" });
|
||||
expect(routines[1]!.properties).not.toHaveProperty("company_id");
|
||||
});
|
||||
|
||||
it("Cloud: work that outlives its request does not inherit the request's user", async () => {
|
||||
const posthog = fakePostHog();
|
||||
initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory });
|
||||
const app = express();
|
||||
app.use(postHogRequestContextMiddlewareForEnv(CLOUD_ENV)!);
|
||||
let later: Promise<void> | null = null;
|
||||
app.post("/start", (req, res) => {
|
||||
req.actor = { type: "board", userId: "user-1", source: "session" };
|
||||
later = new Promise((resolve) => {
|
||||
res.on("finish", () =>
|
||||
setTimeout(() => {
|
||||
trackRoutineCreated(getTelemetryClient()!);
|
||||
resolve();
|
||||
}, 5),
|
||||
);
|
||||
});
|
||||
res.json({});
|
||||
});
|
||||
await request(app).post("/start").set("X-POSTHOG-SESSION-ID", "sess-1").expect(200);
|
||||
await later;
|
||||
await shutdownTelemetry();
|
||||
|
||||
const routine = posthog.captured.find((message) => message.event === "routine.created")!;
|
||||
expect(routine.distinctId).toBe("workspace:stack-123");
|
||||
expect(routine.properties).not.toHaveProperty("$session_id");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,73 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { createPostHogDirectTransport, type PostHogNodeClient } from "../services/posthog-direct/transport.js";
|
||||
import type { CloudPostHogConfig } from "../services/cloud-posthog-config.js";
|
||||
|
||||
const config: CloudPostHogConfig = {
|
||||
token: "phc_test",
|
||||
host: "http://127.0.0.1:1",
|
||||
environment: "staging",
|
||||
stackId: "stack-123",
|
||||
directEnabled: true,
|
||||
browserEnabled: false,
|
||||
replayEnabled: false,
|
||||
};
|
||||
|
||||
const startup = {
|
||||
stackSlug: "acme",
|
||||
primaryHost: "acme.paperclip.app",
|
||||
app: "paperclip",
|
||||
schemaVersion: "1",
|
||||
version: "1.0.0",
|
||||
installId: "install-1",
|
||||
installHash: "hash-1",
|
||||
};
|
||||
|
||||
function fakeClient() {
|
||||
const captured: string[] = [];
|
||||
const groups: string[] = [];
|
||||
const client: PostHogNodeClient = {
|
||||
capture: (message) => void captured.push(message.event),
|
||||
groupIdentify: (message) => void groups.push(message.groupKey),
|
||||
flush: async () => {},
|
||||
shutdown: async () => {},
|
||||
};
|
||||
return { client, captured, groups };
|
||||
}
|
||||
|
||||
describe("PostHog direct transport", () => {
|
||||
it("re-sends the startup announcement with the first batch after the client failed to load", async () => {
|
||||
const fake = fakeClient();
|
||||
const factory = vi
|
||||
.fn<() => Promise<PostHogNodeClient>>()
|
||||
.mockRejectedValueOnce(new Error("import failed"))
|
||||
.mockResolvedValue(fake.client);
|
||||
const transport = createPostHogDirectTransport(config, { factory });
|
||||
|
||||
await expect(transport.announceWorkspace(startup)).rejects.toThrow("import failed");
|
||||
expect(fake.captured).toEqual([]);
|
||||
|
||||
const result = await transport.send({
|
||||
app: "paperclip",
|
||||
schemaVersion: "1",
|
||||
installId: "install-1",
|
||||
version: "1.0.0",
|
||||
batchId: "batch-1",
|
||||
events: [{ event: { name: "routine.created", occurredAt: "2026-11-17T12:00:00.000Z", dimensions: {} }, context: undefined }],
|
||||
});
|
||||
|
||||
expect(result).toEqual({ kind: "ok" });
|
||||
expect(fake.groups).toEqual(["stack-123"]);
|
||||
expect(fake.captured).toEqual(["cloud.workspace_started", "routine.created"]);
|
||||
|
||||
// Sent once only.
|
||||
await transport.send({
|
||||
app: "paperclip",
|
||||
schemaVersion: "1",
|
||||
installId: "install-1",
|
||||
version: "1.0.0",
|
||||
batchId: "batch-2",
|
||||
events: [{ event: { name: "routine.created", occurredAt: "2026-11-17T12:00:01.000Z", dimensions: {} }, context: undefined }],
|
||||
});
|
||||
expect(fake.captured.filter((event) => event === "cloud.workspace_started")).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
@@ -263,6 +263,7 @@ import {
|
||||
stopServerMetrics,
|
||||
} from "./services/server-metrics.js";
|
||||
import { chatWebhookBodyParser } from "./middleware/chat-webhook-body.js";
|
||||
import { postHogRequestContextMiddlewareForEnv } from "./services/posthog-direct/request-context.js";
|
||||
import { createChatWebhookDiagnostics } from "./services/chat-webhook-diagnostics.js";
|
||||
|
||||
type UiMode = "none" | "static" | "vite-dev";
|
||||
@@ -557,6 +558,11 @@ export async function createApp(
|
||||
app.use((req, res, next) => (dotPrincipalHttp.matchesPost(req) || ["/mcp/files/upload", "/mcp/runner/files/upload"].includes(req.path)) ? next() : jsonBodyParser(req, res, next));
|
||||
app.use("/api", apiCompression());
|
||||
app.use(httpLogger);
|
||||
// Paperclip Cloud only: link server analytics events to the browser session
|
||||
// that caused them. Self-hosted servers never mount this, so posthog-js
|
||||
// tracing headers are ignored there.
|
||||
const postHogRequestContext = postHogRequestContextMiddlewareForEnv();
|
||||
if (postHogRequestContext) app.use(postHogRequestContext);
|
||||
const privateHostnameGateEnabled = shouldEnablePrivateHostnameGuard({
|
||||
deploymentMode: opts.deploymentMode,
|
||||
deploymentExposure: opts.deploymentExposure,
|
||||
|
||||
+4
-5
@@ -212,7 +212,7 @@ import { abortInFlightMultipartUploads } from "./storage/s3-multipart.js";
|
||||
import { printStartupBanner } from "./startup-banner.js";
|
||||
import { getBoardClaimWarningUrl, initializeBoardClaimChallenge } from "./board-claim.js";
|
||||
import { maybePersistWorktreeRuntimePorts } from "./worktree-config.js";
|
||||
import { initTelemetry, getTelemetryClient } from "./telemetry.js";
|
||||
import { initTelemetry, getTelemetryClient, shutdownTelemetry } from "./telemetry.js";
|
||||
import { conflict } from "./errors.js";
|
||||
import { ensureDecisionSigningSecret } from "./services/decision-signing.js";
|
||||
import { createDecisionRetentionNotifyOriginAgent, createDecisionWakeOriginAgent } from "./services/decision-wakeup.js";
|
||||
@@ -2361,14 +2361,13 @@ async function startServerWithDatabaseTeardown(
|
||||
});
|
||||
}
|
||||
|
||||
const telemetryClient = getTelemetryClient();
|
||||
if (telemetryClient) {
|
||||
telemetryClient.stop();
|
||||
if (getTelemetryClient()) {
|
||||
await runBoundedShutdownStep({
|
||||
step: "telemetry_flush",
|
||||
signal,
|
||||
timeoutMs: 5_000,
|
||||
run: () => telemetryClient.flush(),
|
||||
// Flushes queued events, then closes the Cloud PostHog client if any.
|
||||
run: () => shutdownTelemetry(),
|
||||
log: logger,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
import { isCloudManagedInstance, type CloudInstanceEnv } from "./cloud-instance.js";
|
||||
|
||||
/**
|
||||
* PostHog settings for a Paperclip Cloud stack. Present only on a
|
||||
* Cloud-managed instance that has a project token and a stack id; every
|
||||
* self-hosted install resolves `null` and keeps the collector path.
|
||||
*/
|
||||
export type CloudPostHogConfig = {
|
||||
token: string; // PAPERCLIP_POSTHOG_PROJECT_TOKEN
|
||||
host: string; // PAPERCLIP_POSTHOG_HOST, default "https://us.i.posthog.com"
|
||||
environment: string | null; // PAPERCLIP_POSTHOG_ENVIRONMENT
|
||||
stackId: string; // PAPERCLIP_CLOUD_STACK_ID
|
||||
directEnabled: boolean; // PAPERCLIP_POSTHOG_DIRECT !== "0"
|
||||
browserEnabled: boolean; // PAPERCLIP_POSTHOG_BROWSER_ENABLED === "1"
|
||||
replayEnabled: boolean; // browserEnabled && PAPERCLIP_POSTHOG_REPLAY_ENABLED !== "0"
|
||||
};
|
||||
|
||||
export const DEFAULT_CLOUD_POSTHOG_HOST = "https://us.i.posthog.com";
|
||||
|
||||
function readEnv(env: CloudInstanceEnv, name: string): string | null {
|
||||
const value = env[name]?.trim();
|
||||
return value ? value : null;
|
||||
}
|
||||
|
||||
export function resolveCloudPostHogConfig(
|
||||
env: Record<string, string | undefined> = process.env,
|
||||
): CloudPostHogConfig | null {
|
||||
if (!isCloudManagedInstance(env)) return null;
|
||||
const token = readEnv(env, "PAPERCLIP_POSTHOG_PROJECT_TOKEN");
|
||||
const stackId = readEnv(env, "PAPERCLIP_CLOUD_STACK_ID");
|
||||
if (!token || !stackId) return null;
|
||||
|
||||
const browserEnabled = readEnv(env, "PAPERCLIP_POSTHOG_BROWSER_ENABLED") === "1";
|
||||
return {
|
||||
token,
|
||||
host: (readEnv(env, "PAPERCLIP_POSTHOG_HOST") ?? DEFAULT_CLOUD_POSTHOG_HOST).replace(/\/+$/, ""),
|
||||
environment: readEnv(env, "PAPERCLIP_POSTHOG_ENVIRONMENT"),
|
||||
stackId,
|
||||
directEnabled: readEnv(env, "PAPERCLIP_POSTHOG_DIRECT") !== "0",
|
||||
browserEnabled,
|
||||
replayEnabled: browserEnabled && readEnv(env, "PAPERCLIP_POSTHOG_REPLAY_ENABLED") !== "0",
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether server events go straight to PostHog. Requires the kill switch to
|
||||
* be on and an environment: every direct event carries `environment`, so
|
||||
* without one the stack keeps using the collector.
|
||||
*/
|
||||
export function isPostHogDirectDeliveryEnabled(
|
||||
config: CloudPostHogConfig | null,
|
||||
): config is CloudPostHogConfig & { environment: string } {
|
||||
return Boolean(config?.directEnabled && config.environment);
|
||||
}
|
||||
@@ -0,0 +1,424 @@
|
||||
{
|
||||
"ingestedAt": "2026-11-17T12:00:00.000Z",
|
||||
"rawTaskId": "6f1f3c2a-9b8e-4d7c-a1b2-c3d4e5f60718",
|
||||
"hashedTaskId": "9c1e5b7a3d2f4e60",
|
||||
"envelope": {
|
||||
"app": "paperclip",
|
||||
"schemaVersion": "1",
|
||||
"installId": "11111111-2222-4333-8444-555555555555",
|
||||
"version": "2026.1117.0",
|
||||
"batchId": "fixture-batch-0001",
|
||||
"events": [
|
||||
{
|
||||
"name": "server.started",
|
||||
"occurredAt": "2026-11-17T11:58:00.000Z",
|
||||
"dimensions": {
|
||||
"os_platform": "linux"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "agent.task_run",
|
||||
"occurredAt": "2026-11-17T11:58:01.000Z",
|
||||
"dimensions": {
|
||||
"agent_id": "2f6c7d1e-0a4b-4c3d-9e8f-112233445566",
|
||||
"state": "succeeded",
|
||||
"adapter_type": "claude_local",
|
||||
"agent_role": "engineer",
|
||||
"model": "claude-opus-5-5",
|
||||
"duration_seconds": 42,
|
||||
"input_tokens": 1200,
|
||||
"output_tokens": 300,
|
||||
"task_id": "9c1e5b7a3d2f4e60"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "agent.created",
|
||||
"occurredAt": "2026-11-17T11:58:02.000Z",
|
||||
"dimensions": {
|
||||
"agent_id": "3a7b8c9d-1e2f-4a5b-8c6d-778899aabbcc",
|
||||
"agent_role": "astronaut"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "install.completed",
|
||||
"occurredAt": "2026-11-17T11:58:03.000Z",
|
||||
"dimensions": {
|
||||
"adapter_type": "future_adapter"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "skill.imported",
|
||||
"occurredAt": "2026-11-17T11:58:04.000Z",
|
||||
"dimensions": {
|
||||
"source_type": "mystery_source"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "interaction.resolved",
|
||||
"occurredAt": "2026-11-17T11:58:05.000Z",
|
||||
"dimensions": {
|
||||
"interaction_kind": "suggest_tasks",
|
||||
"status": "accepted",
|
||||
"resolved_by_kind": "user",
|
||||
"option_count": 3,
|
||||
"selected_option_count": 2,
|
||||
"legacy_inherited_restriction": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "routine.created",
|
||||
"occurredAt": "2026-11-17T11:58:06.000Z",
|
||||
"dimensions": {}
|
||||
},
|
||||
{
|
||||
"name": "question_response.delivery",
|
||||
"occurredAt": "2026-11-17T11:58:07.000Z",
|
||||
"dimensions": {
|
||||
"outcome": "delivered"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"canonicalRecords": [
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "a77f7fdef12def432e98412718b080efc3db2b4c0735bbbd623f7051dc4e6e76",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "server.started",
|
||||
"occurred_at": "2026-11-17T11:58:00.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"os_platform": "linux"
|
||||
},
|
||||
"normalized_properties": [],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "a4d9c57bc5d720ce3c7c25cf145499eb98e62639f782a545fd360717cdc8c635",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "agent.task_run",
|
||||
"occurred_at": "2026-11-17T11:58:01.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"agent_id": "282a1c1fae5df6996043f35138b162af4e794c00cf68087665b1a39c8b4980ca",
|
||||
"state": "succeeded",
|
||||
"adapter_type": "claude_local",
|
||||
"agent_role": "engineer",
|
||||
"model": "claude-opus-5-5",
|
||||
"duration_seconds": 42,
|
||||
"input_tokens": 1200,
|
||||
"output_tokens": 300,
|
||||
"task_id": "9c1e5b7a3d2f4e60"
|
||||
},
|
||||
"normalized_properties": [],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "22fae133df11fcfd31fe83847aa7206f90c4254a54b1a924c589ad4cec119846",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "agent.created",
|
||||
"occurred_at": "2026-11-17T11:58:02.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"agent_id": "9532a2b6bf43a010107bb5c09020418d34165f50155dfba097c49ae53269afb0",
|
||||
"agent_role": "other"
|
||||
},
|
||||
"normalized_properties": [
|
||||
"agent_role"
|
||||
],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "f66fe4effe5ef14500271e97791576ade468152b3e6b15e56dfc2c9deaa4333b",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "install.completed",
|
||||
"occurred_at": "2026-11-17T11:58:03.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"adapter_type": "other"
|
||||
},
|
||||
"normalized_properties": [
|
||||
"adapter_type"
|
||||
],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "ec19908cf8c99d58357929b2ee9c494ba3af8f04a5ade3e26eeac1188bc2560c",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "skill.imported",
|
||||
"occurred_at": "2026-11-17T11:58:04.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"source_type": "unknown"
|
||||
},
|
||||
"normalized_properties": [
|
||||
"source_type"
|
||||
],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "2d7c541d00ca3b5971d56d8cf43f02d79e1bbae41fc526b1490c4640a627e2fe",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "interaction.resolved",
|
||||
"occurred_at": "2026-11-17T11:58:05.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {
|
||||
"interaction_kind": "suggest_tasks",
|
||||
"status": "accepted",
|
||||
"resolved_by_kind": "user",
|
||||
"option_count": 3,
|
||||
"selected_option_count": 2,
|
||||
"legacy_inherited_restriction": false
|
||||
},
|
||||
"normalized_properties": [],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
},
|
||||
{
|
||||
"source": "client",
|
||||
"event_id": "369e2de4dbd5da7871377958422888401120642e2b0edafa3f3002e58f1d6fe9",
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"version": "2026.1117.0",
|
||||
"envelope_version": 2,
|
||||
"app_version": "2026.1117.0",
|
||||
"event_name": "routine.created",
|
||||
"occurred_at": "2026-11-17T11:58:06.000Z",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49",
|
||||
"dimensions": {},
|
||||
"normalized_properties": [],
|
||||
"backfilled": false,
|
||||
"deployment_source": "cloud",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11"
|
||||
}
|
||||
],
|
||||
"loaderEvents": [
|
||||
{
|
||||
"event": "server.started",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:00.000Z",
|
||||
"uuid": "a77f7fde-f12d-4f43-ae98-412718b080ef",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [],
|
||||
"version": "2026.1117.0",
|
||||
"os_platform": "linux",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "agent.task_run",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:01.000Z",
|
||||
"uuid": "a4d9c57b-c5d7-40ce-bc7c-25cf145499eb",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [],
|
||||
"version": "2026.1117.0",
|
||||
"agent_id": "282a1c1fae5df6996043f35138b162af4e794c00cf68087665b1a39c8b4980ca",
|
||||
"state": "succeeded",
|
||||
"adapter_type": "claude_local",
|
||||
"agent_role": "engineer",
|
||||
"model": "claude-opus-5-5",
|
||||
"duration_seconds": 42,
|
||||
"input_tokens": 1200,
|
||||
"output_tokens": 300,
|
||||
"task_id": "9c1e5b7a3d2f4e60",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "agent.created",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:02.000Z",
|
||||
"uuid": "22fae133-df11-4cfd-b1fe-83847aa7206f",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [
|
||||
"agent_role"
|
||||
],
|
||||
"version": "2026.1117.0",
|
||||
"agent_id": "9532a2b6bf43a010107bb5c09020418d34165f50155dfba097c49ae53269afb0",
|
||||
"agent_role": "other",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "install.completed",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:03.000Z",
|
||||
"uuid": "f66fe4ef-fe5e-4145-8027-1e97791576ad",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [
|
||||
"adapter_type"
|
||||
],
|
||||
"version": "2026.1117.0",
|
||||
"adapter_type": "other",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "skill.imported",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:04.000Z",
|
||||
"uuid": "ec19908c-f8c9-4d58-b579-29b2ee9c494b",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [
|
||||
"source_type"
|
||||
],
|
||||
"version": "2026.1117.0",
|
||||
"source_type": "unknown",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "interaction.resolved",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:05.000Z",
|
||||
"uuid": "2d7c541d-00ca-4b59-b1d5-6d8cf43f02d7",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [],
|
||||
"version": "2026.1117.0",
|
||||
"interaction_kind": "suggest_tasks",
|
||||
"status": "accepted",
|
||||
"resolved_by_kind": "user",
|
||||
"option_count": 3,
|
||||
"selected_option_count": 2,
|
||||
"legacy_inherited_restriction": false,
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"event": "routine.created",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"timestamp": "2026-11-17T11:58:06.000Z",
|
||||
"uuid": "369e2de4-dbd5-4a78-b137-795842288840",
|
||||
"disableGeoip": true,
|
||||
"sendFeatureFlags": false,
|
||||
"properties": {
|
||||
"app": "paperclip",
|
||||
"schema_version": "1",
|
||||
"source": "client",
|
||||
"deployment_source": "cloud",
|
||||
"ingested_at": "2026-11-17T12:00:00.000Z",
|
||||
"event_date": "2026-11-17",
|
||||
"hour": "11",
|
||||
"normalized_properties": [],
|
||||
"version": "2026.1117.0",
|
||||
"distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb",
|
||||
"$process_person_profile": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,118 @@
|
||||
// GENERATED by scripts/generate-posthog-direct-fixtures.mjs from the telemetry
|
||||
// backend's event manifest (x-normalize.unknown_enum_value). DO NOT EDIT.
|
||||
// Enum domains come from PAPERCLIP_ENUM_DESCRIPTIONS in @paperclipai/shared.
|
||||
|
||||
export const UNKNOWN_ENUM_FALLBACKS = {
|
||||
"agent.created": {
|
||||
"agent_role": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"agent.first_heartbeat": {
|
||||
"agent_role": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"agent.task_completed": {
|
||||
"adapter_type": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
},
|
||||
"agent_role": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"agent.task_run": {
|
||||
"adapter_type": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
},
|
||||
"agent_role": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
}
|
||||
},
|
||||
"company.imported": {
|
||||
"source_type": {
|
||||
"fallback": "unknown",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"goal.created": {
|
||||
"goal_level": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"install.completed": {
|
||||
"adapter_type": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"interaction.created": {
|
||||
"interaction_kind": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"interaction.resolved": {
|
||||
"interaction_kind": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
},
|
||||
"status": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
},
|
||||
"resolution_reason": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
},
|
||||
"resolved_by_kind": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
},
|
||||
"created_by_kind": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
},
|
||||
"creator_agent_role": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
},
|
||||
"continuation_policy": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
},
|
||||
"target_type": {
|
||||
"fallback": "other",
|
||||
"required": false
|
||||
}
|
||||
},
|
||||
"routine.run": {
|
||||
"source": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
},
|
||||
"status": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"server.started": {
|
||||
"os_platform": {
|
||||
"fallback": "other",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"skill.imported": {
|
||||
"source_type": {
|
||||
"fallback": "unknown",
|
||||
"required": true
|
||||
}
|
||||
}
|
||||
} as const;
|
||||
@@ -0,0 +1,233 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
PAPERCLIP_ENUM_DESCRIPTIONS,
|
||||
PAPERCLIP_EVENTS,
|
||||
type TelemetryDimensions,
|
||||
type TelemetryEvent,
|
||||
} from "@paperclipai/shared/telemetry";
|
||||
import type { CloudPostHogConfig } from "../cloud-posthog-config.js";
|
||||
import { UNKNOWN_ENUM_FALLBACKS } from "./enum-fallbacks.generated.js";
|
||||
import type { PostHogEventContext } from "./request-context.js";
|
||||
|
||||
/**
|
||||
* Builds PostHog capture messages for Paperclip Cloud direct delivery.
|
||||
*
|
||||
* The shape mirrors what the telemetry backend produces today for collector
|
||||
* events (ingest `normalizeCanonicalRecord` + loader `buildPostHogEvent`), so
|
||||
* existing insights keep working: same event names, metadata keys,
|
||||
* deterministic uuid, and enum fallback normalization. The intended Cloud
|
||||
* differences are real identifiers (distinct_id, agent_id, private refs) and
|
||||
* the added workspace properties (stack_id, company_id, user_id, environment,
|
||||
* $groups, $session_id, $window_id).
|
||||
*/
|
||||
|
||||
export const POSTHOG_WORKSPACE_GROUP_TYPE = "workspace";
|
||||
|
||||
/**
|
||||
* Direct-path-only startup event. It is not in the generated contract and
|
||||
* never goes through the collector. It carries the hashed install id so an
|
||||
* offline job can join pre-switch history to the workspace without group
|
||||
* analytics.
|
||||
*/
|
||||
export const CLOUD_WORKSPACE_STARTED_EVENT = "cloud.workspace_started";
|
||||
|
||||
export type PostHogDirectEvent = {
|
||||
event: string;
|
||||
distinct_id: string;
|
||||
timestamp: string;
|
||||
uuid: string;
|
||||
disableGeoip: true;
|
||||
sendFeatureFlags: false;
|
||||
properties: Record<string, unknown>;
|
||||
};
|
||||
|
||||
export type PostHogDirectBatchMeta = {
|
||||
app: string;
|
||||
schemaVersion: string;
|
||||
installId: string;
|
||||
version: string;
|
||||
ingestedAt: string;
|
||||
};
|
||||
|
||||
type IdentityConfig = Pick<CloudPostHogConfig, "stackId" | "environment">;
|
||||
|
||||
function stableJson(value: unknown): string {
|
||||
if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
|
||||
if (value && typeof value === "object") {
|
||||
const record = value as Record<string, unknown>;
|
||||
return `{${Object.keys(record)
|
||||
.sort()
|
||||
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
|
||||
.join(",")}}`;
|
||||
}
|
||||
return JSON.stringify(value);
|
||||
}
|
||||
|
||||
/** Same formula as the telemetry backend's `deterministicEventId`. */
|
||||
export function deterministicEventId(input: {
|
||||
app: string;
|
||||
installId: string;
|
||||
event: { name: string; occurredAt: string; dimensions: TelemetryDimensions };
|
||||
}): string {
|
||||
return createHash("sha256")
|
||||
.update(String(input.app))
|
||||
.update("\0")
|
||||
.update(String(input.installId))
|
||||
.update("\0")
|
||||
.update(String(input.event.name))
|
||||
.update("\0")
|
||||
.update(String(input.event.occurredAt))
|
||||
.update("\0")
|
||||
.update(stableJson(input.event.dimensions ?? {}))
|
||||
.digest("hex");
|
||||
}
|
||||
|
||||
/** Same formula as the telemetry backend's `eventIdToPostHogUuid`. */
|
||||
export function eventIdToPostHogUuid(eventId: string): string {
|
||||
if (!/^[0-9a-f]{64}$/.test(eventId)) {
|
||||
throw new Error("eventIdToPostHogUuid requires a 64 lowercase hex event id");
|
||||
}
|
||||
const chars = eventId.slice(0, 32).split("");
|
||||
chars[12] = "4";
|
||||
chars[16] = ((parseInt(chars[16]!, 16) & 0x3) | 0x8).toString(16);
|
||||
const hex = chars.join("");
|
||||
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
|
||||
}
|
||||
|
||||
const ENUM_DOMAINS = PAPERCLIP_ENUM_DESCRIPTIONS as Record<string, Record<string, Record<string, string>>>;
|
||||
const FALLBACKS = UNKNOWN_ENUM_FALLBACKS as Record<string, Record<string, { fallback: string; required: boolean }>>;
|
||||
|
||||
/**
|
||||
* Applies the backend's unknown-enum fallback. Returns null for an event the
|
||||
* collector path would quarantine (and so never reach PostHog): an
|
||||
* unregistered name, or an unknown enum value whose fallback is itself not an
|
||||
* allowed value.
|
||||
*/
|
||||
export function normalizeDimensions(
|
||||
eventName: string,
|
||||
dimensions: TelemetryDimensions,
|
||||
): { dimensions: TelemetryDimensions; normalizedProperties: string[] } | null {
|
||||
if (!Object.hasOwn(PAPERCLIP_EVENTS, eventName)) return null;
|
||||
const normalized: TelemetryDimensions = { ...dimensions };
|
||||
const normalizedProperties: string[] = [];
|
||||
for (const [key, rule] of Object.entries(FALLBACKS[eventName] ?? {})) {
|
||||
const allowed = Object.keys(ENUM_DOMAINS[eventName]?.[key] ?? {});
|
||||
const value = normalized[key];
|
||||
if (value === undefined) {
|
||||
if (rule.required && allowed.includes(rule.fallback)) {
|
||||
normalized[key] = rule.fallback;
|
||||
normalizedProperties.push(key);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (allowed.length > 0 && !allowed.includes(String(value))) {
|
||||
if (!allowed.includes(rule.fallback)) return null;
|
||||
normalized[key] = rule.fallback;
|
||||
normalizedProperties.push(key);
|
||||
}
|
||||
}
|
||||
return { dimensions: normalized, normalizedProperties: normalizedProperties.sort() };
|
||||
}
|
||||
|
||||
function utcPartitions(occurredAt: string): { event_date: string; hour: string } {
|
||||
const ts = new Date(occurredAt);
|
||||
return {
|
||||
event_date: ts.toISOString().slice(0, 10),
|
||||
hour: String(ts.getUTCHours()).padStart(2, "0"),
|
||||
};
|
||||
}
|
||||
|
||||
/** The acting user when known, else the workspace. */
|
||||
export function resolveDistinctId(config: IdentityConfig, context: PostHogEventContext | undefined): string {
|
||||
return context?.userId ?? `workspace:${config.stackId}`;
|
||||
}
|
||||
|
||||
export function buildPostHogDirectEvent(
|
||||
event: TelemetryEvent,
|
||||
context: PostHogEventContext | undefined,
|
||||
meta: PostHogDirectBatchMeta,
|
||||
config: IdentityConfig,
|
||||
): PostHogDirectEvent | null {
|
||||
const normalized = normalizeDimensions(event.name, event.dimensions ?? {});
|
||||
if (!normalized) return null;
|
||||
const eventId = deterministicEventId({
|
||||
app: meta.app,
|
||||
installId: meta.installId,
|
||||
event: { name: event.name, occurredAt: event.occurredAt, dimensions: normalized.dimensions },
|
||||
});
|
||||
const distinctId = resolveDistinctId(config, context);
|
||||
const hasPerson = Boolean(context?.userId);
|
||||
return {
|
||||
event: event.name,
|
||||
distinct_id: distinctId,
|
||||
timestamp: event.occurredAt,
|
||||
uuid: eventIdToPostHogUuid(eventId),
|
||||
disableGeoip: true,
|
||||
sendFeatureFlags: false,
|
||||
properties: {
|
||||
// Metadata keys and order match the backend loader's buildProperties().
|
||||
app: meta.app,
|
||||
schema_version: meta.schemaVersion,
|
||||
source: "client",
|
||||
deployment_source: "cloud",
|
||||
ingested_at: meta.ingestedAt,
|
||||
...utcPartitions(event.occurredAt),
|
||||
normalized_properties: normalized.normalizedProperties,
|
||||
...(meta.version ? { version: meta.version } : {}),
|
||||
...normalized.dimensions,
|
||||
// Cloud-only properties.
|
||||
stack_id: config.stackId,
|
||||
...(context?.companyId ? { company_id: context.companyId } : {}),
|
||||
...(context?.userId ? { user_id: context.userId } : {}),
|
||||
...(config.environment ? { environment: config.environment } : {}),
|
||||
...(context?.sessionId ? { $session_id: context.sessionId } : {}),
|
||||
...(context?.windowId ? { $window_id: context.windowId } : {}),
|
||||
$groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId },
|
||||
distinct_id: distinctId,
|
||||
// A workspace id must never become a person profile.
|
||||
...(hasPerson ? {} : { $process_person_profile: false }),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** The `cloud.workspace_started` event sent once per server start on Cloud. */
|
||||
export function buildWorkspaceStartedEvent(
|
||||
input: { installHash: string; occurredAt: string },
|
||||
meta: PostHogDirectBatchMeta,
|
||||
config: IdentityConfig,
|
||||
): PostHogDirectEvent {
|
||||
const distinctId = resolveDistinctId(config, undefined);
|
||||
const eventId = deterministicEventId({
|
||||
app: meta.app,
|
||||
installId: meta.installId,
|
||||
event: {
|
||||
name: CLOUD_WORKSPACE_STARTED_EVENT,
|
||||
occurredAt: input.occurredAt,
|
||||
dimensions: { stack_id: config.stackId, install_hash: input.installHash },
|
||||
},
|
||||
});
|
||||
return {
|
||||
event: CLOUD_WORKSPACE_STARTED_EVENT,
|
||||
distinct_id: distinctId,
|
||||
timestamp: input.occurredAt,
|
||||
uuid: eventIdToPostHogUuid(eventId),
|
||||
disableGeoip: true,
|
||||
sendFeatureFlags: false,
|
||||
properties: {
|
||||
app: meta.app,
|
||||
schema_version: meta.schemaVersion,
|
||||
source: "client",
|
||||
deployment_source: "cloud",
|
||||
ingested_at: meta.ingestedAt,
|
||||
...utcPartitions(input.occurredAt),
|
||||
normalized_properties: [],
|
||||
...(meta.version ? { version: meta.version } : {}),
|
||||
stack_id: config.stackId,
|
||||
install_hash: input.installHash,
|
||||
...(config.environment ? { environment: config.environment } : {}),
|
||||
$groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId },
|
||||
distinct_id: distinctId,
|
||||
$process_person_profile: false,
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
export {
|
||||
createPostHogDirectTransport,
|
||||
loadPostHogNode,
|
||||
type PostHogDirectTransport,
|
||||
type PostHogNodeClient,
|
||||
type PostHogNodeFactory,
|
||||
} from "./transport.js";
|
||||
export {
|
||||
capturePostHogEventContext,
|
||||
postHogRequestContextMiddleware,
|
||||
type PostHogEventContext,
|
||||
} from "./request-context.js";
|
||||
export { buildPostHogDirectEvent, type PostHogDirectEvent } from "./event-shape.js";
|
||||
@@ -0,0 +1,110 @@
|
||||
import { AsyncLocalStorage } from "node:async_hooks";
|
||||
import type { Request, RequestHandler } from "express";
|
||||
import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "../cloud-posthog-config.js";
|
||||
|
||||
/**
|
||||
* Request-scoped analytics context for Paperclip Cloud direct delivery.
|
||||
*
|
||||
* The store holds the live request so the acting user is read from the
|
||||
* authenticated actor when an event is tracked, whichever middleware set it.
|
||||
* The posthog-js tracing headers only link an event to a browser session and
|
||||
* window. They never identify a person and never authorize anything.
|
||||
*/
|
||||
type PostHogRequestStore = {
|
||||
req: Request;
|
||||
sessionId: string | null;
|
||||
windowId: string | null;
|
||||
// False once the response finishes. Work that outlives its request (timers,
|
||||
// background loops started during the request) must not keep attributing
|
||||
// events to that request's user or session.
|
||||
active: boolean;
|
||||
};
|
||||
|
||||
export type PostHogEventContext = {
|
||||
userId?: string;
|
||||
companyId?: string;
|
||||
sessionId?: string;
|
||||
windowId?: string;
|
||||
};
|
||||
|
||||
export const POSTHOG_SESSION_ID_HEADER = "x-posthog-session-id";
|
||||
export const POSTHOG_WINDOW_ID_HEADER = "x-posthog-window-id";
|
||||
|
||||
const storage = new AsyncLocalStorage<PostHogRequestStore>();
|
||||
const TRACING_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
|
||||
|
||||
function readTracingHeader(req: Request, name: string): string | null {
|
||||
const value = req.headers[name];
|
||||
const raw = Array.isArray(value) ? value[0] : value;
|
||||
const trimmed = raw?.trim();
|
||||
return trimmed && TRACING_ID_RE.test(trimmed) ? trimmed : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Express middleware that opens the request-scoped context. Mount it only on
|
||||
* a Cloud stack with direct delivery on; self-hosted servers never mount it,
|
||||
* so their requests carry no session context and the headers are ignored.
|
||||
*/
|
||||
export function postHogRequestContextMiddleware(): RequestHandler {
|
||||
return (req, res, next) => {
|
||||
const store: PostHogRequestStore = {
|
||||
req,
|
||||
sessionId: readTracingHeader(req, POSTHOG_SESSION_ID_HEADER),
|
||||
windowId: readTracingHeader(req, POSTHOG_WINDOW_ID_HEADER),
|
||||
active: true,
|
||||
};
|
||||
const end = () => {
|
||||
store.active = false;
|
||||
};
|
||||
res.once("finish", end);
|
||||
res.once("close", end);
|
||||
storage.run(store, next);
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The request-context middleware for this process, or null when direct
|
||||
* delivery is off (every self-hosted install, a Cloud stack without a token
|
||||
* or environment, or the PAPERCLIP_POSTHOG_DIRECT=0 kill switch).
|
||||
*/
|
||||
export function postHogRequestContextMiddlewareForEnv(
|
||||
env: Record<string, string | undefined> = process.env,
|
||||
): RequestHandler | null {
|
||||
return isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig(env)) ? postHogRequestContextMiddleware() : null;
|
||||
}
|
||||
|
||||
function actingUserId(req: Request): string | undefined {
|
||||
const actor = req.actor;
|
||||
if (!actor || actor.type !== "board" || !actor.userId) return undefined;
|
||||
// Local implicit and Cloud control actors are not a signed-in person.
|
||||
if (actor.source === "local_implicit" || actor.source === "cloud_control") return undefined;
|
||||
return actor.userId;
|
||||
}
|
||||
|
||||
/**
|
||||
* The company the request acts in, when the request itself says so: an agent
|
||||
* actor's company, the route's `:companyId`, or else the board actor's only
|
||||
* company (a Cloud stack usually has one). A board user with several companies
|
||||
* on a route without `:companyId` has no known company.
|
||||
*/
|
||||
function knownCompanyId(req: Request): string | undefined {
|
||||
if (req.actor?.companyId) return req.actor.companyId;
|
||||
const fromParams = (req.params as Record<string, unknown> | undefined)?.companyId;
|
||||
if (typeof fromParams === "string" && fromParams) return fromParams;
|
||||
const companyIds = req.actor?.companyIds;
|
||||
return companyIds?.length === 1 ? companyIds[0] : undefined;
|
||||
}
|
||||
|
||||
/** Snapshot of the current request's analytics context, taken at track time. */
|
||||
export function capturePostHogEventContext(): PostHogEventContext | undefined {
|
||||
const store = storage.getStore();
|
||||
if (!store || !store.active) return undefined;
|
||||
const context: PostHogEventContext = {};
|
||||
const userId = actingUserId(store.req);
|
||||
const companyId = knownCompanyId(store.req);
|
||||
if (userId) context.userId = userId;
|
||||
if (companyId) context.companyId = companyId;
|
||||
if (store.sessionId) context.sessionId = store.sessionId;
|
||||
if (store.windowId) context.windowId = store.windowId;
|
||||
return Object.keys(context).length > 0 ? context : undefined;
|
||||
}
|
||||
@@ -0,0 +1,211 @@
|
||||
import type {
|
||||
TelemetryOutgoingBatch,
|
||||
TelemetrySendResult,
|
||||
TelemetryTransport,
|
||||
} from "@paperclipai/shared/telemetry";
|
||||
import type { CloudPostHogConfig } from "../cloud-posthog-config.js";
|
||||
import {
|
||||
buildPostHogDirectEvent,
|
||||
buildWorkspaceStartedEvent,
|
||||
POSTHOG_WORKSPACE_GROUP_TYPE,
|
||||
type PostHogDirectEvent,
|
||||
} from "./event-shape.js";
|
||||
import { capturePostHogEventContext, type PostHogEventContext } from "./request-context.js";
|
||||
|
||||
const POSTHOG_SHUTDOWN_TIMEOUT_MS = 3_000;
|
||||
|
||||
/** The slice of the posthog-node client this transport uses. */
|
||||
export type PostHogNodeClient = {
|
||||
capture(message: {
|
||||
distinctId: string;
|
||||
event: string;
|
||||
properties?: Record<string, unknown>;
|
||||
timestamp?: Date;
|
||||
uuid?: string;
|
||||
groups?: Record<string, string>;
|
||||
disableGeoip?: boolean;
|
||||
sendFeatureFlags?: boolean;
|
||||
}): void;
|
||||
groupIdentify(message: {
|
||||
groupType: string;
|
||||
groupKey: string;
|
||||
properties?: Record<string, unknown>;
|
||||
disableGeoip?: boolean;
|
||||
}): void;
|
||||
flush(): Promise<void>;
|
||||
shutdown(shutdownTimeoutMs?: number): Promise<void> | void;
|
||||
};
|
||||
|
||||
export type PostHogNodeFactory = (config: CloudPostHogConfig) => Promise<PostHogNodeClient>;
|
||||
|
||||
/**
|
||||
* Loads posthog-node only when a Cloud stack actually sends. A self-hosted
|
||||
* server never reaches this function, so it never loads the package.
|
||||
*/
|
||||
export const loadPostHogNode: PostHogNodeFactory = async (config) => {
|
||||
const { PostHog } = await import("posthog-node");
|
||||
return new PostHog(config.token, {
|
||||
host: config.host,
|
||||
// The telemetry client already batches; send each flushed batch promptly.
|
||||
flushAt: 50,
|
||||
flushInterval: 10_000,
|
||||
disableGeoip: true,
|
||||
}) as unknown as PostHogNodeClient;
|
||||
};
|
||||
|
||||
export type WorkspaceStartup = {
|
||||
stackSlug: string | null;
|
||||
primaryHost: string | null;
|
||||
app: string;
|
||||
schemaVersion: string;
|
||||
version: string;
|
||||
installId: string;
|
||||
/**
|
||||
* sha256 hex of the raw install id: the same canonical install_id the
|
||||
* telemetry backend computes. Not secret. An offline operator job derives
|
||||
* the pre-switch PostHog id from it, so history stays joinable. Sent only on
|
||||
* `cloud.workspace_started`, never on the group or on ordinary events.
|
||||
*/
|
||||
installHash: string;
|
||||
};
|
||||
|
||||
export type PostHogDirectTransport = TelemetryTransport & {
|
||||
/** Sends `$groupidentify` and `cloud.workspace_started` for this start. */
|
||||
announceWorkspace(startup: WorkspaceStartup): Promise<void>;
|
||||
shutdown(): Promise<void>;
|
||||
};
|
||||
|
||||
export function createPostHogDirectTransport(
|
||||
config: CloudPostHogConfig,
|
||||
options: { factory?: PostHogNodeFactory; now?: () => Date } = {},
|
||||
): PostHogDirectTransport {
|
||||
const factory = options.factory ?? loadPostHogNode;
|
||||
const now = options.now ?? (() => new Date());
|
||||
let clientPromise: Promise<PostHogNodeClient> | null = null;
|
||||
let pendingAnnouncement: { startup: WorkspaceStartup; occurredAt: string } | null = null;
|
||||
|
||||
const getClient = () => {
|
||||
clientPromise ??= factory(config).catch((error) => {
|
||||
clientPromise = null;
|
||||
throw error;
|
||||
});
|
||||
return clientPromise;
|
||||
};
|
||||
|
||||
const capture = (client: PostHogNodeClient, message: PostHogDirectEvent) => {
|
||||
client.capture({
|
||||
distinctId: message.distinct_id,
|
||||
event: message.event,
|
||||
properties: message.properties,
|
||||
timestamp: new Date(message.timestamp),
|
||||
uuid: message.uuid,
|
||||
// posthog-node rebuilds `$groups` from this option and drops a `$groups`
|
||||
// property passed without it.
|
||||
groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId },
|
||||
disableGeoip: message.disableGeoip,
|
||||
sendFeatureFlags: message.sendFeatureFlags,
|
||||
});
|
||||
};
|
||||
|
||||
// Group properties need PostHog's group analytics add-on. Send them anyway;
|
||||
// the history join relies on the plain event below. Both go straight to
|
||||
// posthog-node: TelemetryClient.track() accepts only generated contract
|
||||
// events, and these are Cloud-only.
|
||||
function captureAnnouncement(
|
||||
client: PostHogNodeClient,
|
||||
{ startup, occurredAt }: { startup: WorkspaceStartup; occurredAt: string },
|
||||
) {
|
||||
client.groupIdentify({
|
||||
groupType: POSTHOG_WORKSPACE_GROUP_TYPE,
|
||||
groupKey: config.stackId,
|
||||
disableGeoip: true,
|
||||
properties: {
|
||||
stack_slug: startup.stackSlug,
|
||||
primary_host: startup.primaryHost,
|
||||
environment: config.environment,
|
||||
},
|
||||
});
|
||||
capture(
|
||||
client,
|
||||
buildWorkspaceStartedEvent(
|
||||
{ installHash: startup.installHash, occurredAt },
|
||||
{
|
||||
app: startup.app,
|
||||
schemaVersion: startup.schemaVersion,
|
||||
installId: startup.installId,
|
||||
version: startup.version,
|
||||
ingestedAt: occurredAt,
|
||||
},
|
||||
config,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
return {
|
||||
hashesPrivateRefs: false,
|
||||
|
||||
captureEventContext: () => capturePostHogEventContext(),
|
||||
|
||||
async send(batch: TelemetryOutgoingBatch): Promise<TelemetrySendResult> {
|
||||
const meta = {
|
||||
app: batch.app,
|
||||
schemaVersion: batch.schemaVersion,
|
||||
installId: batch.installId,
|
||||
version: batch.version,
|
||||
ingestedAt: now().toISOString(),
|
||||
};
|
||||
const messages = batch.events
|
||||
.map(({ event, context }) =>
|
||||
buildPostHogDirectEvent(event, context as PostHogEventContext | undefined, meta, config),
|
||||
)
|
||||
.filter((message): message is PostHogDirectEvent => message !== null);
|
||||
if (messages.length === 0) return { kind: "ok" };
|
||||
|
||||
let client: PostHogNodeClient;
|
||||
try {
|
||||
client = await getClient();
|
||||
} catch {
|
||||
// The package could not load. Retrying with backoff is safe: nothing
|
||||
// was captured yet, so no event can be sent twice.
|
||||
return { kind: "network" };
|
||||
}
|
||||
// A startup announcement that could not load the client goes out with
|
||||
// the first batch that can, so the history-join event is not lost.
|
||||
if (pendingAnnouncement) {
|
||||
const announcement = pendingAnnouncement;
|
||||
pendingAnnouncement = null;
|
||||
captureAnnouncement(client, announcement);
|
||||
}
|
||||
for (const message of messages) capture(client, message);
|
||||
try {
|
||||
await client.flush();
|
||||
} catch {
|
||||
// posthog-node already retried this request. It keeps events that hit
|
||||
// a network failure queued for its next flush and drops ones PostHog
|
||||
// rejected, so resending them from here could only duplicate events.
|
||||
console.warn(`[telemetry] PostHog flush failed for a batch of ${messages.length} event(s)`);
|
||||
}
|
||||
return { kind: "ok" };
|
||||
},
|
||||
|
||||
async announceWorkspace(startup: WorkspaceStartup): Promise<void> {
|
||||
const announcement = { startup, occurredAt: now().toISOString() };
|
||||
let client: PostHogNodeClient;
|
||||
try {
|
||||
client = await getClient();
|
||||
} catch (error) {
|
||||
pendingAnnouncement = announcement;
|
||||
throw error;
|
||||
}
|
||||
captureAnnouncement(client, announcement);
|
||||
await client.flush();
|
||||
},
|
||||
|
||||
async shutdown(): Promise<void> {
|
||||
if (!clientPromise) return;
|
||||
const client = await clientPromise.catch(() => null);
|
||||
if (!client) return;
|
||||
await client.shutdown(POSTHOG_SHUTDOWN_TIMEOUT_MS);
|
||||
},
|
||||
};
|
||||
}
|
||||
+86
-2
@@ -1,17 +1,70 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import path from "node:path";
|
||||
import {
|
||||
TelemetryClient,
|
||||
type TelemetryConfig,
|
||||
type TelemetryState,
|
||||
resolveTelemetryConfig,
|
||||
loadOrCreateState,
|
||||
trackServerStarted,
|
||||
} from "@paperclipai/shared/telemetry";
|
||||
import { resolvePaperclipInstanceRoot } from "./home-paths.js";
|
||||
import { serverVersion } from "./version.js";
|
||||
import { getCloudStackContext } from "./services/cloud-instance.js";
|
||||
import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "./services/cloud-posthog-config.js";
|
||||
import {
|
||||
createPostHogDirectTransport,
|
||||
type PostHogDirectTransport,
|
||||
type PostHogNodeFactory,
|
||||
} from "./services/posthog-direct/index.js";
|
||||
|
||||
let client: TelemetryClient | null = null;
|
||||
let directTransport: PostHogDirectTransport | null = null;
|
||||
let initializationFailed = false;
|
||||
|
||||
export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClient | null {
|
||||
export type InitTelemetryOptions = {
|
||||
env?: Record<string, string | undefined>;
|
||||
/** Test seam for the posthog-node client. */
|
||||
postHogFactory?: PostHogNodeFactory;
|
||||
};
|
||||
|
||||
/**
|
||||
* Picks the one sender for this process. Self-hosted installs (and Cloud
|
||||
* stacks without a PostHog token, or with PAPERCLIP_POSTHOG_DIRECT=0) keep the
|
||||
* collector. A Cloud stack with a token sends every batch straight to PostHog.
|
||||
*/
|
||||
function resolveDirectTransport(
|
||||
options: InitTelemetryOptions,
|
||||
telemetry: TelemetryConfig,
|
||||
getState: () => TelemetryState,
|
||||
): PostHogDirectTransport | null {
|
||||
const env = options.env ?? process.env;
|
||||
const config = resolveCloudPostHogConfig(env);
|
||||
// Every direct event must carry an environment; without one keep the collector.
|
||||
if (!isPostHogDirectDeliveryEnabled(config)) return null;
|
||||
const transport = createPostHogDirectTransport(config, { factory: options.postHogFactory });
|
||||
const stack = getCloudStackContext(env);
|
||||
const { installId } = getState();
|
||||
void transport
|
||||
.announceWorkspace({
|
||||
stackSlug: stack?.stackSlug ?? null,
|
||||
primaryHost: stack?.primaryHost ?? null,
|
||||
app: telemetry.app ?? "paperclip",
|
||||
schemaVersion: telemetry.schemaVersion ?? "1",
|
||||
version: serverVersion,
|
||||
installId,
|
||||
installHash: createHash("sha256").update(installId).digest("hex"),
|
||||
})
|
||||
.catch(() => {
|
||||
console.warn("[telemetry] Could not announce the workspace to PostHog.");
|
||||
});
|
||||
return transport;
|
||||
}
|
||||
|
||||
export function initTelemetry(
|
||||
fileConfig?: { enabled?: boolean },
|
||||
options: InitTelemetryOptions = {},
|
||||
): TelemetryClient | null {
|
||||
if (client || initializationFailed) return client;
|
||||
|
||||
const config = resolveTelemetryConfig(fileConfig);
|
||||
@@ -20,14 +73,20 @@ export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClie
|
||||
let pendingClient: TelemetryClient | null = null;
|
||||
try {
|
||||
const stateDir = path.join(resolvePaperclipInstanceRoot(), "telemetry");
|
||||
let state: TelemetryState | null = null;
|
||||
const getState = () => (state ??= loadOrCreateState(stateDir, serverVersion));
|
||||
const transport = resolveDirectTransport(options, config, getState);
|
||||
pendingClient = new TelemetryClient(
|
||||
config,
|
||||
() => loadOrCreateState(stateDir, serverVersion),
|
||||
getState,
|
||||
serverVersion,
|
||||
Math.random,
|
||||
transport ?? undefined,
|
||||
);
|
||||
trackServerStarted(pendingClient, { os_platform: process.platform });
|
||||
pendingClient.startPeriodicFlush(60_000);
|
||||
client = pendingClient;
|
||||
directTransport = transport;
|
||||
return client;
|
||||
} catch {
|
||||
pendingClient?.stop();
|
||||
@@ -40,3 +99,28 @@ export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClie
|
||||
export function getTelemetryClient(): TelemetryClient | null {
|
||||
return client;
|
||||
}
|
||||
|
||||
/** Whether this process sends telemetry straight to PostHog (Cloud only). */
|
||||
export function isPostHogDirectTelemetryActive(): boolean {
|
||||
return directTransport !== null;
|
||||
}
|
||||
|
||||
/** Stops timers, sends queued events, then closes the PostHog client if any. */
|
||||
export async function shutdownTelemetry(): Promise<void> {
|
||||
const current = client;
|
||||
if (!current) return;
|
||||
current.stop();
|
||||
try {
|
||||
await current.flush();
|
||||
} finally {
|
||||
await directTransport?.shutdown();
|
||||
}
|
||||
}
|
||||
|
||||
/** Test-only: forget the process-wide client. */
|
||||
export function resetTelemetryForTests(): void {
|
||||
client?.stop();
|
||||
client = null;
|
||||
directTransport = null;
|
||||
initializationFailed = false;
|
||||
}
|
||||
@@ -351,15 +351,15 @@
|
||||
"packages/shared/src/slack-tools.ts": "c53a75cd3099c6d8dcd1475e755aae589d4c88f6",
|
||||
"packages/shared/src/subscriptions.ts": "ef70e63395ca967bbc30776b71560e96eb354a75",
|
||||
"packages/shared/src/summary-slot.test.ts": "5f8e222dea425f0d5bff0adb5c683087bd7cf7fb",
|
||||
"packages/shared/src/telemetry/README.md": "28125b5ab542abc46c4bb6c044636a093f13584f",
|
||||
"packages/shared/src/telemetry/README.md": "50ae8992b33c4141de443d42c57de24357e3d0aa",
|
||||
"packages/shared/src/telemetry/client-types.test.ts": "3b630edda4972b929ba4decd7457f226eb9cfc5b",
|
||||
"packages/shared/src/telemetry/client.test.ts": "3ba900cdab5a1ac1dcc1dcea382bb790af32d895",
|
||||
"packages/shared/src/telemetry/client.ts": "03a10a5550b542487543fbfd4a417e6eb316e11e",
|
||||
"packages/shared/src/telemetry/client.test.ts": "5a95f2305a393c5b2e7750b10e0ed65da0f30cf8",
|
||||
"packages/shared/src/telemetry/client.ts": "d6534ce8aaa6f69fb2dd03e12487db024e250a96",
|
||||
"packages/shared/src/telemetry/config.ts": "dfcd4d692cc06e71cb77f70b44fc05721eb330d1",
|
||||
"packages/shared/src/telemetry/connector-events.test.ts": "c060017c7a6a26e67aea56e5c9e36059be527070",
|
||||
"packages/shared/src/telemetry/events.ts": "78f2031313fb9c82412b7a5ec6facf1d1a935300",
|
||||
"packages/shared/src/telemetry/events.ts": "5a8bd387ad993db1b9dcbd0919200edb58eb68bd",
|
||||
"packages/shared/src/telemetry/generated/paperclip-telemetry.ts": "b44d37d34283fefa4fba8e9ac4d87682ba694926",
|
||||
"packages/shared/src/telemetry/index.ts": "d6436ffd5ba9463d45c5500b7c4847f51679d170",
|
||||
"packages/shared/src/telemetry/index.ts": "39ba76a46c323a30e40c0590dcbc31edebefbe9a",
|
||||
"packages/shared/src/telemetry/readme-contract.test.ts": "eec9d4511ddc3085a9af1a2dab6bf8487e49dfd7",
|
||||
"packages/shared/src/telemetry/retention.test.ts": "9d54db1371bf20f22b8d2f8373f84433107a7408",
|
||||
"packages/shared/src/telemetry/retention.ts": "023004d4e49f52cfb6fa8c7d32e674640704ebb4",
|
||||
|
||||
Reference in new issue
Block a user