feat(appkit): send internal telemetry via AppkitLog schema

apps/dev-playground/app.yaml

@@ -5,6 +5,8 @@ env:
  valueFrom: genie-space
  - name: DATABRICKS_SERVING_ENDPOINT_NAME
  valueFrom: serving-endpoint
+ - name: DATABRICKS_JOB_ID
+ valueFrom: job
  # Files plugin manifest declares a static DATABRICKS_VOLUME_FILES
  # requirement; keep it bound so appkit's runtime validation passes
  # even though the policy harness below uses its own keys.

docs/docs/api/appkit/Function.createApp.md

@@ -4,6 +4,7 @@
 function createApp<T>(config: {
  cache?: CacheConfig;
  client?: WorkspaceClient;
+ disableInternalTelemetry?: boolean;
  onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
  plugins?: T;
  telemetry?: TelemetryConfig;
@@ -30,9 +31,10 @@ with an `asUser(req)` method for user-scoped execution.
 
 | Parameter | Type |
 | ------ | ------ |
-| `config` | \{ `cache?`: [`CacheConfig`](Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `onPluginsReady?`: (`appkit`: `PluginMap`\<`T`\>) => `void` \| `Promise`\<`void`\>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](Interface.TelemetryConfig.md); \} |
+| `config` | \{ `cache?`: [`CacheConfig`](Interface.CacheConfig.md); `client?`: `WorkspaceClient`; `disableInternalTelemetry?`: `boolean`; `onPluginsReady?`: (`appkit`: `PluginMap`\<`T`\>) => `void` \| `Promise`\<`void`\>; `plugins?`: `T`; `telemetry?`: [`TelemetryConfig`](Interface.TelemetryConfig.md); \} |
 | `config.cache?` | [`CacheConfig`](Interface.CacheConfig.md) |
 | `config.client?` | `WorkspaceClient` |
+| `config.disableInternalTelemetry?` | `boolean` |
 | `config.onPluginsReady?` | (`appkit`: `PluginMap`\<`T`\>) => `void` \| `Promise`\<`void`\> |
 | `config.plugins?` | `T` |
 | `config.telemetry?` | [`TelemetryConfig`](Interface.TelemetryConfig.md) |

docs/docs/privacy.mdx

@@ -0,0 +1,47 @@
+---
+sidebar_position: 99
+---
+
+# Privacy
+
+AppKit sends a small amount of anonymized usage telemetry to Databricks
+so the team can understand how the SDK is used and prioritize
+improvements. This page documents exactly what is sent, when, and how
+to turn it off.
+
+## What we collect
+
+Every event is a single record with three top-level fields:
+
+| Field | Type | Source |
+| ---------------- | ------ | ----------------------------------- |
+| `event_name` | enum | One of `APP_STARTUP`, `HEARTBEAT`, `REQUEST_METRICS` |
+| `app_id` | string | The app's OAuth client UUID (`DATABRICKS_CLIENT_ID`) |
+| `appkit_version` | string | The AppKit SDK version |
+
+Each event also carries one of three event-specific bodies:
+
+- **`APP_STARTUP`** — emitted once when `createApp` finishes booting.
+ Empty body.
+- **`HEARTBEAT`** — emitted every five minutes from a running app.
+ Empty body.
+- **`REQUEST_METRICS`** — emitted once per minute, one record per HTTP
+ endpoint that received traffic in the window. Each record contains:
+ - `endpoint` — the route template (e.g. `GET /api/genie/:space_id/messages`),
+ never the raw request URL or any user-provided values.
+ - `request_count`
+ - `request_latency_ms_avg`
+ - `response_count_http4xx`
+ - `response_count_http5xx`
+
+## How to opt out
+
+Set any one of the following:
+
+```sh
+DISABLE_APPKIT_INTERNAL_TELEMETRY=true
+DO_NOT_TRACK=1
+```
+
+Either fully disables the reporter — no events are emitted and no
+network calls are made.

packages/appkit/src/core/appkit.ts

@@ -8,8 +8,13 @@ import type {
  PluginData,
  PluginMap,
 } from "shared";
+import { version as productVersion } from "../../package.json";
 import { CacheManager } from "../cache";
 import { ServiceContext } from "../context";
+import {
+ isInternalTelemetryEnabled,
+ TelemetryReporter,
+} from "../internal-telemetry";
 import { createLogger } from "../logging/logger";
 import { ResourceRegistry, ResourceType } from "../registry";
 import type { TelemetryConfig } from "../telemetry";
@@ -191,6 +196,7 @@ export class AppKit<TPlugins extends InputPluginMap> {
  cache?: CacheConfig;
  client?: WorkspaceClient;
  onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
+ disableInternalTelemetry?: boolean;
  } = {},
  ): Promise<PluginMap<T>> {
  // Initialize core services
@@ -233,6 +239,10 @@ export class AppKit<TPlugins extends InputPluginMap> {
  logger.debug("onPluginsReady hook completed");
  }
 
+ if (isInternalTelemetryEnabled(config)) {
+ AppKit.bootstrapInternalTelemetry();
+ }
+
  const serverPlugin = instance.#pluginInstances.server;
  if (serverPlugin && typeof (serverPlugin as any).start === "function") {
  await (serverPlugin as any).start();
@@ -241,6 +251,18 @@ export class AppKit<TPlugins extends InputPluginMap> {
  return handle;
  }
 
+ private static bootstrapInternalTelemetry(): void {
+ const serviceCtx = ServiceContext.get();
+ const reporter = TelemetryReporter.initialize({
+ workspaceId: serviceCtx.workspaceId,
+ client: serviceCtx.client,
+ appId: process.env.DATABRICKS_CLIENT_ID || "",
+ appkitVersion: productVersion,
+ });
+ reporter.start();
+ reporter.sendStartup().catch(() => {});
+ }
+
  private static preparePlugins(
  plugins: PluginData<PluginConstructor, unknown, string>[],
  ) {
@@ -300,6 +322,7 @@ export async function createApp<
  cache?: CacheConfig;
  client?: WorkspaceClient;
  onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
+ disableInternalTelemetry?: boolean;
  } = {},
 ): Promise<PluginMap<T>> {
  return AppKit._createApp(config);

packages/appkit/src/core/tests/databricks.test.ts

@@ -6,6 +6,24 @@ import type { PluginManifest } from "../../registry/types";
 import { ResourceType } from "../../registry/types";
 import { AppKit, createApp } from "../appkit";
 
+const mockReporter = {
+ start: vi.fn(),
+ stop: vi.fn(),
+ sendStartup: vi.fn().mockResolvedValue(undefined),
+ sendHeartbeat: vi.fn().mockResolvedValue(undefined),
+ flushRequestMetrics: vi.fn().mockResolvedValue(undefined),
+ recordRequest: vi.fn(),
+};
+
+vi.mock("../../internal-telemetry", () => ({
+ isInternalTelemetryEnabled: vi.fn().mockReturnValue(true),
+ TelemetryReporter: {
+ initialize: vi.fn(() => mockReporter),
+ getInstance: vi.fn(() => mockReporter),
+ _reset: vi.fn(),
+ },
+}));
+
 // Generic test manifest for test plugins
 const createTestManifest = (name: string): PluginManifest => ({
  name,
@@ -629,6 +647,60 @@ describe("AppKit", () => {
  });
  });
 
+ describe("internal telemetry", () => {
+ test("initializes the reporter and fires sendStartup after createApp", async () => {
+ const { TelemetryReporter } = await import("../../internal-telemetry");
+ mockReporter.sendStartup.mockClear();
+ mockReporter.start.mockClear();
+ vi.mocked(TelemetryReporter.initialize).mockClear();
+
+ await createApp({
+ plugins: [{ plugin: CoreTestPlugin, config: {}, name: "coreTest" }],
+ });
+
+ // Allow the fire-and-forget promise chain to resolve
+ await new Promise((r) => setTimeout(r, 10));
+
+ expect(TelemetryReporter.initialize).toHaveBeenCalledWith(
+ expect.objectContaining({
+ appkitVersion: expect.any(String),
+ client: expect.anything(),
+ }),
+ );
+ expect(mockReporter.start).toHaveBeenCalledOnce();
+ expect(mockReporter.sendStartup).toHaveBeenCalledOnce();
+ });
+
+ test("skips bootstrap when isInternalTelemetryEnabled returns false", async () => {
+ const { isInternalTelemetryEnabled, TelemetryReporter } = await import(
+ "../../internal-telemetry"
+ );
+ vi.mocked(TelemetryReporter.initialize).mockClear();
+ mockReporter.sendStartup.mockClear();
+ vi.mocked(isInternalTelemetryEnabled).mockReturnValue(false);
+
+ await createApp({ plugins: [] });
+
+ await new Promise((r) => setTimeout(r, 10));
+
+ expect(TelemetryReporter.initialize).not.toHaveBeenCalled();
+ expect(mockReporter.sendStartup).not.toHaveBeenCalled();
+ vi.mocked(isInternalTelemetryEnabled).mockReturnValue(true);
+ });
+
+ test("does not crash startup if sendStartup rejects", async () => {
+ mockReporter.sendStartup.mockRejectedValueOnce(
+ new Error("telemetry failure"),
+ );
+
+ const instance = await createApp({
+ plugins: [{ plugin: CoreTestPlugin, config: {}, name: "coreTest" }],
+ });
+
+ expect(instance).toBeDefined();
+ });
+ });
+
  describe("SDK context binding", () => {
  test("should bind SDK methods to plugin instance", async () => {
  class ContextTestPlugin implements BasePlugin {

packages/appkit/src/internal-telemetry/appkit-log.ts

@@ -0,0 +1,58 @@
+// IMPORTANT: keep this file in sync with the AppkitLog proto schema served by
+// the Databricks client telemetry endpoint. Field names use proto JSON
+// conventions (snake_case) so the wire format matches the backend.
+
+export type AppkitEventName =
+ | "APPKIT_EVENT_NAME_UNSPECIFIED"
+ | "APP_STARTUP"
+ | "HEARTBEAT"
+ | "REQUEST_METRICS";
+
+export type AppStartupEvent = Record<string, never>;
+
+export type HeartbeatEvent = Record<string, never>;
+
+export interface RequestMetricsEvent {
+ endpoint?: string;
+ request_count?: number;
+ request_latency_ms_avg?: number;
+ response_count_http4xx?: number;
+ response_count_http5xx?: number;
+}
+
+export interface AppkitLog {
+ event_name: AppkitEventName;
+ app_id?: string;
+ appkit_version?: string;
+ app_startup_event?: AppStartupEvent;
+ heartbeat_event?: HeartbeatEvent;
+ request_metrics_event?: RequestMetricsEvent;
+}
+
+interface AppkitLogEnvelope {
+ frontend_log_event_id: string;
+ inferred_timestamp_millis: number;
+ entry: { appkit_log: AppkitLog };
+}
+
+interface TelemetryPayload {
+ uploadTime: number;
+ items: never[];
+ protoLogs: string[];
+}
+
+export function wrapAppkitLog(log: AppkitLog): AppkitLogEnvelope {
+ return {
+ frontend_log_event_id: `appkit-${log.event_name.toLowerCase()}-${crypto.randomUUID()}`,
+ inferred_timestamp_millis: Date.now(),
+ entry: { appkit_log: log },
+ };
+}
+
+export function buildAppkitPayload(logs: AppkitLog[]): TelemetryPayload {
+ return {
+ uploadTime: Date.now(),
+ items: [],
+ protoLogs: logs.map((log) => JSON.stringify(wrapAppkitLog(log))),
+ };
+}

packages/appkit/src/internal-telemetry/config.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks whether internal telemetry is enabled.
+ * Shared across all telemetry event types (startup, heartbeat, metrics, etc.).
+ */
+export function isInternalTelemetryEnabled(opts?: {
+ disableInternalTelemetry?: boolean;
+}): boolean {
+ if (opts?.disableInternalTelemetry) return false;
+ if (process.env.DISABLE_APPKIT_INTERNAL_TELEMETRY === "true") return false;
+ if (process.env.DO_NOT_TRACK === "1") return false;
+ return true;
+}

packages/appkit/src/internal-telemetry/index.ts

@@ -0,0 +1,8 @@
+// Internal telemetry: APP_STARTUP, HEARTBEAT, and REQUEST_METRICS events
+// POSTed to /telemetry-ext so the Databricks team can prioritize SDK work.
+// Disable with disableInternalTelemetry: true on createApp,
+// DISABLE_APPKIT_INTERNAL_TELEMETRY=true, or DO_NOT_TRACK=1.
+// Full data inventory: docs/docs/privacy.mdx.
+
+export { isInternalTelemetryEnabled } from "./config";
+export { TelemetryReporter } from "./reporter";