@theia/telemetry 1.74.0-next.68

package/src/common/telemetry-consent-provider.spec.ts

@@ -0,0 +1,95 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { Emitter } from '@theia/core/lib/common';
+import { Container } from '@theia/core/shared/inversify';
+import {
+    PreferenceTelemetryConsentProvider, TelemetryConsentProvider, isKindAllowedByLevel
+} from './telemetry-consent-provider';
+import { TELEMETRY_FILTERS, TELEMETRY_LEVEL, TelemetryPreferences } from './telemetry-preferences';
+import { TelemetryLevel } from './telemetry-types';
+
+describe('telemetry consent provider', () => {
+    it('maps telemetry levels to event kinds', () => {
+        const kinds = ['usage', 'error', 'crash'] as const;
+        const levels: TelemetryLevel[] = ['off', 'crash', 'error', 'all'];
+        expect(levels.map(level => kinds.filter(kind => isKindAllowedByLevel(level, kind)))).to.deep.equal([
+            [],
+            ['crash'],
+            ['error', 'crash'],
+            ['usage', 'error', 'crash']
+        ]);
+    });
+
+    it('applies and reports preference changes before readiness', () => {
+        const changes = new Emitter<never>();
+        const ready = new Promise<void>(() => undefined);
+        let level: TelemetryLevel = 'off';
+        const preferences = {
+            get [TELEMETRY_LEVEL](): TelemetryLevel {
+                return level;
+            },
+            [TELEMETRY_FILTERS]: {},
+            ready,
+            onPreferenceChanged: changes.event
+        } as unknown as TelemetryPreferences;
+        const container = new Container();
+        container.bind(TelemetryPreferences).toConstantValue(preferences);
+        container.bind(TelemetryConsentProvider).to(PreferenceTelemetryConsentProvider).inSingletonScope();
+        const provider = container.get<TelemetryConsentProvider>(TelemetryConsentProvider);
+        const observed: TelemetryLevel[] = [];
+        provider.onDidChangeTelemetryLevel(value => observed.push(value));
+
+        level = 'error';
+        changes.fire({ preferenceName: TELEMETRY_LEVEL } as never);
+
+        expect(provider.level).to.equal('error');
+        expect(observed).to.deep.equal(['error']);
+    });
+
+    it('starts off, then reads the preference after readiness and fires on changes', async () => {
+        const changes = new Emitter<never>();
+        let resolveReady: () => void;
+        const ready = new Promise<void>(resolve => resolveReady = resolve);
+        let level: TelemetryLevel = 'error';
+        const preferences = {
+            get [TELEMETRY_LEVEL](): TelemetryLevel {
+                return level;
+            },
+            [TELEMETRY_FILTERS]: {},
+            ready,
+            onPreferenceChanged: changes.event
+        } as unknown as TelemetryPreferences;
+        const container = new Container();
+        container.bind(TelemetryPreferences).toConstantValue(preferences);
+        container.bind(TelemetryConsentProvider).to(PreferenceTelemetryConsentProvider).inSingletonScope();
+        const provider = container.get<TelemetryConsentProvider>(TelemetryConsentProvider);
+        const observed: TelemetryLevel[] = [];
+        provider.onDidChangeTelemetryLevel(value => observed.push(value));
+
+        expect(provider.level).to.equal('off');
+        resolveReady!();
+        await preferences.ready;
+        await Promise.resolve();
+        expect(provider.level).to.equal('error');
+
+        level = 'all';
+        changes.fire({ preferenceName: TELEMETRY_LEVEL } as never);
+        expect(provider.level).to.equal('all');
+        expect(observed).to.deep.equal(['error', 'all']);
+    });
+});

package/src/common/telemetry-consent-provider.ts

