@n8n/frontend-module-otel 0.1.0

package/src/__tests__/render.ts

@@ -0,0 +1,36 @@
+import { N8nPlugin } from '@n8n/design-system';
+import { i18nInstance } from '@n8n/i18n';
+import { render, type RenderOptions as TestingLibraryRenderOptions } from '@testing-library/vue';
+import type { Pinia } from 'pinia';
+import { PiniaVuePlugin } from 'pinia';
+
+/**
+ * The shell's `@/__tests__/render` cannot come with the module: it provides the
+ * workflow-document store and installs shell-only plugins. This module renders one
+ * settings view built from design-system components, so it needs the design-system
+ * directives, i18n and a pinia — nothing else.
+ */
+export type RenderOptions<T> = Omit<TestingLibraryRenderOptions<T>, 'props'> & {
+	pinia?: Pinia;
+	props?: Partial<TestingLibraryRenderOptions<T>['props']>;
+};
+
+export function createComponentRenderer<T>(component: T, defaultOptions: RenderOptions<T> = {}) {
+	return (options: RenderOptions<T> = {}) => {
+		const { pinia, ...renderOptions } = { ...defaultOptions, ...options };
+
+		return render(component, {
+			...renderOptions,
+			global: {
+				...renderOptions.global,
+				plugins: [
+					i18nInstance,
+					PiniaVuePlugin,
+					N8nPlugin,
+					...(renderOptions.global?.plugins ?? []),
+					...(pinia ? [pinia] : []),
+				],
+			},
+		} as TestingLibraryRenderOptions<T>);
+	};
+}

package/src/__tests__/setup.ts

@@ -0,0 +1,21 @@
+// The shared jsdom harness — observers, matchMedia, canvas, timers, teardown guards.
+import '@n8n/vitest-config/setup/frontend';
+
+import { loadLanguage, type LocaleMessages } from '@n8n/i18n';
+import englishBaseText from '@n8n/i18n/locales/en.json';
+import { createPinia, setActivePinia } from 'pinia';
+import { beforeEach } from 'vitest';
+
+// Framework boot stays per-package on purpose: `@n8n/i18n` devDepends on
+// `@n8n/vitest-config`, so booting i18n from inside the shared harness would
+// close a turbo build cycle.
+//
+// `useI18n()` reads a module-level singleton, so this runs once at import and
+// needs no app instance — but `baseText` returns the key itself until the
+// messages are loaded, and this module's strings still live in the central
+// `en.json` (per-module locales are a later wave).
+loadLanguage('en', englishBaseText as unknown as LocaleMessages);
+
+beforeEach(() => {
+	setActivePinia(createPinia());
+});

package/src/index.ts

@@ -0,0 +1,4 @@
+// The module's only public entry. The shell imports the descriptor from here via
+// `modules.manifest.ts`; anything else the shell (or a test) needs must be exported
+// here too — deep paths into `src/` are not part of the contract.
+export { OtelModule } from './otel.module';

package/src/otel.api.test.ts

@@ -0,0 +1,86 @@
+import type { IRestApiContext } from '@n8n/rest-api-client';
+import { makeRestApiRequest } from '@n8n/rest-api-client';
+
+import { getOtelSettings, updateOtelSettings, sendOtelTestTrace } from './otel.api';
+import type { OtelSettingsResponse, OtelTestConnection } from './otel.api';
+
+vi.mock('@n8n/rest-api-client', () => ({
+	makeRestApiRequest: vi.fn(),
+}));
+
+const requestMock = vi.mocked(makeRestApiRequest);
+
+const context: IRestApiContext = { baseUrl: 'http://localhost:5678', pushRef: '' };
+
+const makeSettings = (overrides: Partial<OtelSettingsResponse> = {}): OtelSettingsResponse => ({
+	enabled: false,
+	exporterEndpoint: 'http://localhost:4318',
+	exporterTracingPath: '/v1/traces',
+	exporterServiceName: 'n8n',
+	exporterHeaders: '',
+	tracesSampleRate: 1.0,
+	startupConnectivityTimeoutMs: 2000,
+	includeNodeSpans: true,
+	injectOutbound: true,
+	productionExecutionsOnly: true,
+	envManagedFields: [],
+	...overrides,
+});
+
+describe('otel.api', () => {
+	beforeEach(() => {
+		requestMock.mockReset();
+	});
+
+	describe('getOtelSettings', () => {
+		it('makes a GET request to /otel/settings and returns the response', async () => {
+			const response = makeSettings({ enabled: true });
+			requestMock.mockResolvedValueOnce(response);
+
+			const result = await getOtelSettings(context);
+
+			expect(requestMock).toHaveBeenCalledWith(context, 'GET', '/otel/settings');
+			expect(result).toEqual(response);
+		});
+	});
+
+	describe('updateOtelSettings', () => {
+		it('makes a PUT request to /otel/settings with the settings payload', async () => {
+			const payload = makeSettings({ enabled: true, exporterEndpoint: 'https://collector.io' });
+			const response = makeSettings({ ...payload });
+			requestMock.mockResolvedValueOnce(response);
+
+			const result = await updateOtelSettings(context, payload);
+
+			expect(requestMock).toHaveBeenCalledWith(context, 'PUT', '/otel/settings', payload);
+			expect(result).toEqual(response);
+		});
+	});
+
+	describe('sendOtelTestTrace', () => {
+		const connection: OtelTestConnection = {
+			exporterEndpoint: 'https://collector.io',
+			exporterTracingPath: '/v1/traces',
+			exporterServiceName: 'n8n',
+			exporterHeaders: 'auth=token',
+			startupConnectivityTimeoutMs: 2000,
+		};
+
+		it('makes a POST request to /otel/test-trace with the connection payload', async () => {
+			requestMock.mockResolvedValueOnce({ success: true });
+
+			const result = await sendOtelTestTrace(context, connection);
+
+			expect(requestMock).toHaveBeenCalledWith(context, 'POST', '/otel/test-trace', connection);
+			expect(result).toEqual({ success: true });
+		});
+
+		it('returns the failure result from the response', async () => {
+			requestMock.mockResolvedValueOnce({ success: false, error: '401 Unauthorized' });
+
+			const result = await sendOtelTestTrace(context, connection);
+
+			expect(result).toEqual({ success: false, error: '401 Unauthorized' });
+		});
+	});
+});

