packages/telemetry/README.md
The experimental @theia/telemetry extension provides a typed service for reporting usage, error, and crash events from Theia frontends and backends. Applications decide where events go by contributing local or remote backend sinks; without a sink, the framework sends data nowhere.
Remote sinks are gated by the user-scoped telemetry.telemetryLevel preference, which defaults to off. Local sinks keep data on the machine and bypass consent, but all sinks respect telemetry.filters. A missing filter entry allows all declared sink interests, an empty array disables that sink, and a non-empty array restricts delivery to matching topics.
import { TelemetryEvent } from '@theia/telemetry/lib/common';
import { TelemetrySink } from '@theia/telemetry/lib/node';
import { injectable } from '@theia/core/shared/inversify';
@injectable()
class ApplicationTelemetrySink implements TelemetrySink {
readonly id = 'example/backend';
readonly interests: readonly string[] = ['example/build/*'];
readonly scope: 'local' | 'remote' = 'remote';
handle(event: TelemetryEvent): void {
// Forward the permitted event using an application-owned transport.
}
}
Producers inject TelemetryService and report events with slash-separated topics:
telemetryService.report('example/build/completed', {
duration: 1200,
successful: true
});
See the API samples for a complete command and sink example, and the generated @theia/telemetry API documentation for the public contracts.
The frontend and backend modules bind the preference-backed TelemetryConsentProvider by default. Applications may rebind it to source consent from their own opt-in mechanism. TelemetryConsentProvider.onDidChangeTelemetryLevel is the hook for application-owned reactions to consent changes; the framework does not send opt-out notifications.
Applications that override defaults for telemetry.telemetryLevel or telemetry.filters must register equivalent PreferenceContribution overrides in both frontend and backend containers. This keeps the frontend forwarding optimization aligned with the backend-authoritative policy. theia.frontend.config.preferences configures frontend defaults only and is insufficient by itself for backend telemetry policy.
"Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia