feat: add telemetry (#3822)

* feat: telemetry

Co-authored-by: Kinfe123 <kinfishtech@gmail.com>

* chore: remove changeset

* fix: do not generate project id unless telemetry is enabled

* fix: return `isInsiderContainerCached`

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* chore: remove unused utils file

* fix: properly cache generated project id

* feat: interpret empty env vars as false

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* fix: use nullish coalescing to set fallback

* fix: should be `isInsideContainerCached`

* fix: unique icons + tooltip for telemetry component

* fix: import child process from node

* fix: remove quotes in description

Co-authored-by: Alex Yang <himself65@outlook.com>

* fix: address reviews

Co-authored-by: Alex Yang <himself65@outlook.com>

* chore: refactor

* refactor

* add tests

* cache pkg json

* add cli tracking

* add migrate

* chore fix xi

* skip tet

* update snapshot

* chore: fix typecheck

* Expand telemetry docs: list collected fields, clarify anonymous redaction via getTelemetryAuthConfig, and document CLI events and audit/opt‑out paths.

* docs

* doc cleanup

* fixes

* remove git first commit message

* update docs

---------

Co-authored-by: Kinfe123 <kinfishtech@gmail.com>
Co-authored-by: Bereket Engida <86073083+Bekacru@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: Alex Yang <himself65@outlook.com>
Co-authored-by: Bereket Engida <Bekacru@gmail.com>

docs/content/docs/reference/options.mdx

@@ -636,3 +636,16 @@ export const auth = betterAuth({
 	disabledPaths: ["/sign-up/email", "/sign-in/email"],
 })
 ```
+
+## `telemetry`
+
+Enable or disable Better Auth's telemetry collection. (default: `true`)
+
+```ts
+import { betterAuth } from "better-auth";
+export const auth = betterAuth({
+  telemetry: {
+    enabled: false,
+  }
+})
+```

docs/content/docs/reference/telemetry.mdx

@@ -0,0 +1,68 @@
+---
+title: Telemetry
+description: Better Auth now collects anonymous telemetry data about general usage.
+---
+
+## Why is telemetry collected?
+
+Telemetry data helps us understand how Better Auth is being used across different environments so we can improve performance, prioritize features, and fix issues more effectively. Telemetry data helps us improve Better Auth by giving us insight into how it’s used in real-world environments. It guides our decisions on performance optimizations, feature development, and bug fixes. All data is collected anonymously and with privacy in mind, and users can opt out at any time.
+
+## What is being collected?
+
+The following data points may be reported. Everything is anonymous and intended for aggregate insights only.
+
+- **Anonymous identifier**: A non-reversible hash derived from your project (`package.json` name and optionally `baseURL`). This lets us de‑duplicate events per project without knowing who you are.
+- **Runtime**: `{ name: "node" | "bun" | "deno", version }`.
+- **Environment**: one of `development`, `production`, `test`, or `ci`.
+- **Framework (if detected)**: `{ name, version }` for frameworks like Next.js, Nuxt, Remix, Astro, SvelteKit, etc.
+- **Database (if detected)**: `{ name, version }` for integrations like PostgreSQL, MySQL, SQLite, Prisma, Drizzle, MongoDB, etc.
+- **System info**: platform, OS release, architecture, CPU count/model/speed, total memory, and flags like `isDocker`, `isWSL`, `isTTY`.
+- **Package manager**: `{ name, version }` derived from the npm user agent.
+- **Redacted auth config snapshot**: A minimized, privacy‑preserving view of your `betterAuth` options produced by `getTelemetryAuthConfig`.
+
+We also collect anonymous telemetry from the CLI:
+
+- **CLI generate (`cli_generate`)**: outcome `generated | overwritten | appended | no_changes | aborted` plus redacted config.
+- **CLI migrate (`cli_migrate`)**: outcome `migrated | no_changes | aborted | unsupported_adapter` plus adapter id (when relevant) and redacted config.
+
+You can audit telemetry locally by setting the `BETTER_AUTH_TELEMETRY_DEBUG=1` environment variable when running your project. In this debug mode, telemetry events are logged only to the console.
+
+## How is my data protected?
+
+All collected data is fully anonymous and only useful in aggregate. It cannot be traced back to any individual source and is accessible only to a small group of core Better Auth maintainers to guide roadmap decisions.
+
+- **No PII or secrets**: We do not collect emails, usernames, tokens, secrets, client IDs, client secrets, or database URLs.
+- **No full config**: We never send your full `betterAuth` configuration. Instead we send a reduced, redacted snapshot of non‑sensitive toggles and counts.
+- **Redaction by design**: See [detect-auth-config.ts](https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/telemetry/detectors/detect-auth-config.ts) in the Better Auth source for the exact shape of what is included. It purposely converts sensitive values to booleans, counts, or generic identifiers.
+
+## How can I disable it?
+
+You can disable telemetry collection in your auth config or by setting an environment variable.
+
+- Via your auth config.
+
+  ```ts title="auth.ts"
+  export const auth = betterAuth({
+    // [!code highlight]
+    telemetry: { // [!code highlight]
+      enabled: false // [!code highlight]
+    } // [!code highlight]
+  });
+  ```
+
+- Via an environment variable.
+
+  ```env title=".env"
+  # Enable telemetry
+  BETTER_AUTH_TELEMETRY=1
+
+  # Disable telemetry
+  BETTER_AUTH_TELEMETRY=0
+  ```
+
+### When is telemetry sent?
+
+- On `betterAuth` initialization (`type: "init"`).
+- On CLI actions: `generate` and `migrate` as described above.
+
+Telemetry is disabled automatically in tests (`NODE_ENV=test`) unless explicitly overridden by internal tooling.