@dxos/plugin-observability 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/capabilities/client-ready.ts

@@ -2,97 +2,105 @@
 // Copyright 2025 DXOS.org
 //
 
-import {
-  Capabilities,
-  LayoutAction,
-  type PluginContext,
-  SettingsAction,
-  contributes,
-  createIntent,
-} from '@dxos/app-framework';
-import { type Observability, setupTelemetryListeners } from '@dxos/observability';
+import * as Effect from 'effect/Effect';
 
-import { meta } from '../meta';
-import { ObservabilityAction } from '../types';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
+import { log } from '@dxos/log';
+import { type Observability, ObservabilityProvider } from '@dxos/observability';
 
-import { ClientCapability, ObservabilityCapabilities } from './capabilities';
+import { meta } from '#meta';
+import { ObservabilityCapabilities, ObservabilityOperation } from '#types';
 
-type ClientReadyOptions = {
-  context: PluginContext;
+export type ClientReadyOptions = {
   namespace: string;
-  observability: Observability;
+  observability: Observability.Observability;
 };
 
-export default async ({ context, namespace, observability }: ClientReadyOptions) => {
-  const manager = context.getCapability(Capabilities.PluginManager);
-  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-  const state = context.getCapability(ObservabilityCapabilities.State);
-  const client = context.getCapability(ClientCapability);
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ observability }: ClientReadyOptions) {
+    const manager = yield* Capability.get(Capabilities.PluginManager);
+    const { invokePromise } = yield* Capability.get(Capabilities.OperationInvoker);
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const stateAtom = yield* Capability.get(ObservabilityCapabilities.State);
+    const client = yield* Capability.get(ObservabilityCapabilities.ClientCapability);
 
-  const sendPrivacyNotice = async () => {
-    const environment = client?.config?.values.runtime?.app?.env?.DX_ENVIRONMENT;
-    const notify =
-      environment && environment !== 'ci' && !environment.endsWith('.local') && !environment.endsWith('.lan');
-    if (!state.notified && notify) {
-      await dispatch(
-        createIntent(LayoutAction.AddToast, {
-          part: 'toast',
-          subject: {
-            id: `${meta.id}/notice`,
-            title: ['observability toast label', { ns: meta.id }],
-            description: ['observability toast description', { ns: meta.id }],
-            duration: Infinity,
-            icon: 'ph--info--regular',
-            actionLabel: ['observability toast action label', { ns: meta.id }],
-            actionAlt: ['observability toast action alt', { ns: meta.id }],
-            closeLabel: ['observability toast close label', { ns: meta.id }],
-            onAction: () => dispatch(createIntent(SettingsAction.Open, { plugin: meta.id })),
-          },
-        }),
-      );
+    const sendPrivacyNotice = async () => {
+      const environment = client?.config?.values.runtime?.app?.env?.DX_ENVIRONMENT;
+      const notify =
+        environment && environment !== 'ci' && !environment.endsWith('.local') && !environment.endsWith('.lan');
+      const state = registry.get(stateAtom);
+      if (!state.notified && notify) {
+        await invokePromise(LayoutOperation.AddToast, {
+          id: `${meta.id}.notice`,
+          title: ['observability-toast.label', { ns: meta.id }],
+          description: ['observability-toast.description', { ns: meta.id }],
+          duration: Infinity,
+          icon: 'ph--info--regular',
+          actionLabel: ['observability-toast-action.label', { ns: meta.id }],
+          actionAlt: ['observability-toast-action.alt', { ns: meta.id }],
+          closeLabel: ['observability-toast-close.label', { ns: meta.id }],
+          onAction: () => invokePromise(SettingsOperation.Open, { plugin: meta.id }),
+        });
 
-      state.notified = true;
+        registry.set(stateAtom, { ...registry.get(stateAtom), notified: true });
+      }
+    };
+
+    // Ensure errors are tagged with enabled plugins to help with reproductions.
+    const enabledPlugins = manager.getEnabled();
+    log('client-ready: tagging enabled plugins', { count: enabledPlugins.length });
+    for (const plugin of enabledPlugins) {
+      observability.setTags({ [`pluginEnabled-${plugin}`]: 'true' }, 'errors');
     }
-  };
 
-  // Ensure errors are tagged with enabled plugins to help with reproductions.
-  manager.enabled.map((plugin) => observability?.setTag(`pluginEnabled-${plugin}`, 'true', 'errors'));
+    log('client-ready: sending page.load event');
+    yield* Effect.tryPromise(() =>
+      invokePromise(ObservabilityOperation.SendEvent, {
+        name: 'page.load',
+        properties: {
+          // TODO(wittjosiah): These apis are deprecated. Is there a better way to find this information?
+          loadDuration: window.performance.timing.loadEventEnd - window.performance.timing.loadEventStart,
+        },
+      }),
+    );
+    log('client-ready: page.load event sent');
 
-  await dispatch(
-    createIntent(ObservabilityAction.SendEvent, {
-      name: 'page.load',
-      properties: {
-        // TODO(wittjosiah): These apis are deprecated. Is there a better way to find this information?
-        loadDuration: window.performance.timing.loadEventEnd - window.performance.timing.loadEventStart,
-      },
-    }),
-  );
+    // Each provider is logged individually because some provider setups perform
+    // RPC calls (e.g. runtimeMetricsProvider awaits SystemService.getPlatform());
+    // a hung worker pipe surfaces as a missing "added" log, so the last
+    // "adding ..." line points to the stall.
+    log('client-ready: adding identity data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.identityProvider(client.services.services));
+    log('client-ready: identity data provider added');
 
-  // Start client observability (i.e. not running as shared worker)
-  // TODO(nf): how to prevent multiple instances for single shared worker?
-  const cleanup = setupTelemetryListeners(namespace, client, observability);
+    log('client-ready: adding network metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.networkMetricsProvider(client.services.services));
+    log('client-ready: network metrics data provider added');
 
-  await Promise.all([
-    observability.setIdentityTags(client.services.services),
-    observability.startRuntimeMetrics(client),
-    observability.startNetworkMetrics(client.services.services),
-    observability.startSpacesMetrics(client, namespace),
-  ]);
+    log('client-ready: adding runtime metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.runtimeMetricsProvider(client.services.services));
+    log('client-ready: runtime metrics data provider added');
 
-  if (client.halo.identity.get()) {
-    await sendPrivacyNotice();
-  } else {
-    const subscription = client.halo.identity.subscribe(async (identity) => {
-      if (identity && observability) {
-        await sendPrivacyNotice();
-        await observability.setIdentityTags(client.services.services);
-        subscription.unsubscribe();
-      }
-    });
-  }
+    log('client-ready: adding space metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.spacesMetricsProvider(client));
+    log('client-ready: space metrics data provider added');
 
-  return contributes(ObservabilityCapabilities.Observability, observability, async () => {
-    cleanup();
-    await observability.close();
-  });
-};
+    if (client.halo.identity.get()) {
+      log('client-ready: identity present, sending privacy notice');
+      yield* Effect.tryPromise(() => sendPrivacyNotice());
+      log('client-ready: privacy notice sent');
+    } else {
+      log('client-ready: no identity, deferring privacy notice');
+      const subscription = client.halo.identity.subscribe(async (identity) => {
+        if (identity && observability) {
+          await sendPrivacyNotice();
+          subscription.unsubscribe();
+        }
+      });
+    }
+
+    log('client-ready: contributing observability capability');
+    return Capability.contributes(ObservabilityCapabilities.Observability, observability, () => observability.close());
+  }),
+);

package/src/capabilities/index.ts

@@ -2,13 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { lazy } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
 
-export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
-export const ClientReady = lazy(() => import('./client-ready'));
-export const IntentResolver = lazy(() => import('./intent-resolver'));
-export const ReactSurface = lazy(() => import('./react-surface'));
-export const ObservabilitySettings = lazy(() => import('./settings'));
-export const ObservabilityState = lazy(() => import('./state'));
+import type { ClientReadyOptions } from './client-ready';
 
-export * from './capabilities';
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const ClientReady = Capability.lazy<ClientReadyOptions>('ClientReady', () => import('./client-ready'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const ObservabilitySettings = Capability.lazy('ObservabilitySettings', () => import('./settings'));
+export const ObservabilityState = Capability.lazy('ObservabilityState', () => import('./state'));

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { ObservabilityOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, ObservabilityOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -2,26 +2,34 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
-import { SettingsStore } from '@dxos/local-storage';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface, useOperationInvoker, useSettingsState } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { HelpContainer, ObservabilitySettings, type ObservabilitySettingsProps } from '../components';
-import { meta } from '../meta';
+import { ObservabilitySettings } from '#components';
+import { meta } from '#meta';
+import { ObservabilityOperation } from '#types';
+import { type Settings } from '#types';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: meta.id,
-      role: 'article',
-      filter: (data): data is { subject: SettingsStore<ObservabilitySettingsProps> } =>
-        data.subject instanceof SettingsStore && data.subject.prefix === meta.id,
-      component: ({ data: { subject } }) => <ObservabilitySettings settings={subject.value} />,
-    }),
-    createSurface({
-      id: `${meta.id}/help`,
-      role: 'deck-companion--help',
-      component: () => <HelpContainer />,
-    }),
-  ]);
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'root',
+        filter: AppSurface.settings(AppSurface.Article, meta.id),
+        component: ({ data: { subject } }) => {
+          const { settings } = useSettingsState<Settings.Settings>(subject.atom);
+          const { invokePromise } = useOperationInvoker();
+          const handleSettingsChange = (cb: (current: Settings.Settings) => Settings.Settings) => {
+            const next = cb(settings);
+            void invokePromise(ObservabilityOperation.Toggle, { state: next.enabled });
+          };
+          return <ObservabilitySettings settings={settings} onSettingsChange={handleSettingsChange} />;
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings.ts

@@ -2,20 +2,32 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes } from '@dxos/app-framework';
-import { live } from '@dxos/live-object';
+import * as Effect from 'effect/Effect';
 
