Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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/simport { 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();}