# 仪器化（实验性） (/docs/reference/instrumentation)

Better Auth 的分布式追踪



<Callout type="warning">
  OpenTelemetry 仪器化处于实验阶段，未来版本可能发生变化。API 和跨度结构可能会更改。
</Callout>

Better Auth 通过 [OpenTelemetry](https://opentelemetry.io/) 进行分布式追踪的仪器化。为端点、钩子、数据库操作和插件生命周期生成跨度。\
该仪器化的目标是提供关于您的 Better Auth 实例行为的更好洞察，帮助您调试问题并优化性能。

## 设置 [#设置]

Better Auth 使用 OpenTelemetry API 来创建跨度。为了收集和导出追踪，您的应用至少需要配置一个 **TracerProvider** 和一个 **SpanExporter**。

有关设置说明，请参阅官方 OpenTelemetry 文档：

* **[Node.js 入门](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)** – Node.js 应用设置指南

## 禁用仪器化 [#禁用仪器化]

若要阻止 Better Auth 创建 OpenTelemetry 跨度，请将 `experimental.instrumentation.enabled` 设置为 `false`：

```ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  experimental: {
    instrumentation: {
      enabled: false,
    },
  },
});
```

仪器化默认处于启用状态。禁用仪器化仅影响此 auth 实例，不会影响您的应用和其他库生成的跨度。

## 支持的跨度 [#支持的跨度]

Better Auth 支持以下跨度：

### 端点跨度 [#端点跨度]

| 跨度名称               | 描述           | 何时发出                               |
| ------------------ | ------------ | ---------------------------------- |
| `{METHOD} {route}` | 认证端点的父跨度     | 每次认证 API 调用（例如 `GET /get-session`） |
| `handler {route}`  | 围绕端点处理器执行的跨度 | 在每个端点内部，包装处理器                      |

**属性：**

* `http.route` - **路由模板**（低基数）
* `better_auth.operation_id` - 操作标识符（例如 `getSession`）

支持以下全局钩子：

| 跨度名称                           | 描述        | 何时发出                  |
| ------------------------------ | --------- | --------------------- |
| `hook before {route} {source}` | 认证端点的前置钩子 | 当某个路由的 `before` 钩子运行时 |
| `hook after {route} {source}`  | 认证端点的后置钩子 | 当某个路由的 `after` 钩子运行时  |

* **属性：**
  * `better_auth.hook.type` - 钩子类型（例如 `before` 或 `after`）
  * `better_auth.context` - 执行上下文：全局钩子时为 `"user"`，插件注册钩子时为 `"plugin:{pluginId}"`
  * `http.route` - **路由模板**（低基数）
  * `better_auth.operation_id` - 操作标识符（例如 `getSession`）

也支持中间件：

| 跨度名称                            | 描述                  | 何时发出     |
| ------------------------------- | ------------------- | -------- |
| `onRequest {pluginId}`          | 插件的 `onRequest` 钩子  | 请求处理之前   |
| `onResponse {pluginId}`         | 插件的 `onResponse` 钩子 | 生成响应之后   |
| `middleware {route} {pluginId}` | 插件中间件执行             | 路由中间件运行时 |

**属性：**

* `better_auth.hook.type` - 钩子类型：`"onRequest"`、`"onResponse"` 或 `"middleware"`
* `better_auth.context` - 执行上下文：`"plugin:{pluginId}"`（例如 `plugin:bearer`、`plugin:test-plugin`）
* `http.route` - 仅在中间件跨度上为 **路由模板**（低基数）
* `http.response.status_code` - HTTP 响应状态码（仅限 onResponse）

### 数据库跨度 [#数据库跨度]

| 跨度名称                     | 描述       | 何时发出                   |
| ------------------------ | -------- | ---------------------- |
| `db {operation} {model}` | 数据库操作的跨度 | 所有适配器操作（创建、查找一个、查找多个等） |

* **操作：** `create`、`findOne`、`findMany`、`update`、`updateMany`、`delete`、`deleteMany`、`consumeOne`、`incrementOne`、`count`
* **模型：** 核心模型包括 `user`、`account`、`session`、`verification`，以及插件定义的模型（例如 `organization`、`rateLimit`）。
* **属性：**
  * `db.operation.name` - 数据库操作名称（例如 `create`）
  * `db.collection.name` - 数据库集合/模型名称（例如 `user`）

此外，定义了数据库钩子时还会生成以下跨度：

| 跨度名称                            | 描述            | 何时发出                               |
| ------------------------------- | ------------- | ---------------------------------- |
| `db {operation}.before {model}` | 创建/更新/删除的前置钩子 | 当 `databaseHooks` 的 `before` 钩子运行时 |
| `db {operation}.after {model}`  | 创建/更新/删除的后置钩子 | 当 `databaseHooks` 的 `after` 钩子运行时  |

* **操作：** `create`、`update`、`updateMany`、`delete`（用于单个删除和 `deleteMany` 调用）
* **属性：**
  * `better_auth.hook.type` - 钩子类型（例如 `create.before`、`create.after`、`update.before`）
  * `better_auth.context` - 执行上下文：`"user"` 或 `"plugin:{pluginId}"`
  * `db.collection.name` - 数据库集合/模型名称（例如 `user`)