@@ -0,0 +1,72 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { Emitter, Event } from '@theia/core/lib/common';
+import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
+import { TELEMETRY_LEVEL, TelemetryPreferences } from './telemetry-preferences';
+import { TelemetryEventKind } from './telemetry-service';
+import { TelemetryLevel } from './telemetry-types';
+
+/** @experimental */
+export const TelemetryConsentProvider = Symbol('TelemetryConsentProvider');
+
+/** @experimental */
+export interface TelemetryConsentProvider {
+    readonly level: TelemetryLevel;
+    readonly onDidChangeTelemetryLevel: Event<TelemetryLevel>;
+}
+
+/** @experimental */
+export function isKindAllowedByLevel(level: TelemetryLevel, kind: TelemetryEventKind): boolean {
+    return level === 'all'
+        || level === 'error' && (kind === 'error' || kind === 'crash')
+        || level === 'crash' && kind === 'crash';
+}
+
+/** @experimental */
+@injectable()
+export class PreferenceTelemetryConsentProvider implements TelemetryConsentProvider {
+
+    protected currentLevel: TelemetryLevel = 'off';
+    protected readonly onDidChangeTelemetryLevelEmitter = new Emitter<TelemetryLevel>();
+    readonly onDidChangeTelemetryLevel = this.onDidChangeTelemetryLevelEmitter.event;
+
+    @inject(TelemetryPreferences)
+    protected readonly preferences: TelemetryPreferences;
+
+    @postConstruct()
+    protected init(): void {
+        this.preferences.onPreferenceChanged(change => {
+            if (change.preferenceName === TELEMETRY_LEVEL) {
+                this.setLevel(this.preferences[TELEMETRY_LEVEL]);
+            }
+        });
+        this.preferences.ready.then(() => {
+            this.setLevel(this.preferences[TELEMETRY_LEVEL]);
+        }, () => undefined);
+    }
+
+    protected setLevel(level: TelemetryLevel): void {
+        if (level !== this.currentLevel) {
+            this.currentLevel = level;
+            this.onDidChangeTelemetryLevelEmitter.fire(level);
+        }
+    }
+
+    get level(): TelemetryLevel {
+        return this.currentLevel;
+    }
+}

package/src/common/telemetry-preferences.spec.ts

@@ -0,0 +1,56 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { PreferenceScope } from '@theia/core/lib/common/preferences/preference-scope';
+import {
+    TELEMETRY_FILTERS,
+    TELEMETRY_LEVEL,
+    TelemetryPreferenceSchema
+} from './telemetry-preferences';
+
+describe('telemetry preferences', () => {
+    it('defines only the level and filters preference keys', () => {
+        expect(Object.keys(TelemetryPreferenceSchema.properties)).to.deep.equal([TELEMETRY_LEVEL, TELEMETRY_FILTERS]);
+    });
+
+    it('limits telemetry preferences to user scope', () => {
+        expect(TelemetryPreferenceSchema.scope).to.equal(PreferenceScope.User);
+    });
+
+    it('uses safe defaults and describes each telemetry level', () => {
+        expect(TelemetryPreferenceSchema.properties[TELEMETRY_LEVEL]).to.deep.include({
+            type: 'string',
+            enum: ['off', 'crash', 'error', 'all'],
+            enumDescriptions: [
+                'Disables all product telemetry.',
+                'Sends OS level crash reports.',
+                'Sends general error telemetry and crash reports.',
+                'Sends usage data, errors, and crash reports.'
+            ],
+            default: 'off'
+        });
+        expect(TelemetryPreferenceSchema.properties[TELEMETRY_FILTERS].default).to.deep.equal({});
+    });
+
+    it('defines filters as sink IDs mapped to arrays of topic patterns', () => {
+        expect(TelemetryPreferenceSchema.properties[TELEMETRY_FILTERS]).to.include({ type: 'object' });
+        expect(TelemetryPreferenceSchema.properties[TELEMETRY_FILTERS].additionalProperties).to.deep.equal({
+            type: 'array',
+            items: { type: 'string' }
+        });
+    });
+});

package/src/common/telemetry-preferences.ts

