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";