package/src/otel.api.ts

@@ -0,0 +1,48 @@
+import type { IRestApiContext } from '@n8n/rest-api-client';
+import { makeRestApiRequest } from '@n8n/rest-api-client';
+
+export type OtelSettings = {
+	enabled: boolean;
+	exporterEndpoint: string;
+	exporterTracingPath: string;
+	exporterServiceName: string;
+	exporterHeaders: string;
+	tracesSampleRate: number;
+	startupConnectivityTimeoutMs: number;
+	includeNodeSpans: boolean;
+	injectOutbound: boolean;
+	productionExecutionsOnly: boolean;
+};
+
+export type OtelSettingsResponse = OtelSettings & {
+	envManagedFields: Array<keyof OtelSettings>;
+};
+
+export async function getOtelSettings(context: IRestApiContext): Promise<OtelSettingsResponse> {
+	return await makeRestApiRequest(context, 'GET', '/otel/settings');
+}
+
+export async function updateOtelSettings(
+	context: IRestApiContext,
+	settings: OtelSettings,
+): Promise<OtelSettingsResponse> {
+	return await makeRestApiRequest(context, 'PUT', '/otel/settings', settings);
+}
+
+export type OtelTestConnection = Pick<
+	OtelSettings,
+	| 'exporterEndpoint'
+	| 'exporterTracingPath'
+	| 'exporterServiceName'
+	| 'exporterHeaders'
+	| 'startupConnectivityTimeoutMs'
+>;
+
+export type OtelTestTraceResponse = { success: true } | { success: false; error: string };
+
+export async function sendOtelTestTrace(
+	context: IRestApiContext,
+	connection: OtelTestConnection,
+): Promise<OtelTestTraceResponse> {
+	return await makeRestApiRequest(context, 'POST', '/otel/test-trace', connection);
+}

package/src/otel.constants.ts

@@ -0,0 +1,26 @@
+export const OTEL_STORE = 'otel';
+
+/**
+ * Route name for the OpenTelemetry settings page. Owned by this module rather
+ * than by the shared `VIEWS` enum, so the module can be packaged without the
+ * shell holding one of its identifiers. The value is unchanged, so existing
+ * URLs and telemetry keep resolving.
+ */
+export const OTEL_SETTINGS_VIEW = 'SettingsOpenTelemetryView';
+
+/** Name of the span emitted by the "Send test trace" button — shown in the result copy. */
+export const OTEL_TEST_SPAN_NAME = 'n8n.test_trace';
+
+/** Maps each settings field to its env-var name — shown in per-field tooltips. */
+export const OTEL_FIELD_ENV_VARS = {
+	enabled: 'N8N_OTEL_ENABLED',
+	exporterEndpoint: 'N8N_OTEL_EXPORTER_OTLP_ENDPOINT',
+	exporterTracingPath: 'N8N_OTEL_EXPORTER_OTLP_TRACING_PATH',
+	exporterServiceName: 'N8N_OTEL_EXPORTER_SERVICE_NAME',
+	exporterHeaders: 'N8N_OTEL_EXPORTER_OTLP_HEADERS',
+	tracesSampleRate: 'N8N_OTEL_TRACES_SAMPLE_RATE',
+	startupConnectivityTimeoutMs: 'N8N_OTEL_STARTUP_CONNECTIVITY_TIMEOUT_MS',
+	includeNodeSpans: 'N8N_OTEL_TRACES_INCLUDE_NODE_SPANS',
+	injectOutbound: 'N8N_OTEL_TRACES_INJECT_OUTBOUND',
+	productionExecutionsOnly: 'N8N_OTEL_TRACES_PRODUCTION_ONLY',
+} as const;