@@ -0,0 +1,91 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { nls } from '@theia/core/lib/common/nls';
+import { PreferenceScope } from '@theia/core/lib/common/preferences/preference-scope';
+import { createPreferenceProxy, PreferenceProxy } from '@theia/core/lib/common/preferences/preference-proxy';
+import { PreferenceContribution, PreferenceSchema } from '@theia/core/lib/common/preferences/preference-schema';
+import { PreferenceService } from '@theia/core/lib/common/preferences/preference-service';
+import { interfaces } from '@theia/core/shared/inversify';
+import { TelemetryLevel } from './telemetry-types';
+
+/** @experimental */
+export const TELEMETRY_LEVEL = 'telemetry.telemetryLevel';
+/** @experimental */
+export const TELEMETRY_FILTERS = 'telemetry.filters';
+
+/** @experimental */
+export type TelemetryFilters = Record<string, string[]>;
+
+/** @experimental */
+export interface TelemetryConfiguration {
+    [TELEMETRY_LEVEL]: TelemetryLevel;
+    [TELEMETRY_FILTERS]: TelemetryFilters;
+}
+
+/** @experimental */
+export const TelemetryPreferenceSchema: PreferenceSchema = {
+    scope: PreferenceScope.User,
+    properties: {
+        [TELEMETRY_LEVEL]: {
+            type: 'string',
+            enum: ['off', 'crash', 'error', 'all'],
+            enumDescriptions: [
+                nls.localizeByDefault('Disables all product telemetry.'),
+                nls.localizeByDefault('Sends OS level crash reports.'),
+                nls.localizeByDefault('Sends general error telemetry and crash reports.'),
+                nls.localizeByDefault('Sends usage data, errors, and crash reports.')
+            ],
+            default: 'off',
+            description: nls.localizeByDefault('Controls the level of telemetry.')
+        },
+        [TELEMETRY_FILTERS]: {
+            type: 'object',
+            additionalProperties: {
+                type: 'array',
+                items: {
+                    type: 'string'
+                }
+            },
+            default: {},
+            description: nls.localize('theia/telemetry/filters',
+                'Restrict the topic patterns delivered to each telemetry sink. Missing entries allow all sink interests; empty arrays disable a sink.')
+        }
+    }
+};
+
+/** @experimental */
+export const TelemetryPreferenceContribution = Symbol('TelemetryPreferenceContribution');
+/** @experimental */
+export const TelemetryPreferences = Symbol('TelemetryPreferences');
+/** @experimental */
+export type TelemetryPreferences = PreferenceProxy<TelemetryConfiguration>;
+
+/** @experimental */
+export function createTelemetryPreferences(preferences: PreferenceService, schema: PreferenceSchema = TelemetryPreferenceSchema): TelemetryPreferences {
+    return createPreferenceProxy(preferences, schema);
+}
+
+/** @experimental */
+export function bindTelemetryPreferences(bind: interfaces.Bind): void {
+    bind(TelemetryPreferences).toDynamicValue(ctx => {
+        const preferences = ctx.container.get<PreferenceService>(PreferenceService);
+        const contribution = ctx.container.get<PreferenceContribution>(TelemetryPreferenceContribution);
+        return createTelemetryPreferences(preferences, contribution.schema);
+    }).inSingletonScope();
+    bind(TelemetryPreferenceContribution).toConstantValue({ schema: TelemetryPreferenceSchema });
+    bind(PreferenceContribution).toService(TelemetryPreferenceContribution);
+}

package/src/common/telemetry-protocol.ts

@@ -0,0 +1,100 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { isObject } from '@theia/core/lib/common/types';
+import {
+    TelemetryData, TelemetryEventKind, TelemetryReportOptions, TelemetryValue, isTelemetryData, isTelemetryEventKind, snapshotTelemetryData
+} from './telemetry-service';
+import { isValidTelemetryTopic } from './telemetry-topic';
+
+/** @experimental */
+export interface TelemetryEvent<T extends object = Record<string, TelemetryValue>> {
+    readonly topic: string;
+    readonly kind: TelemetryEventKind;
+    readonly data?: TelemetryData<T>;
+    readonly attributes?: TelemetryData<Record<string, TelemetryValue>>;
+    readonly session: string;
+    readonly timestamp: number;
+}
+
+/** @experimental */
+export function isValidTelemetryEvent(event: unknown): event is TelemetryEvent {
+    if (!isObject<TelemetryEvent>(event)) {
+        return false;
+    }
+    return isValidTelemetryTopic(event.topic)
+        && isTelemetryEventKind(event.kind)
+        && typeof event.session === 'string'
+        && event.session.length > 0
+        && typeof event.timestamp === 'number'
+        && Number.isFinite(event.timestamp)
+        && (event.data === undefined || isTelemetryData(event.data))
+        && (event.attributes === undefined || isTelemetryData(event.attributes));
+}
+
+/** @experimental */
+export function describeTelemetryTopic(topic: unknown): string {
+    return typeof topic === 'string' ? topic : '<invalid>';
+}
+
+/** @experimental */
+export function describeTelemetryEventTopic(event: unknown): string {
+    if (!isObject(event)) {
+        return '<invalid>';
+    }
+    return describeTelemetryTopic(event.topic);
+}
+
+/** @experimental */
+export function createTelemetryEvent<T extends object>(
+    topic: string,
+    session: string,
+    data?: TelemetryData<T>,
+    options?: TelemetryReportOptions
+): TelemetryEvent<T> {
+    return {
+        topic,
+        kind: options?.kind ?? 'usage',
+        data,
+        attributes: options?.attributes,
+        session,
+        timestamp: Date.now()
+    };
+}
+
+/** @experimental */
+export function snapshotTelemetryEvent(event: TelemetryEvent): TelemetryEvent {
+    return Object.freeze({
+        topic: event.topic,
+        kind: event.kind,
+        data: snapshotTelemetryData(event.data),
+        attributes: snapshotTelemetryData(event.attributes),
+        session: event.session,
+        timestamp: event.timestamp
+    });
+}
+
+/** @experimental */
+export const telemetryServicePath = '/services/telemetry';
+
+/** @experimental */
+export const TelemetryRpc = Symbol('TelemetryRpc');
+
+/** @experimental */
+export interface TelemetryRpc {
+    notifyEvent(event: TelemetryEvent): void;
+    getLocalSinkInterests(): Promise<string[]>;
+}

