@dxos/plugin-observability 0.8.4-main.f5c0578 → 0.8.4-main.fcfe5033a5

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 { OBSERVABILITY_PLUGIN } 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>(OBSERVABILITY_PLUGIN);
+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/cli/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugin';

package/src/cli/plugin.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { Operation, OperationHandlerSet } from '@dxos/operation';
+
+import { meta } from '#meta';
+import { ObservabilityOperation } from '#operations';
+
+// TODO(wittjosiah): Hook up.
+export const ObservabilityPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({
+    activate: Capability.lazy('OperationHandler', () =>
+      Promise.resolve({
+        default: Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+          Effect.fnUntraced(function* () {
+            return Capability.contributes(
+              Capabilities.OperationHandler,
+              OperationHandlerSet.make(Operation.withHandler(ObservabilityOperation.SendEvent, () => Effect.void)),
+            );
+          }),
+        ),
+      }),
+    ),
+  }),
+  Plugin.make,
+);

package/src/components/FeedbackForm/FeedbackForm.stories.tsx

@@ -0,0 +1,32 @@
+//
+// 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 { FeedbackForm } from './FeedbackForm';
+
+const meta = {
+  title: 'plugins/plugin-observability/components/FeedbackForm',
+  component: FeedbackForm,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof FeedbackForm>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    onSave: (values) => {
+      console.log(values);
+    },
+  },
+};

package/src/components/FeedbackForm/FeedbackForm.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { useTranslation } from '@dxos/react-ui';
+import { Form, type FormRootProps, type FormSubmitProps } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { UserFeedback } from '#operations';
+
+export type FeedbackFormProps = Pick<FormRootProps<UserFeedback>, 'onSave'> & Pick<FormSubmitProps, 'disabled'>;
+
+const defaultValues: UserFeedback = {
+  message: '',
+  includeLogs: true,
+};
+
+export const FeedbackForm = ({ onSave, disabled }: FeedbackFormProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <Form.Root schema={UserFeedback} defaultValues={defaultValues} onSave={onSave}>
+      <Form.Viewport>
+        <Form.Content>
+          <Form.FieldSet />
+          <Form.Submit icon='ph--paper-plane-tilt--regular' label={t('send-feedback.label')} disabled={disabled} />
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};

package/src/components/FeedbackForm/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './FeedbackForm';

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

@@ -0,0 +1,33 @@
+//
+// 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,38 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Input, Message, useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { type 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.Item
+          title={t('observability-enabled.label')}
+          description={t('observability-enabled.description')}
+        >
+          <Input.Switch
+            disabled={!onSettingsChange}
+            checked={settings.enabled}
+            onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, enabled: !!checked }))}
+          />
+        </SettingsForm.Item>
+      </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,8 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type ComponentType, lazy } from 'react';
+
 export * from './FeedbackForm';
-export * from './HelpContainer';
-export * from './ObservabilitySettings';
+
+export const ObservabilitySettings: ComponentType<any> = lazy(() => import('./ObservabilitySettings'));

package/src/containers/HelpContainer/HelpContainer.tsx

