@theia/plugin-ext 1.76.0-next.34 → 1.76.0-next.42

package/src/plugin/plugin-context.ts

@@ -325,7 +325,8 @@ export function createAPIFactory(
     messageRegistryExt: MessageRegistryExt,
     clipboard: ClipboardExt,
     webviewExt: WebviewsExtImpl,
-    localizationExt: LocalizationExtImpl
+    localizationExt: LocalizationExtImpl,
+    telemetryExt: TelemetryExtImpl
 ): PluginAPIFactory {
 
     const authenticationExt = rpc.set(MAIN_RPC_CONTEXT.AUTHENTICATION_EXT, new AuthenticationExtImpl(rpc));
@@ -359,12 +360,12 @@ export function createAPIFactory(
     const tabsExt = rpc.set(MAIN_RPC_CONTEXT.TABS_EXT, new TabsExtImpl(rpc));
     const customEditorExt = rpc.set(MAIN_RPC_CONTEXT.CUSTOM_EDITORS_EXT, new CustomEditorsExtImpl(rpc, documents, webviewExt));
     const webviewViewsExt = rpc.set(MAIN_RPC_CONTEXT.WEBVIEW_VIEWS_EXT, new WebviewViewsExtImpl(rpc, webviewExt));
-    const telemetryExt = rpc.set(MAIN_RPC_CONTEXT.TELEMETRY_EXT, new TelemetryExtImpl());
     const testingExt = rpc.set(MAIN_RPC_CONTEXT.TESTING_EXT, new TestingExtImpl(rpc, commandRegistry));
     const uriExt = rpc.set(MAIN_RPC_CONTEXT.URI_EXT, new UriExtImpl(rpc));
     const lmExt = rpc.set(MAIN_RPC_CONTEXT.MCP_SERVER_DEFINITION_REGISTRY_EXT, new LmExtImpl(rpc));
     const lmToolExt = rpc.set(MAIN_RPC_CONTEXT.LM_TOOLS_EXT, new LanguageModelToolsExtImpl(rpc));
     rpc.set(MAIN_RPC_CONTEXT.DEBUG_EXT, debugExt);
+    rpc.set(MAIN_RPC_CONTEXT.TELEMETRY_EXT, telemetryExt);
 
     const commandLogger = new PluginLogger(rpc, 'commands-plugin');
 

package/src/plugin/plugin-manager.ts

@@ -37,6 +37,7 @@ import * as theia from '@theia/plugin';
 import * as types from './types-impl';
 import { join } from './path';
 import { EnvExtImpl } from './env';
+import { TelemetryExtImpl } from './telemetry-ext';
 import { PreferenceRegistryExtImpl } from './preference-registry';
 import { InternalStorageExt, Memento, GlobalState } from './plugin-storage';
 import { ExtPluginApi } from '../common/plugin-ext-api-contribution';
@@ -474,6 +475,9 @@ export class PluginManagerExtImpl extends AbstractPluginManagerExtImpl<PluginMan
     @inject(WebviewsExtImpl)
     protected readonly webview: WebviewsExtImpl;
 
+    @inject(TelemetryExtImpl)
+    protected readonly telemetryExt: TelemetryExtImpl;
+
     private supportedActivationEvents: Set<string>;
 
     async $init(params: PluginManagerInitializeParams): Promise<void> {
@@ -489,6 +493,8 @@ export class PluginManagerExtImpl extends AbstractPluginManagerExtImpl<PluginMan
         this.envExt.setAppUriScheme(params.env.appUriScheme);
 
         this.preferencesManager.init(params.preferences);
+        // must be in place before activation: plugins create their telemetry loggers during `activate()`
+        this.telemetryExt.setLevel(params.telemetryLevel ?? 'off');
 
         if (params.extApi) {
             this.host.initExtApi(params.extApi);

package/src/plugin/telemetry-ext.spec.ts

@@ -15,47 +15,188 @@
 // *****************************************************************************
 
 import * as chai from 'chai';
+import { TelemetryLevel } from '@theia/telemetry/lib/common/telemetry-types';
 import { TelemetryExtImpl } from './telemetry-ext';
 
 const expect = chai.expect;
 
-describe('TelemetryLogger', () => {
+describe('TelemetryExtImpl', () => {
     const sender = {
         sendEventData: () => { },
         sendErrorData: () => { }
     };
 
-    it('reflects the current telemetry enabled state', () => {
+    interface Expectation {
+        isTelemetryEnabled: boolean;
+        isUsageEnabled: boolean;
+        isErrorsEnabled: boolean;
+    }
+
+    const expectations: Record<TelemetryLevel, Expectation> = {
+        off: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: false },
+        crash: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: false },
+        error: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: true },
+        all: { isTelemetryEnabled: true, isUsageEnabled: true, isErrorsEnabled: true }
+    };
+
+    for (const level of ['off', 'crash', 'error', 'all'] as const) {
+        const expected = expectations[level];
+
+        it(`derives the enablement states from telemetry level '${level}'`, () => {
+            const telemetry = new TelemetryExtImpl();
+            telemetry.$onDidChangeTelemetryLevel(level);
+            const logger = telemetry.createTelemetryLogger(sender);
+
+            expect(telemetry.level).to.equal(level);
+            expect(telemetry.isTelemetryEnabled).to.equal(expected.isTelemetryEnabled);
+            expect(logger.isUsageEnabled).to.equal(expected.isUsageEnabled);
+            expect(logger.isErrorsEnabled).to.equal(expected.isErrorsEnabled);
+        });
+
+        it(`applies telemetry level '${level}' to loggers created before the level arrived`, () => {
+            const telemetry = new TelemetryExtImpl();
+            const logger = telemetry.createTelemetryLogger(sender);
+            telemetry.$onDidChangeTelemetryLevel(level);
+
+            expect(logger.isUsageEnabled).to.equal(expected.isUsageEnabled);
+            expect(logger.isErrorsEnabled).to.equal(expected.isErrorsEnabled);
+        });
+    }
+
+    it('only fires onDidChangeTelemetryEnabled when the boolean it reports changes', () => {
+        const telemetry = new TelemetryExtImpl();
+        const fired: boolean[] = [];
+        telemetry.onDidChangeTelemetryEnabled(enabled => fired.push(enabled));
+
+        telemetry.$onDidChangeTelemetryLevel('crash');
+        telemetry.$onDidChangeTelemetryLevel('error');
+        telemetry.$onDidChangeTelemetryLevel('all');
+        telemetry.$onDidChangeTelemetryLevel('off');
+
+        expect(fired).to.deep.equal([true, false]);
+    });
+
+    it('fires onDidChangeEnableStates once per transition that changes an enablement state', () => {
         const telemetry = new TelemetryExtImpl();
         const logger = telemetry.createTelemetryLogger(sender);
+        let changes = 0;
+        logger.onDidChangeEnableStates(() => changes++);
 
-        expect(logger.telemetryEnabled).to.equal(false);
-        expect(logger.isUsageEnabled).to.equal(false);
-        expect(logger.isErrorsEnabled).to.equal(false);
+        telemetry.$onDidChangeTelemetryLevel('crash'); // off -> crash: both stay false
+        expect(changes).to.equal(0);
 
-        telemetry.isTelemetryEnabled = true;
+        telemetry.$onDidChangeTelemetryLevel('error'); // errors become enabled
+        expect(changes).to.equal(1);
 
-        expect(logger.telemetryEnabled).to.equal(true);
-        expect(logger.isUsageEnabled).to.equal(true);
-        expect(logger.isErrorsEnabled).to.equal(true);
+        telemetry.$onDidChangeTelemetryLevel('all'); // usage becomes enabled
+        expect(changes).to.equal(2);
 
-        telemetry.isTelemetryEnabled = false;
+        telemetry.$onDidChangeTelemetryLevel('off');
+        expect(changes).to.equal(3);
+    });
 
-        expect(logger.telemetryEnabled).to.equal(false);
+    it('stops following the level once the logger is disposed', () => {
+        const telemetry = new TelemetryExtImpl();
+        const logger = telemetry.createTelemetryLogger(sender);
+        let changes = 0;
+        logger.onDidChangeEnableStates(() => changes++);
+
+        logger.dispose();
+        telemetry.$onDidChangeTelemetryLevel('all');
         expect(logger.isUsageEnabled).to.equal(false);
-        expect(logger.isErrorsEnabled).to.equal(false);
+
+        logger.isUsageEnabled = true;
+        expect(changes).to.equal(0);
+    });
+
+    it('logs rather than propagates a sender that fails to flush on disposal', async () => {
+        const telemetry = new TelemetryExtImpl();
+        const logged: unknown[] = [];
+        const consoleError = console.error;
+        console.error = (...args: unknown[]) => { logged.push(args); };
+        try {
+            telemetry.createTelemetryLogger({ ...sender, flush: () => { throw new Error('boom'); } }).dispose();
+            telemetry.createTelemetryLogger({ ...sender, flush: () => Promise.reject(new Error('boom')) }).dispose();
+            await new Promise(resolve => setTimeout(resolve, 0));
+        } finally {
+            console.error = consoleError;
+        }
+
+        expect(logged).to.have.lengthOf(2);
     });
 
-    it('emits enable-state changes when telemetry is toggled', () => {
+    it('ignores a repeated telemetry level', () => {
         const telemetry = new TelemetryExtImpl();
         const logger = telemetry.createTelemetryLogger(sender);
         let changes = 0;
-
         logger.onDidChangeEnableStates(() => changes++);
 
-        telemetry.isTelemetryEnabled = true;
-        telemetry.isTelemetryEnabled = false;
+        telemetry.$onDidChangeTelemetryLevel('all');
+        telemetry.$onDidChangeTelemetryLevel('all');
 
-        expect(changes).to.equal(2);
+        expect(changes).to.equal(1);
+    });
+});
+
+describe('TelemetryLogger', () => {
+
+    interface RecordingSender {
+        events: string[];
+        errors: Error[];
+        sendEventData(eventName: string): void;
+        sendErrorData(error: Error): void;
+    }
+
+    function createSender(): RecordingSender {
+        const events: string[] = [];
+        const errors: Error[] = [];
+        return {
+            events,
+            errors,
+            sendEventData: (eventName: string) => events.push(eventName),
+            sendErrorData: (error: Error) => errors.push(error)
+        };
+    }
+
+    it('delivers errors but suppresses usage at telemetry level \'error\'', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('error');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        logger.logUsage('usage-event');
+        logger.logError('error-event');
+        logger.logError(new Error('boom'));
+
+        expect(sender.events).to.deep.equal(['error-event']);
+        expect(sender.errors).to.have.lengthOf(1);
+    });
+
+    it('suppresses usage that a plugin re-enables while the telemetry level forbids it', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('off');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        logger.isUsageEnabled = true;
+        logger.isErrorsEnabled = true;
+        logger.logUsage('usage-event');
+        logger.logError('error-event');
+
+        expect(sender.events).to.be.empty;
+    });
+
+    it('refuses to let a plugin assign the telemetry level of its logger', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('off');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        expect(Reflect.set(logger, 'level', 'all')).to.be.false;
+        logger.logUsage('usage-event');
+
+        expect(logger.level).to.equal('off');
+        expect(logger.isUsageEnabled).to.be.false;
+        expect(sender.events).to.be.empty;
     });
 });

package/src/plugin/telemetry-ext.ts

@@ -14,33 +14,54 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 
 import { Event, Emitter } from '@theia/core/lib/common/event';
+import { Disposable } from '@theia/core/lib/common/disposable';
 import { cloneAndChange } from '@theia/core';
+import { injectable } from '@theia/core/shared/inversify';
+import { TelemetryLevel, isKindAllowedByLevel } from '@theia/telemetry/lib/common/telemetry-types';
+import { TelemetryExt } from '../common/plugin-api-rpc';
 import { mixin } from '../common/types';
 import { TelemetryTrustedValue, TelemetryLoggerOptions } from './types-impl';
 
-export class TelemetryExtImpl {
+/**
+ * Holds the telemetry level the user consented to and hands it to the loggers plugins create.
+ *
+ * @experimental
+ */
+@injectable()
+export class TelemetryExtImpl implements TelemetryExt {
 
-    _isTelemetryEnabled: boolean = false; // telemetry not activated by default
+    protected currentLevel: TelemetryLevel = 'off';
     private readonly onDidChangeTelemetryEnabledEmitter = new Emitter<boolean>();
     readonly onDidChangeTelemetryEnabled: Event<boolean> = this.onDidChangeTelemetryEnabledEmitter.event;
+    private readonly onDidChangeTelemetryLevelEmitter = new Emitter<TelemetryLevel>();
+    protected readonly onDidChangeTelemetryLevel: Event<TelemetryLevel> = this.onDidChangeTelemetryLevelEmitter.event;
 
-    get isTelemetryEnabled(): boolean {
-        return this._isTelemetryEnabled;
+    get level(): TelemetryLevel {
+        return this.currentLevel;
     }
 
-    set isTelemetryEnabled(isTelemetryEnabled: boolean) {
-        if (this._isTelemetryEnabled !== isTelemetryEnabled) {
-            this._isTelemetryEnabled = isTelemetryEnabled;
-            this.onDidChangeTelemetryEnabledEmitter.fire(this._isTelemetryEnabled);
+    $onDidChangeTelemetryLevel(level: TelemetryLevel): void {
+        this.setLevel(level);
+    }
+
+    setLevel(level: TelemetryLevel): void {
+        if (this.currentLevel === level) {
+            return;
         }
+        const wasTelemetryEnabled = this.isTelemetryEnabled;
+        this.currentLevel = level;
+        this.onDidChangeTelemetryLevelEmitter.fire(level);
+        if (this.isTelemetryEnabled !== wasTelemetryEnabled) {
+            this.onDidChangeTelemetryEnabledEmitter.fire(this.isTelemetryEnabled);
+        }
+    }
+
+    get isTelemetryEnabled(): boolean {
+        return isKindAllowedByLevel(this.currentLevel, 'usage');
     }
 
     createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions | undefined): TelemetryLogger {
-        const logger = new TelemetryLogger(sender, this._isTelemetryEnabled, options);
-        this.onDidChangeTelemetryEnabled(isEnabled => {
-            logger.telemetryEnabled = isEnabled;
-        });
-        return logger;
+        return new TelemetryLogger(sender, this.currentLevel, this.onDidChangeTelemetryLevel, options);
     }
 }
 
@@ -49,30 +70,36 @@ export class TelemetryLogger {
     readonly options: TelemetryLoggerOptions | undefined;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     readonly commonProperties: Record<string, any>;
-    private _telemetryEnabled: boolean;
+    private _level: TelemetryLevel;
 
     private readonly onDidChangeEnableStatesEmitter: Emitter<TelemetryLogger> = new Emitter();
     readonly onDidChangeEnableStates: Event<TelemetryLogger> = this.onDidChangeEnableStatesEmitter.event;
     private _isUsageEnabled: boolean;
     private _isErrorsEnabled: boolean;
+    private readonly levelSubscription: Disposable;
 
-    constructor(sender: TelemetrySender, telemetryEnabled: boolean, options?: TelemetryLoggerOptions) {
+    constructor(sender: TelemetrySender, level: TelemetryLevel, onDidChangeTelemetryLevel: Event<TelemetryLevel>, options?: TelemetryLoggerOptions) {
         this.sender = sender;
         this.options = options;
         this.commonProperties = this.getCommonProperties();
-        this._telemetryEnabled = telemetryEnabled;
-        this._isErrorsEnabled = telemetryEnabled;
-        this._isUsageEnabled = telemetryEnabled;
+        this._level = level;
+        this._isErrorsEnabled = isKindAllowedByLevel(level, 'error');
+        this._isUsageEnabled = isKindAllowedByLevel(level, 'usage');
+        this.levelSubscription = onDidChangeTelemetryLevel(next => this.applyLevel(next));
     }
 
-    get telemetryEnabled(): boolean {
-        return this._telemetryEnabled;
+    /**
+     * The telemetry level the user consented to. Must stay read-only: the object handed to a plugin is proxied with a
+     * `get` trap only, so a setter here would let the plugin raise its own gate.
+     */
+    get level(): TelemetryLevel {
+        return this._level;
     }
 
-    set telemetryEnabled(telemetryEnabled: boolean) {
-        if (this._telemetryEnabled !== telemetryEnabled) {
-            this._telemetryEnabled = telemetryEnabled;
-            this.updateEnableStates(telemetryEnabled, telemetryEnabled);
+    private applyLevel(level: TelemetryLevel): void {
+        if (this._level !== level) {
+            this._level = level;
+            this.updateEnableStates(isKindAllowedByLevel(level, 'usage'), isKindAllowedByLevel(level, 'error'));
         }
     }
 
@@ -108,7 +135,7 @@ export class TelemetryLogger {
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     logUsage(eventName: string, data?: Record<string, any | TelemetryTrustedValue<any>>): void {
-        if (!this.telemetryEnabled || !this.isUsageEnabled) {
+        if (!isKindAllowedByLevel(this._level, 'usage') || !this.isUsageEnabled) {
             return;
         }
         this.logEvent(eventName, data);
@@ -116,7 +143,7 @@ export class TelemetryLogger {
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     logError(eventNameOrException: string | Error, data?: Record<string, any | TelemetryTrustedValue<any>>): void {
-        if (!this.telemetryEnabled || !this.isErrorsEnabled || !this.sender) {
+        if (!isKindAllowedByLevel(this._level, 'error') || !this.isErrorsEnabled || !this.sender) {
             // no sender available or error shall not be sent
             return;
         }
@@ -128,14 +155,17 @@ export class TelemetryLogger {
     }
 
     dispose(): void {
-        if (this.sender?.flush) {
-            let tempSender: TelemetrySender | undefined = this.sender;
-            this.sender = undefined;
-            Promise.resolve(tempSender.flush!()).then(tempSender = undefined);
-        } else {
-            this.sender = undefined;
+        this.levelSubscription.dispose();
+        this.onDidChangeEnableStatesEmitter.dispose();
+        const sender = this.sender;
+        this.sender = undefined;
+        const reportFlushFailure = (error: unknown): void => console.error('Failed to flush the telemetry sender.', error);
+        try {
+            Promise.resolve(sender?.flush?.()).catch(reportFlushFailure);
+        } catch (error) {
+            reportFlushFailure(error);
         }
-    };
+    }
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     private logEvent(eventName: string, data?: Record<string, any>): void {