package/src/common/telemetry-service.spec.ts

@@ -0,0 +1,152 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import URI from '@theia/core/lib/common/uri';
+import { isValidTelemetryEvent } from './telemetry-protocol';
+import { TelemetryData, TelemetryService, isTelemetryData, isTelemetryEventKind, snapshotTelemetryData } from './telemetry-service';
+
+interface ConsumerPayload {
+    action: string;
+    duration: number;
+    successful: boolean;
+    tags: string[];
+    measurements: readonly number[];
+    states: boolean[];
+}
+
+const typedPayload = {
+    action: 'open',
+    duration: 12,
+    successful: true,
+    tags: ['editor', 'open'],
+    measurements: [4, 8] as const,
+    states: [true, false]
+} satisfies TelemetryData<ConsumerPayload>;
+
+const compileTimeUsage = (service: TelemetryService): void => service.report<ConsumerPayload>('consumer/action', typedPayload, {
+    kind: 'error',
+    attributes: { source: 'consumer' }
+});
+
+describe('telemetry service contract', () => {
+    it('supports consumer-defined payload interfaces without an index signature', () => {
+        expect(compileTimeUsage).to.be.a('function');
+    });
+    it('validates telemetry event kinds', () => {
+        expect(['usage', 'error', 'crash'].every(isTelemetryEventKind)).to.be.true;
+        expect(isTelemetryEventKind('invalid')).to.be.false;
+    });
+
+    it('validates event kind, attributes, and session', () => {
+        const event = {
+            topic: 'consumer/action',
+            kind: 'error' as const,
+            data: typedPayload,
+            attributes: { source: 'consumer' },
+            session: 'frontend-session',
+            timestamp: 42
+        };
+
+        expect(isValidTelemetryEvent(event)).to.be.true;
+        expect(isValidTelemetryEvent({ ...event, kind: 'invalid' })).to.be.false;
+        expect(isValidTelemetryEvent({ ...event, session: '' })).to.be.false;
+        expect(isValidTelemetryEvent({ ...event, attributes: { nested: {} } })).to.be.false;
+    });
+
+    it('accepts plain flat payloads with primitive telemetry values', () => {
+        expect(isTelemetryData(typedPayload)).to.be.true;
+        expect(isTelemetryData({})).to.be.true;
+    });
+
+    it('accepts homogeneous primitive and empty arrays unchanged', () => {
+        const strings = ['editor', 'open'];
+        const numbers = [4, 8];
+        const booleans = [true, false];
+        const empty: string[] = [];
+        const data = { strings, numbers, booleans, empty };
+
+        expect(isTelemetryData(data)).to.be.true;
+        expect(data.strings).to.equal(strings);
+        expect(data.numbers).to.equal(numbers);
+        expect(data.booleans).to.equal(booleans);
+        expect(data.empty).to.equal(empty);
+    });
+
+    it('creates immutable snapshots without transforming accepted values', () => {
+        const strings = ['editor', 'open'];
+        const data = { action: 'open', duration: 12, successful: true, strings };
+
+        const snapshot = snapshotTelemetryData(data);
+
+        expect(snapshot).to.deep.equal(data);
+        expect(snapshot).not.to.equal(data);
+        expect(snapshot?.strings).not.to.equal(strings);
+        expect(Object.isFrozen(snapshot)).to.be.true;
+        expect(Object.isFrozen(snapshot?.strings)).to.be.true;
+        expect(snapshotTelemetryData(undefined)).to.be.undefined;
+    });
+
+    it('rejects non-object payloads', () => {
+        for (const value of [undefined, 'value', 1, true]) {
+            expect(isTelemetryData(value)).to.be.false;
+        }
+        // eslint-disable-next-line no-null/no-null
+        expect(isTelemetryData(null)).to.be.false;
+    });
+
+    it('rejects top-level arrays and nested objects', () => {
+        expect(isTelemetryData([])).to.be.false;
+        expect(isTelemetryData({ value: { nested: true } })).to.be.false;
+    });
+
+    it('rejects mixed, nested, and sparse arrays', () => {
+        const sparse = new Array<string>(2);
+        sparse[1] = 'value';
+
+        expect(isTelemetryData({ value: ['value', 1] })).to.be.false;
+        expect(isTelemetryData({ value: [['nested']] })).to.be.false;
+        expect(isTelemetryData({ value: sparse })).to.be.false;
+    });
+
+    it('rejects unsupported array elements', () => {
+        expect(isTelemetryData({ value: [{ nested: true }] })).to.be.false;
+        expect(isTelemetryData({ value: ['value', undefined] })).to.be.false;
+        expect(isTelemetryData({ value: ['value', () => 'value'] })).to.be.false;
+        expect(isTelemetryData({ value: ['value', Symbol('value')] })).to.be.false;
+        expect(isTelemetryData({ value: new Uint8Array([1, 2]) })).to.be.false;
+    });
+
+    it('rejects special and binary objects', () => {
+        expect(isTelemetryData(new Error('failure'))).to.be.false;
+        expect(isTelemetryData(new Date())).to.be.false;
+        expect(isTelemetryData(new URI('file:///workspace'))).to.be.false;
+        expect(isTelemetryData(new Uint8Array([1, 2]))).to.be.false;
+    });
+
+    it('rejects class instances even when their properties are flat', () => {
+        class Payload {
+            value = 'value';
+        }
+        expect(isTelemetryData(new Payload())).to.be.false;
+    });
+
+    it('rejects unsupported values in otherwise plain payloads', () => {
+        expect(isTelemetryData({ value: undefined })).to.be.false;
+        expect(isTelemetryData({ value: () => 'value' })).to.be.false;
+        expect(isTelemetryData({ value: Symbol('value') })).to.be.false;
+    });
+});