@@ -0,0 +1,56 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useState } from 'react';
+
+import { useCapability, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { useAsyncEffect } from '@dxos/react-hooks';
+import { osTranslations } from '@dxos/ui-theme';
+
+import { FeedbackForm } from '#components';
+import { meta } from '#meta';
+import { ObservabilityOperation, type UserFeedback } from '#operations';
+import { ObservabilityCapabilities } from '#types';
+
+/** Renders the feedback form, disabling it when the feedback survey is unavailable. */
+export const HelpContainer = () => {
+  const { invokePromise } = useOperationInvoker();
+  const observability = useCapability(ObservabilityCapabilities.Observability);
+  const [feedbackAvailable, setFeedbackAvailable] = useState(false);
+
+  useAsyncEffect(
+    async (controller) => {
+      const available = await observability.isAvailable('feedback').pipe(
+        Effect.catchAll(() => Effect.succeed(false)),
+        Effect.catchAllDefect(() => Effect.succeed(false)),
+        runAndForwardErrors,
+      );
+      if (!controller.signal.aborted) {
+        setFeedbackAvailable(available);
+      }
+    },
+    [observability],
+  );
+
+  const handleSave = useCallback(
+    async (values: UserFeedback) => {
+      await invokePromise(ObservabilityOperation.CaptureUserFeedback, values);
+      await invokePromise(LayoutOperation.UpdateComplementary, { state: 'collapsed' });
+      await invokePromise(LayoutOperation.AddToast, {
+        id: `${meta.id}.feedback-success`,
+        icon: 'ph--paper-plane-tilt--regular',
+        duration: 3000,
+        title: ['feedback-toast.label', { ns: meta.id }],
+        description: ['feedback-toast.description', { ns: meta.id }],
+        closeLabel: ['close.label', { ns: osTranslations }],
+      });
+    },
+    [invokePromise],
+  );
+
+  return <FeedbackForm onSave={handleSave} disabled={!feedbackAvailable} />;
+};

package/src/containers/HelpContainer/index.ts

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

package/src/containers/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const HelpContainer: ComponentType<any> = lazy(() => import('./HelpContainer'));

package/src/index.ts

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

package/src/meta.ts

@@ -2,12 +2,15 @@
 // 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 OBSERVABILITY_PLUGIN = 'dxos.org/plugin/observability';
-
-export const meta: PluginMeta = {
-  id: OBSERVABILITY_PLUGIN,
+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',
 };

package/src/operations/capture-user-feedback.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { ObservabilityCapabilities } from '../types';
+import { CaptureUserFeedback } from './definitions';
+
+const handler: Operation.WithHandler<typeof CaptureUserFeedback> = CaptureUserFeedback.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const observability = yield* Capability.get(ObservabilityCapabilities.Observability);
+      observability.feedback.captureUserFeedback({ message: input.message, includeLogs: input.includeLogs });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/definitions.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Format } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { meta } from '#meta';
+
+import { translations } from '../translations';
+
+const t = translations[0]['en-US'][meta.id];
+
+export const UserFeedback = Schema.Struct({
+  message: Format.Text.pipe(
+    Schema.nonEmptyString(),
+    Schema.maxLength(4_096),
+    Schema.annotations({
+      title: t['feedback-textarea.label'],
+      description: t['feedback-textarea.placeholder'],
+    }),
+  ),
+  includeLogs: Schema.Boolean.pipe(
+    Schema.annotations({
+      title: t['include-debug-logs.label'],
+    }),
+    Schema.optional,
+  ),
+});
+
+export type UserFeedback = Schema.Schema.Type<typeof UserFeedback>;
+
+const OBSERVABILITY_OPERATION = `${meta.id}.operation`;
+
+/**
+ * Operations for the Observability plugin.
+ */
+export const Toggle = Operation.make({
+  meta: {
+    key: `${OBSERVABILITY_OPERATION}.toggle`,
+    name: 'Toggle Observability',
+    description: 'Toggle observability on or off.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    state: Schema.optional(Schema.Boolean),
+  }),
+  output: Schema.Boolean,
+});
+
+export const CaptureUserFeedback = Operation.make({
+  meta: {
+    key: `${OBSERVABILITY_OPERATION}.capture-feedback`,
+    name: 'Capture User Feedback',
+    description: 'Capture user feedback.',
+  },
+  services: [Capability.Service],
+  input: UserFeedback,
+  output: Schema.Void,
+});
+
+export const SendEvent = Operation.make({
+  meta: {
+    key: `${OBSERVABILITY_OPERATION}.send-event`,
+    name: 'Send Event',
+    description: 'Send an observability event.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    name: Schema.String.annotations({ description: 'The name of the event.' }),
+    properties: Schema.optional(Schema.Any).annotations({ description: 'Event properties.' }),
+  }),
+  output: Schema.Void,
+});

package/src/operations/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * as ObservabilityOperation from './definitions';
+export { UserFeedback } from './definitions';
+
+export const ObservabilityOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./capture-user-feedback'),
+  () => import('./send-event'),
+  () => import('./toggle'),
+);

package/src/operations/send-event.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
+
+import { ObservabilityCapabilities } from '../types';
+import { SendEvent } from './definitions';
+
+const handler: Operation.WithHandler<typeof SendEvent> = 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,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Observability } from '@dxos/observability';
+import { Operation } from '@dxos/operation';
+
+import { meta } from '#meta';
+
+import { ObservabilityCapabilities, type Settings } from '../types';
+import { Toggle } from './definitions';
+
+const handler: Operation.WithHandler<typeof Toggle> = 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/translations.ts

@@ -4,30 +4,32 @@
 
 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',
-        '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',
+        'observability-enabled.label': 'Enable telemetry',
+        'observability-enabled.description': 'Send anonymous usage and performance data to help improve the product.',
         // 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.',
+        'help.label': 'Feedback & Support',
+        'feedback-textarea.label': 'Feedback',
+        'feedback-textarea.placeholder': 'Please enter your feedback, technical issue, or feature request.',
+        'include-debug-logs.label': 'Include debug logs',
+        '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.',
       },
     },
   },

package/src/types/Settings.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+export const Settings = Schema.mutable(
+  Schema.Struct({
+    enabled: Schema.Boolean,
+    // TODO(wittjosiah): Separate settings for each observability feature.
+    // metrics?: boolean;
+    // telemetry?: boolean;
+    // errors?: boolean;
+  }),
+);
+
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}