package/src/otel.module.test.ts

@@ -0,0 +1,75 @@
+import type { Scope } from '@n8n/permissions';
+import { useRBACStore } from '@n8n/stores/rbac.store';
+import { createPinia, setActivePinia } from 'pinia';
+
+import { OTEL_SETTINGS_VIEW } from './otel.constants';
+import { OtelModule } from './otel.module';
+
+/**
+ * Guards the descriptor half of the shell-to-descriptor move of the otel settings
+ * sidebar item.
+ *
+ * The old gate lived in the shell's `useSettingsItems.ts` as
+ * `isModuleActive('otel') && hasPermission(['rbac'], { rbac: { scope: 'otel:manage' } })`.
+ * It is now split: the descriptor's `available` getter owns the scope half, which is
+ * what this file covers, and `ui.store`'s `settingsSidebarItems` owns the
+ * module-active half, covered by `ui.store.settingsPages.test.ts` in the shell.
+ */
+describe('OtelModule', () => {
+	const settingsPage = () =>
+		OtelModule.settingsPages?.find((item) => item.id === 'settings-opentelemetry');
+
+	const withScopes = (scopes: Scope[]) => {
+		useRBACStore().setGlobalScopes(scopes);
+		return settingsPage();
+	};
+
+	beforeEach(() => {
+		setActivePinia(createPinia());
+	});
+
+	describe('settings sidebar item', () => {
+		it('should hide the item from a user without the otel:manage scope', () => {
+			expect(withScopes([])?.available).toBe(false);
+		});
+
+		it('should hide the item from a user holding only an unrelated scope', () => {
+			expect(withScopes(['workflow:read'])?.available).toBe(false);
+		});
+
+		it('should show the item to a user with the otel:manage scope', () => {
+			expect(withScopes(['otel:manage'])?.available).toBe(true);
+		});
+
+		it('should re-evaluate availability when scopes change after registration', () => {
+			const item = withScopes([]);
+			expect(item?.available).toBe(false);
+
+			useRBACStore().addGlobalScope('otel:manage');
+
+			expect(item?.available).toBe(true);
+		});
+	});
+
+	describe('route', () => {
+		it('should keep routing to the unchanged SettingsOpenTelemetryView route name', () => {
+			expect(OTEL_SETTINGS_VIEW).toBe('SettingsOpenTelemetryView');
+			expect(settingsPage()?.route).toEqual({ to: { name: 'SettingsOpenTelemetryView' } });
+			expect(OtelModule.routes?.[0]).toMatchObject({
+				path: 'opentelemetry',
+				name: 'SettingsOpenTelemetryView',
+			});
+		});
+
+		it('should keep the route rbac middleware, which gates direct URL access', () => {
+			expect(OtelModule.routes?.[0].meta).toMatchObject({
+				middleware: ['authenticated', 'rbac', 'custom'],
+				middlewareOptions: { rbac: { scope: 'otel:manage' } },
+			});
+		});
+
+		it('should load the view lazily, so the shell does not pull it in at boot', () => {
+			expect(typeof OtelModule.routes?.[0].component).toBe('function');
+		});
+	});
+});

package/src/otel.module.ts

@@ -0,0 +1,52 @@
+import type { FrontendModuleDescription } from '@n8n/frontend-module-sdk';
+import { useI18n } from '@n8n/i18n';
+import { useRBACStore } from '@n8n/stores/rbac.store';
+
+import { OTEL_SETTINGS_VIEW } from './otel.constants';
+
+const i18n = useI18n();
+
+// typescript-eslint reads an SFC import as `any`, because only vue-tsc can type one.
+// `pnpm turbo typecheck` is what checks this component for real.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+const SettingsOpenTelemetryView = async () => await import('./SettingsOpenTelemetryView.vue');
+
+export const OtelModule: FrontendModuleDescription = {
+	id: 'otel',
+	name: 'OpenTelemetry',
+	description: 'Configure OpenTelemetry settings',
+	icon: 'telescope',
+	routes: [
+		{
+			path: 'opentelemetry',
+			name: OTEL_SETTINGS_VIEW,
+			component: SettingsOpenTelemetryView,
+			meta: {
+				layout: 'settings',
+				middleware: ['authenticated', 'rbac', 'custom'],
+				middlewareOptions: {
+					rbac: {
+						scope: 'otel:manage',
+					},
+				},
+				telemetry: {
+					pageCategory: 'settings',
+				},
+			},
+		},
+	],
+	settingsPages: [
+		{
+			id: 'settings-opentelemetry',
+			icon: 'telescope',
+			label: i18n.baseText('settings.opentelemetry'),
+			position: 'top',
+			route: { to: { name: OTEL_SETTINGS_VIEW } },
+			// Getter, not a value: the item is registered once at init, but the
+			// scope check must re-run whenever the sidebar recomputes.
+			get available() {
+				return useRBACStore().hasScope('otel:manage');
+			},
+		},
+	],
+};