package/src/common/telemetry-service.ts

@@ -0,0 +1,90 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { deepClone, deepFreeze } from '@theia/core/lib/common/objects';
+import { isObject } from '@theia/core/lib/common/types';
+
+/** @experimental */
+export type TelemetryPrimitive = string | number | boolean;
+/** @experimental */
+export type TelemetryValue = TelemetryPrimitive | readonly string[] | readonly number[] | readonly boolean[];
+
+/** @experimental */
+export type TelemetryData<T extends object> = {
+    [K in keyof T]: T[K] extends TelemetryValue ? T[K] : never;
+};
+
+function isTelemetryPrimitive(value: unknown): value is TelemetryPrimitive {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+
+function isTelemetryArray(value: unknown): value is readonly TelemetryPrimitive[] {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+    if (value.length === 0) {
+        return true;
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, 0) || !isTelemetryPrimitive(value[0])) {
+        return false;
+    }
+    const elementType = typeof value[0];
+    for (let index = 1; index < value.length; index++) {
+        if (!Object.prototype.hasOwnProperty.call(value, index) || !isTelemetryPrimitive(value[index]) || typeof value[index] !== elementType) {
+            return false;
+        }
+    }
+    return true;
+}
+
+function isTelemetryValue(value: unknown): value is TelemetryValue {
+    return isTelemetryPrimitive(value) || isTelemetryArray(value);
+}
+
+/** @experimental */
+export function isTelemetryData(data: unknown): data is Record<string, TelemetryValue> {
+    if (!isObject(data) || Array.isArray(data) || Object.getPrototypeOf(data) !== Object.prototype) {
+        return false;
+    }
+    return Object.values(data).every(isTelemetryValue);
+}
+
+/** @experimental */
+export function snapshotTelemetryData<T extends object>(data: TelemetryData<T> | undefined): TelemetryData<T> | undefined {
+    return data === undefined ? undefined : deepFreeze(deepClone(data));
+}
+
+/** @experimental */
+export type TelemetryEventKind = 'usage' | 'error' | 'crash';
+
+/** @experimental */
+export function isTelemetryEventKind(value: unknown): value is TelemetryEventKind {
+    return value === 'usage' || value === 'error' || value === 'crash';
+}
+
+/** @experimental */
+export interface TelemetryReportOptions {
+    readonly kind?: TelemetryEventKind;
+    readonly attributes?: TelemetryData<Record<string, TelemetryValue>>;
+}
+
+/** @experimental */
+export const TelemetryService = Symbol('TelemetryService');
+
+/** @experimental */
+export interface TelemetryService {
+    report<T extends object>(topic: string, data?: TelemetryData<T>, options?: TelemetryReportOptions): void;
+}