-import { type ObservabilitySettingsProps, ObservabilitySettingsSchema } from '../components';
-import { meta } from '../meta';
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
 
-export default () => {
-  const settings = live<ObservabilitySettingsProps>({
-    enabled: true,
-  });
+import { meta } from '#meta';
+import { ObservabilityCapabilities, Settings } from '#types';
 
-  return contributes(Capabilities.Settings, {
-    prefix: meta.id,
-    schema: ObservabilitySettingsSchema,
-    value: settings,
-  });
-};
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: Settings.Settings,
+      defaultValue: () => ({
+        enabled: true,
+      }),
+    });
+
+    return [
+      Capability.contributes(ObservabilityCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: Settings.Settings,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/state.ts

@@ -2,21 +2,28 @@
 // Copyright 2025 DXOS.org
 //
 
-import { contributes } from '@dxos/app-framework';
-import { LocalStorageStore } from '@dxos/local-storage';
-import { getObservabilityGroup } from '@dxos/observability';
+import * as Effect from 'effect/Effect';
 
-import { meta } from '../meta';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
+import { Observability } from '@dxos/observability';
 
-import { ObservabilityCapabilities } from './capabilities';
+import { meta } from '#meta';
+import { ObservabilityCapabilities } from '#types';
 
-export default async ({ namespace }: { namespace: string }) => {
-  const state = new LocalStorageStore<ObservabilityCapabilities.State>(meta.id);
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ namespace }: { namespace: string }) {
+    const stateAtom = createKvsStore({
+      key: meta.id,
+      schema: ObservabilityCapabilities.StateSchema,
+      defaultValue: () => ({}),
+    });
 
-  state.prop({ key: 'notified', type: LocalStorageStore.bool({ allowUndefined: true }) });
+    // NOTE: Group is set at runtime, not persisted.
+    const group = yield* Effect.tryPromise(() => Observability.getObservabilityGroup(namespace));
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    registry.set(stateAtom, { ...registry.get(stateAtom), group });
 
-  // NOTE: This is not stored in local storage such that it can be accessed by workers.
-  state.values.group = await getObservabilityGroup(namespace);
-
-  return contributes(ObservabilityCapabilities.State, state.values, () => state.close());
-};
+    return Capability.contributes(ObservabilityCapabilities.State, stateAtom);
+  }),
+);

