@dxos/plugin-observability 0.8.3 → 0.8.4-main.1c7ec43d41

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,40 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { contributes, Capabilities, 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 { OBSERVABILITY_PLUGIN } from '../meta';
+import { ObservabilitySettings } from '#components';
+import { HelpContainer } from '#containers';
+import { meta } from '#meta';
+import { ObservabilityOperation } from '#operations';
+import { type Settings } from '#types';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: OBSERVABILITY_PLUGIN,
-      role: 'article',
-      filter: (data): data is { subject: SettingsStore<ObservabilitySettingsProps> } =>
-        data.subject instanceof SettingsStore && data.subject.prefix === OBSERVABILITY_PLUGIN,
-      component: ({ data: { subject } }) => <ObservabilitySettings settings={subject.value} />,
-    }),
-    createSurface({
-      id: `${OBSERVABILITY_PLUGIN}/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} />;
+        },
+      }),
+      Surface.create({
+        id: 'help',
+        role: 'deck-companion--help',
+        component: () => <HelpContainer />,
+      }),
+    ]),
+  ),
+);

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,20 +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 { ObservabilityCapabilities } from './capabilities';
-import { OBSERVABILITY_PLUGIN } from '../meta';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
+import { Observability } from '@dxos/observability';
 
-export default async ({ namespace }: { namespace: string }) => {
-  const state = new LocalStorageStore<ObservabilityCapabilities.State>(OBSERVABILITY_PLUGIN);
+import { meta } from '#meta';
+import { ObservabilityCapabilities } from '#types';
 
-  state.prop({ key: 'notified', type: LocalStorageStore.bool({ allowUndefined: true }) });
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ namespace }: { namespace: string }) {
+    const stateAtom = createKvsStore({
+      key: meta.id,
+      schema: ObservabilityCapabilities.StateSchema,
+      defaultValue: () => ({}),
+    });
 
-  // NOTE: This is not stored in local storage such that it can be accessed by workers.
-  state.values.group = await getObservabilityGroup(namespace);
+    // 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 });
 
-  return contributes(ObservabilityCapabilities.State, state.values, () => state.close());
-};
+    return Capability.contributes(ObservabilityCapabilities.State, stateAtom);
+  }),
+);

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

@@ -0,0 +1,44 @@
+//
+// 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);
+    },
+  },
+};
+
+export const WithDownloadLogs: Story = {
+  args: {
+    onSave: (values) => {
+      console.log(values);
+    },
+    onDownloadLogs: () => {
+      console.log('download logs clicked');
+    },
+  },
+};

package/src/components/FeedbackForm/FeedbackForm.tsx

@@ -0,0 +1,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { IconButton, 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'> & {
+    /** Optional handler — when supplied a "Download logs" button is rendered below the submit action. */
+    onDownloadLogs?: () => void | Promise<void>;
+  };
+
+const defaultValues: UserFeedback = {
+  message: '',
+  includeLogs: true,
+};
+
+export const FeedbackForm = ({ onSave, disabled, onDownloadLogs }: 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} />
+          {onDownloadLogs && (
+            <div role='none' className='flex w-full pt-form-padding'>
+              <IconButton
+                classNames='w-full'
+                type='button'
+                icon='ph--download-simple--regular'
+                label={t('download-logs.label')}
+                onClick={() => void onDownloadLogs()}
+                data-testid='download-logs-button'
+              />
+            </div>
+          )}
+        </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,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,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,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useState } from 'react';
+
+import { useCapabilities, 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 [downloadLogs] = useCapabilities(ObservabilityCapabilities.LogDownloader);
+  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} onDownloadLogs={downloadLogs} />;
+};

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,12 @@
 // Copyright 2023 DXOS.org
 //
 
-export { ObservabilityCapabilities } from './capabilities';
-export { ObservabilityEvents } from './events';
-export * from './components';
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export { ObservabilityCapabilities, ObservabilityEvents } from './types';
+// TODO(wittjosiah): FeedbackForm should be factored out of plugin-observability into a shared UI package.
 export * from './meta';
-export * from './ObservabilityPlugin';
+export const ObservabilityPlugin = Plugin.lazy(meta, () => import('#plugin'));
+export { translations as observabilityTranslations } from './translations';

package/src/meta.ts

@@ -2,12 +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 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',
+  tags: ['system'],
 };

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/compute';
+
+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,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Format } from '@dxos/echo';
+
+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/compute';
+
+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/compute';
+
+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 { Operation } from '@dxos/compute';
+import { Observability } from '@dxos/observability';
+
+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;