@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

4.5 KiB Raw Permalink Blame History