package/src/components/ObservabilitySettings/ObservabilitySettings.stories.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { ObservabilitySettings } from './ObservabilitySettings';
+
+const meta = {
+  title: 'plugins/plugin-observability/components/ObservabilitySettings',
+  component: ObservabilitySettings,
+  tags: ['settings'],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof ObservabilitySettings>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    settings: {
+      enabled: true,
+    },
+  },
+};

package/src/components/ObservabilitySettings/ObservabilitySettings.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Message, useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { Settings } from '#types';
+
+export type ObservabilitySettingsProps = AppSurface.SettingsArticleProps<Settings.Settings>;
+
+export const ObservabilitySettings = ({ settings, onSettingsChange }: ObservabilitySettingsProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+        <Message.Root valence='info'>
+          <Message.Content>{t('observability.description')}</Message.Content>
+        </Message.Root>
+        <SettingsForm.FieldSet
+          readonly={!onSettingsChange}
+          schema={Settings.Settings}
+          values={settings}
+          onValuesChanged={(values) => onSettingsChange?.(() => values)}
+        />
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
+  );
+};

package/src/components/ObservabilitySettings/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ObservabilitySettings as default } from './ObservabilitySettings';

package/src/components/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './FeedbackForm';
-export * from './HelpContainer';
-export * from './ObservabilitySettings';
+import { type ComponentType, lazy } from 'react';
+
+export const ObservabilitySettings: ComponentType<any> = lazy(() => import('./ObservabilitySettings'));

