instrumentation

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

OpenTelemetry instrumentation status

Better Auth instrumentation through OpenTelemetry is experimental and may change in future releases. The API and span structure are subject to change.

Instrumentation overview

Better Auth is instrumented through OpenTelemetry for distributed tracing. Spans are emitted for endpoints, hooks, database operations and the plugin lifecycle. The goal is to provide insights into the behavior of the Better Auth instance to help debug issues and optimize performance.

Instrumentation setup requirements

To collect and export traces, you must configure a TracerProvider and a SpanExporter in your application. Better Auth uses the OpenTelemetry API to create spans.

Endpoint spans supported

Better Auth emits the following endpoint spans: (1) '{METHOD} {route}' - Parent span for an auth endpoint, emitted on every auth API call, with attributes http.route (route template) and better_auth.operation_id (operation identifier like getSession). (2) 'handler {route}' - Span around the endpoint handler execution, wrapping the handler inside each endpoint.

Global hook spans supported

Better Auth emits the following global hook spans: (1) 'hook before {route} {source}' - Before-hook for an auth endpoint, emitted when a before hook runs for the route. (2) 'hook after {route} {source}' - After-hook for an auth endpoint, emitted when an after hook runs for the route. Attributes include better_auth.hook.type (before or after), better_auth.context (user for global hooks or plugin:{pluginId} for plugin-registered hooks), http.route (route template), and better_auth.operation_id (operation identifier).

Plugin middleware spans supported

Better Auth emits the following plugin middleware spans: (1) 'onRequest {pluginId}' - Plugin onRequest hook, emitted before request handling. (2) 'onResponse {pluginId}' - Plugin onResponse hook, emitted after response is produced. (3) 'middleware {route} {pluginId}' - Plugin middleware execution, emitted when middleware runs for a route. Attributes include better_auth.hook.type (onRequest, onResponse, or middleware), better_auth.context (plugin:{pluginId} like plugin:bearer or plugin:test-plugin), http.route (route template, on middleware spans only), and http.response.status_code (HTTP response status code, onResponse only).

Database operation spans

Better Auth emits 'db {operation} {model}' spans for all database operations. Operations include: create, findOne, findMany, update, updateMany, delete, deleteMany, count. Models include core models (user, account, session, verification) and plugin-defined models (organization, rateLimit). Attributes are db.operation.name (database operation name like create) and db.collection.name (collection/model name like user).

Database hook spans

Better Auth emits the following database hook spans: (1) 'db {operation}.before {model}' - Before-hook for a create/update/delete operation, emitted when a databaseHooks before hook runs. (2) 'db {operation}.after {model}' - After-hook for a create/update/delete operation, emitted when a databaseHooks after hook runs. Operations are create, update, updateMany, and delete (used for both single delete and deleteMany calls). Attributes include better_auth.hook.type (create.before, create.after, update.before, etc.), better_auth.context (user or plugin:{pluginId}), and db.collection.name (collection/model name).

Telemetry collection: disabled by default, opt-in

Better Auth collects anonymous telemetry data about general usage if enabled. Telemetry is disabled by default and is optional. Since v1.3.5, telemetry collection is available.

Telemetry data points collected

The following data points may be reported: Anonymous identifier (non-reversible hash from package.json name and optionally baseURL), Runtime (name: node | bun | deno, version), Environment (development, production, test, or ci), Framework if detected (name, version for Next.js, Nuxt, React Router, Astro, SvelteKit, etc.), Database if detected (name, version for PostgreSQL, MySQL, SQLite, Prisma, Drizzle, MongoDB, etc.), System info (platform, OS release, architecture, CPU count/model/speed, total memory, isDocker, isWSL, isTTY flags), Package manager (name, version from npm user agent), and Redacted auth config snapshot produced by getTelemetryAuthConfig.

CLI telemetry data collected

Telemetry data protection and non-collection

No PII or secrets are collected: emails, usernames, tokens, secrets, client IDs, client secrets, and database URLs are never collected. The full betterAuth configuration is never sent; instead a reduced, redacted snapshot of non-sensitive toggles and counts is sent. Sensitive values are converted to booleans, counts, or generic identifiers. All collected data is fully anonymous and only useful in aggregate, cannot be traced back to any individual source, and is accessible only to a small group of core Better Auth maintainers.

Enable telemetry via auth config

Telemetry can be enabled in the auth config by setting telemetry.enabled: true in the betterAuth options.

Enable telemetry via environment variable

Telemetry can be enabled or disabled via environment variables: BETTER_AUTH_TELEMETRY=1 to enable or BETTER_AUTH_TELEMETRY=0 to disable.

Telemetry debug mode

Debug mode can be enabled by setting the BETTER_AUTH_TELEMETRY_DEBUG=1 environment variable when running your project or by setting telemetry: { debug: true } in the auth config. In debug mode, telemetry events are logged only to the console.

When telemetry is sent

Telemetry is sent on betterAuth initialization (type: init) and on CLI actions: generate and migrate. Telemetry is disabled automatically in tests (NODE_ENV=test) unless explicitly overridden by internal tooling.

Debug telemetry in auth config example

To enable telemetry debug mode in auth.ts, set the telemetry option with debug: true inside the betterAuth configuration object.

Give your agent this brain