drizzle-otel/packages/otel-better-auth

@kubiks/otel-better-auth

OpenTelemetry instrumentation for Better Auth. One-line setup for complete auth observability across all auth flows.

Visualize your authentication flows with detailed span information including operation type, user IDs, session IDs, auth methods, and success/failure status.

Installation

npm install @kubiks/otel-better-auth
# or
pnpm add @kubiks/otel-better-auth

Peer Dependencies: @opentelemetry/api >= 1.9.0, better-auth >= 1.0.0

Usage

Quick Start

import { betterAuth } from "better-auth";
import { instrumentBetterAuth } from "@kubiks/otel-better-auth";

export const auth = instrumentBetterAuth(
  betterAuth({
    database: db,
    // ... your Better Auth config
  }),
);

Instrumenting Better Auth is just a single call—wrap the instance you already create and every API method invocation is traced automatically. Keep the rest of your configuration unchanged.

What Gets Traced

Authentication:

• auth.http.oauth.callback.{provider} - OAuth callback with user ID ✅
• auth.http.signin.email - Email signin with user ID
• auth.http.signup.email - Email signup with user ID
• auth.http.oauth.initiate.{provider} - OAuth initiation
• auth.http.signout - User signout
• auth.http.get_session - Get session

Account & Password:

• auth.http.verify_email - Email verification
• auth.http.forgot_password - Password reset request
• auth.http.reset_password - Password reset

Session Management:

• auth.api.get_session - Get current session with user ID and session ID
• auth.api.list_sessions - List all sessions
• auth.api.revoke_session - Revoke a session
• auth.api.revoke_sessions - Revoke multiple sessions
• auth.api.revoke_other_sessions - Revoke all other sessions

Account Management:

• auth.api.link_social_account - Link social account
• auth.api.unlink_account - Unlink account
• auth.api.list_user_accounts - List user accounts
• auth.api.update_user - Update user profile
• auth.api.delete_user - Delete user account

Password Management:

• auth.api.change_password - Change password
• auth.api.set_password - Set password
• auth.api.forget_password - Forgot password request
• auth.api.reset_password - Reset password

Email Management:

• auth.api.change_email - Change email
• auth.api.verify_email - Verify email with user ID
• auth.api.send_verification_email - Send verification email

Span Attributes

Each span includes:

Attribute	Description	Example
auth.operation	Type of operation	signin, signup, get_session, signout
auth.method	Auth method	email, oauth
auth.provider	OAuth provider (when applicable)	google, github
auth.success	Operation success	true, false
auth.error	Error message (when failed)	Invalid credentials
user.id	User ID (when available)	user_123456
user.email	User email (when available)	user@example.com
session.id	Session ID (when available)	session_abcdef

Configuration

instrumentBetterAuth(authClient, {
  tracerName: "my-app", // Custom tracer name
  tracer: customTracer, // Custom tracer instance
});

Examples

// lib/auth.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { instrumentBetterAuth } from "@kubiks/otel-better-auth";
import { db } from "./db";

export const auth = instrumentBetterAuth(
  betterAuth({
    baseURL: process.env.BETTER_AUTH_URL,
    database: drizzleAdapter(db, { provider: "pg" }),
    socialProviders: {
      github: {
        clientId: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET,
      },
    },
  }),
);

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
export { GET, POST } = auth.handler;

License

MIT