package/src/index.ts

@@ -2,8 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
-export { ObservabilityCapabilities } from './capabilities';
-export { ObservabilityEvents } from './events';
-export * from './components';
 export * from './meta';
-export * from './ObservabilityPlugin';
+export * from './types';

package/src/meta.ts

@@ -2,15 +2,16 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
 import { trim } from '@dxos/util';
 
-export const meta: PluginMeta = {
-  id: 'dxos.org/plugin/observability',
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.observability',
   name: 'Telemetry',
   description: trim`
     Application observability and telemetry collection for monitoring performance and usage patterns.
     Track metrics, logs, and traces for system health and analytics.
   `,
   icon: 'ph--eye--regular',
+  tags: ['system'],
 };

package/src/operations/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const ObservabilityOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./send-event'),
+  () => import('./toggle'),
+);

package/src/operations/send-event.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { ObservabilityCapabilities, ObservabilityOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ObservabilityOperation.SendEvent> = ObservabilityOperation.SendEvent.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      // NOTE: This is to ensure that events fired before observability is ready are still sent.
+      const observability = yield* Capability.waitFor(ObservabilityCapabilities.Observability);
+      const properties = input.properties ?? {};
+      observability.events.captureEvent(input.name, properties);
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/toggle.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { Observability } from '@dxos/observability';
+
+import { meta } from '#meta';
+
+import { ObservabilityCapabilities, ObservabilityOperation, type Settings } from '../types';
+
+const handler: Operation.WithHandler<typeof ObservabilityOperation.Toggle> = ObservabilityOperation.Toggle.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const namespace = yield* Capability.get(ObservabilityCapabilities.Namespace);
+      const observability = yield* Capability.get(ObservabilityCapabilities.Observability);
+      const capabilities = yield* Capability.Service;
+      const registry = capabilities.get(Capabilities.AtomRegistry);
+      const allSettings = capabilities.getAll(AppCapabilities.Settings);
+      const settingsObj = allSettings.find((s: AppCapabilities.Settings) => s.prefix === meta.id);
+      if (!settingsObj) {
+        return false;
+      }
+      const settings = registry.get(settingsObj.atom) as Settings.Settings;
+      const newEnabled = input.state ?? !settings.enabled;
+      registry.set(settingsObj.atom, { ...settings, enabled: newEnabled });
+      observability.events.captureEvent('observability.toggle', {
+        enabled: newEnabled,
+      });
+
+      if (newEnabled) {
+        yield* observability.enable();
+      } else {
+        yield* observability.disable();
+      }
+      yield* Effect.promise(() => Observability.storeObservabilityDisabled(namespace, !newEnabled));
+      return newEnabled;
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const ObservabilityPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { ObservabilityOperationHandlerSet } from './operations';

package/src/translations.ts

@@ -4,31 +4,23 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Telemetry',
-        'settings title': 'Telemetry settings',
-        'observability toast label': 'Privacy Notice',
-        'observability toast description':
+        'plugin.name': 'Telemetry',
+        'settings.title': 'Telemetry settings',
+        'observability-toast.label': 'Privacy Notice',
+        'observability-toast.description':
           'Composer collects usage and performance metrics to improve the product. No user data is collected.',
-        'observability toast action label': 'Settings',
-        'observability toast action alt': 'Open settings to learn more or to disable.',
-        'observability toast close label': 'Okay',
-        'observability enabled label': 'Enable telemetry',
+        'observability-toast-action.label': 'Settings',
+        'observability-toast-action.alt': 'Open settings to learn more or to disable.',
+        'observability-toast-close.label': 'Okay',
         // TODO: Add link about telemetry privacy. Make it clearer that user data is not collected.
-        'observability description':
+        'observability.description':
           'When enabled, basic usage data will used to improve the product. This may include performance metrics, error logs, and usage data. No personally identifiable information, other than your public key, is included with this data and no private data ever leaves your devices.',
-
-        'help label': 'Feedback & Support',
-        'feedback text area label': 'Feedback',
-        'feedback text area placeholder': 'Please enter your feedback, technical issue, or feature request.',
-        'send feedback label': 'Send Feedback',
-        'feedback toast label': 'Thank you for your feedback!',
-        'feedback toast description': 'We will review your feedback and get back to you as soon as possible.',
       },
     },
   },