Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

web: add OTel logs for presence tracking (live viewer avatars) (#7231)

Wolf Mermelstein8d87bcc98e5b
diff --git a/apps/web/src/lib/core/state/liveIndicators.ts b/apps/web/src/lib/core/state/liveIndicators.ts
index c54eddc862..9f52ce1632 100644
--- a/apps/web/src/lib/core/state/liveIndicators.ts
+++ b/apps/web/src/lib/core/state/liveIndicators.ts
@@ -1,5 +1,9 @@
import { ENABLE_LIVE_INDICATORS } from '@core/constant/featureFlags';
import { createWebsocketEventEffect } from '@macro-inc/collaboration/websocket';
+import {
+ reportInvalidTrackingChange,
+ reportTrackingChange,
+} from '@service-connection/presence-telemetry';
import { type FromWebsocketMessage, ws } from '@service-connection/websocket';
import type { Accessor } from 'solid-js';
import { createStore, unwrap } from 'solid-js/store';
@@ -20,10 +24,25 @@ createWebsocketEventEffect(
'user_tracking_change',
(data: FromWebsocketMessage) => {
if (!ENABLE_LIVE_INDICATORS) return;
- const update = trackingUpdate.parse(JSON.parse(data.data));
+ let update: z.infer<typeof trackingUpdate>;
+ try {
+ update = trackingUpdate.parse(JSON.parse(data.data));
+ } catch (error) {
+ reportInvalidTrackingChange(error);
+ return;
+ }
+ const previous = unwrap(indicatorStore[update.entity_id]);
+ if (!sameUsers(previous, update.user_ids))
+ reportTrackingChange(update, update.user_ids, previous);
setIndicatorStore(update.entity_id, update.user_ids);
}
);
+
+function sameUsers(previous: string[] | undefined, next: string[]) {
+ if (previous?.length !== next.length) return false;
+ const nextSet = new Set(next);
+ return previous.every((id) => nextSet.has(id));
+}
export const useUserIndicators = (entityId: Accessor<string>) => {
if (!ENABLE_LIVE_INDICATORS) return () => [];
const indicators = () => unwrap(indicatorStore[entityId()]);
diff --git a/apps/web/src/lib/queries/messages/tests/subscription.test.ts b/apps/web/src/lib/queries/messages/tests/subscription.test.ts
index 8318add5c0..8e4d73548d 100644
--- a/apps/web/src/lib/queries/messages/tests/subscription.test.ts
+++ b/apps/web/src/lib/queries/messages/tests/subscription.test.ts
@@ -19,8 +19,12 @@ const mocks = await vi.hoisted(async () => {
invalidate: vi.fn().mockResolvedValue(undefined),
updates: new Set<(event: unknown) => void>(),
reconnects: new Set<() => void>(),
+ warn: vi.fn(),
};
});
+vi.mock('@macro-inc/observability', () => ({
+ Telemetry: { info: vi.fn(), warn: mocks.warn, error: vi.fn() },
+}));
vi.mock('@core/signal/tabFocus', () => ({ isTabFocused: mocks.focused }));
vi.mock('@service-connection/stream', () => ({
clearStream: mocks.clearStream,
@@ -193,6 +197,32 @@ it('suspends the shared heartbeat in a background tab', () => {
expect(sent('ping')).toHaveLength(1);
});
+it('reports a presence lapse once per unfocused absence past the gateway window', () => {
+ mount(useRefreshTrackedEntitiesOnFocus);
+ mountBlock();
+ const lapses = () =>
+ mocks.warn.mock.calls.filter(
+ ([name]) => name === 'presence.heartbeat_lapsed'
+ );
+
+ mocks.setFocused(false);
+ vi.advanceTimersByTime(40_000);
+ expect(lapses()).toHaveLength(0);
+ vi.advanceTimersByTime(40_000);
+ expect(lapses()).toHaveLength(1);
+ expect(lapses()[0][1]).toMatchObject({
+ 'presence.entity_id': parent.id,
+ 'presence.lapsed_ms': 60_000,
+ });
+ vi.advanceTimersByTime(60_000);
+ expect(lapses()).toHaveLength(1);
+
+ mocks.setFocused(true);
+ mocks.setFocused(false);
+ vi.advanceTimersByTime(60_000);
+ expect(lapses()).toHaveLength(2);
+});
+
it('pings on refocus and refreshes only views left unseen past the gateway window', () => {
mount(useRefreshTrackedEntitiesOnFocus);
mount(() =>
diff --git a/apps/web/src/lib/service-clients/service-connection/client.ts b/apps/web/src/lib/service-clients/service-connection/client.ts
index 24c67082be..605d23d510 100644
--- a/apps/web/src/lib/service-clients/service-connection/client.ts
+++ b/apps/web/src/lib/service-clients/service-connection/client.ts
@@ -11,6 +11,12 @@ import {
} from 'solid-js';
import type { TrackEntityMessage } from './generated/schemas/trackEntityMessage';
+import {
+ reportHeartbeatLapse,
+ reportHeartbeatResumed,
+ reportReopenOnReconnect,
+ reportTrack,
+} from './presence-telemetry';
import { clearStream } from './stream';
import { ws } from './websocket';
@@ -23,6 +29,7 @@ interface TrackedEntity {
heartbeat: ReturnType<typeof setInterval>;
/** When this tab last told the gateway it is watching, by `open` or `ping`. */
lastSeen: number;
+ lapseReported: boolean;
refreshCallbacks: Map<EntityRefresh, number>;
}
const trackedEntities: Map<EntityId, TrackedEntity> = new Map();
@@ -50,13 +57,18 @@ export const connectionGatewayClient = {
...args,
action: 'ping',
});
+ else reportLapseOnce(args);
}, 20_000),
lastSeen: Date.now(),
+ lapseReported: false,
refreshCallbacks: new Map(),
});
}
} else if (args.action === 'ping') {
- if (tracked) tracked.lastSeen = Date.now();
+ if (tracked) {
+ tracked.lastSeen = Date.now();
+ tracked.lapseReported = false;
+ }
} else if (args.action === 'close') {
if (!tracked) return ok({});
else if (tracked.count > 1) {
@@ -68,6 +80,7 @@ export const connectionGatewayClient = {
clearStream(args.entity_id);
}
}
+ if (args.action !== 'ping') reportTrack(args, args.action, isSocketOpen());
ws.send({
type: 'track_entity',
...args,
@@ -76,6 +89,24 @@ export const connectionGatewayClient = {
},
};
+// The underlying socket is unassigned until the first URL resolves.
+const isSocketOpen = () => {
+ try {
+ return ws.readyState === WebSocket.OPEN;
+ } catch {
+ return false;
+ }
+};
+
+function reportLapseOnce(entity: EntityTarget) {
+ const tracked = trackedEntities.get(entity.entity_id);
+ if (!tracked || tracked.lapseReported) return;
+ const lapsedMs = Date.now() - tracked.lastSeen;
+ if (lapsedMs < GATEWAY_ACTIVITY_WINDOW_MS) return;
+ tracked.lapseReported = true;
+ reportHeartbeatLapse(entity, lapsedMs);
+}
+
/** Share tracking and heartbeats; refresh once on subscription, reconnect, and refocus after a long absence. */
export function useEntitySubscription(
entity: Accessor<EntityTarget | undefined>,
@@ -118,6 +149,7 @@ export function useEntitySubscription(
*/
export function useReopenTrackedEntitiesOnReconnect(): void {
createReconnectEffect(ws, () => {
+ reportReopenOnReconnect(trackedEntities.size);
for (const [entity_id, tracked] of trackedEntities) {
const entity = { entity_id, entity_type: tracked.entityType };
ws.send({
@@ -146,8 +178,9 @@ export function useRefreshTrackedEntitiesOnFocus(): void {
const now = Date.now();
for (const [entity_id, tracked] of trackedEntities) {
const entity = { entity_id, entity_type: tracked.entityType };
- const missedEvents =
- now - tracked.lastSeen >= GATEWAY_ACTIVITY_WINDOW_MS;
+ const pausedMs = now - tracked.lastSeen;
+ const missedEvents = pausedMs >= GATEWAY_ACTIVITY_WINDOW_MS;
+ if (missedEvents) reportHeartbeatResumed(entity, pausedMs);
void connectionGatewayClient.trackEntity({
...entity,
action: 'ping',
diff --git a/apps/web/src/lib/service-clients/service-connection/presence-telemetry.ts b/apps/web/src/lib/service-clients/service-connection/presence-telemetry.ts
new file mode 100644
index 0000000000..07136f0ec1
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-connection/presence-telemetry.ts
@@ -0,0 +1,98 @@
+import {
+ type Websocket,
+ WebsocketEvent,
+} from '@macro-inc/collaboration/websocket';
+import { Telemetry } from '@macro-inc/observability';
+import type { TrackEntityMessage } from './generated/schemas/trackEntityMessage';
+
+/** Socket lifecycle; a socket that stops retrying drops the user from every entity's presence. */
+export function instrumentGatewaySocket(ws: Websocket<any, any>) {
+ ws.addEventListener(WebsocketEvent.Close, (_, event) => {
+ Telemetry.warn('connection_gateway.ws.close', {
+ 'ws.close_code': event.code,
+ 'ws.close_reason': event.reason,
+ 'ws.was_clean': event.wasClean,
+ });
+ });
+ ws.addEventListener(WebsocketEvent.Reconnect, (_, event) => {
+ Telemetry.info('connection_gateway.ws.reconnect', {
+ 'ws.retries': event.detail.retries,
+ });
+ });
+ ws.addEventListener(WebsocketEvent.retry, (instance, event) => {
+ if (
+ instance.maxRetries === undefined ||
+ event.detail.retries < instance.maxRetries
+ )
+ return;
+ Telemetry.error('connection_gateway.ws.final_retry', {
+ 'ws.retries': event.detail.retries,
+ 'ws.max_retries': instance.maxRetries,
+ });
+ });
+}
+
+type EntityTarget = { entity_id: string; entity_type: string };
+
+const entityAttributes = (entity: EntityTarget) => ({
+ 'presence.entity_type': entity.entity_type,
+ 'presence.entity_id': entity.entity_id,
+});
+
+/** An `open` or `close` actually sent to the gateway (pings are too frequent to log). */
+export function reportTrack(
+ entity: EntityTarget,
+ action: TrackEntityMessage['action'],
+ socketOpen: boolean
+) {
+ Telemetry.info('presence.track', {
+ ...entityAttributes(entity),
+ 'presence.action': action,
+ 'presence.socket_open': socketOpen,
+ });
+}
+
+/**
+ * The heartbeat was skipped long enough that the gateway no longer counts this
+ * tab as viewing the entity, so other viewers stop seeing this user.
+ */
+export function reportHeartbeatLapse(entity: EntityTarget, lapsedMs: number) {
+ Telemetry.warn('presence.heartbeat_lapsed', {
+ ...entityAttributes(entity),
+ 'presence.lapsed_ms': lapsedMs,
+ 'presence.visibility_state': document.visibilityState,
+ 'presence.has_focus': document.hasFocus(),
+ });
+}
+
+export function reportHeartbeatResumed(entity: EntityTarget, pausedMs: number) {
+ Telemetry.info('presence.heartbeat_resumed', {
+ ...entityAttributes(entity),
+ 'presence.paused_ms': pausedMs,
+ });
+}
+
+export function reportReopenOnReconnect(entityCount: number) {
+ Telemetry.info('presence.reopen_on_reconnect', {
+ 'presence.entity_count': entityCount,
+ });
+}
+
+export function reportTrackingChange(
+ entity: EntityTarget,
+ userIds: string[],
+ previousUserIds: string[] | undefined
+) {
+ Telemetry.info('presence.tracking_change', {
+ ...entityAttributes(entity),
+ 'presence.user_ids': userIds,
+ 'presence.user_count': userIds.length,
+ 'presence.previous_user_count': previousUserIds?.length,
+ });
+}
+
+export function reportInvalidTrackingChange(error: unknown) {
+ Telemetry.warn('presence.tracking_change_invalid', {
+ 'presence.error': error instanceof Error ? error.message : String(error),
+ });
+}
diff --git a/apps/web/src/lib/service-clients/service-connection/websocket.ts b/apps/web/src/lib/service-clients/service-connection/websocket.ts
index 06666e847b..6092aa958e 100644
--- a/apps/web/src/lib/service-clients/service-connection/websocket.ts
+++ b/apps/web/src/lib/service-clients/service-connection/websocket.ts
@@ -14,6 +14,7 @@ import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/s
import { getMacroApiToken } from '@service-auth/fetch';
import { createCallback } from '@solid-primitives/rootless';
import type { ToWebsocketMessage } from './generated/schemas/toWebsocketMessage';
+import { instrumentGatewaySocket } from './presence-telemetry';
export { parseWebsocketPayload } from './websocket-payload';
@@ -56,6 +57,8 @@ export const ws = new WebsocketBuilder(resolveWsUrl)
})
.build();
+instrumentGatewaySocket(ws);
+
function reconnectIfDisconnected() {
ws.reconnectIfDisconnected();
}