# BT.stats

## 功能

返回当前 BT 进程的运行期资源统计，用于定位 I/O 运行边界、后台任务、定时器、网络服务、FFI 资源和 VM 缓存状态。

## 语法

```bt
BT.stats()
```

## 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ |
| 无 | - | 否 | 无 | 不需要参数。 |

## 返回值

| 类型 | 说明 |
| ------ | ------ |
| Object | 返回运行期资源统计对象。字段见下方“返回对象字段”。 |

## 返回对象字段

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| uptime | Int | 是 | 当前 BT 进程已运行秒数，按当前 Unix 时间戳减 `start_time` 计算。 |
| threads | Int | 是 | 当前系统可用并行线程数。读取失败时返回 `1`。 |
| start_time | Int | 是 | BT 进程启动时间戳，单位秒。 |
| io | Object | 是 | 进程级 I/O runtime 和 blocking pool 的配置、活动数、完成数、拒绝数、超时数。 |
| task | Object | 是 | 后台 task 执行器是否启动、队列上限、工作线程、排队数、运行数、完成数、拒绝数。 |
| timer | Object | 是 | 定时器运行时是否启动、活动定时器数、调度堆条目数、上限和单 VM 事件队列上限。 |
| net | Object | 是 | 网络 Web 服务数、事件型服务数、有界事件队列、连接和消息资源上限。 |
| http | Object | 是 | HTTP client 池配置、条目数、命中数、淘汰数、创建失败数和慢调用数。 |
| mysql | Object | 是 | MySQL 普通查询连接池配置、DSN 分组数、连接数、命中数、淘汰数、创建失败数和慢调用数。 |
| bytes | Object | 是 | Bytes 缓冲上限和配置错误。 |
| ffi | Object | 是 | FFI 是否启用、打开动态库数量、Buffer 数量和实际分配字节数。 |
| cache | Object | 是 | 当前线程 include 编译缓存和模板片段缓存条目数、字节数、命中、失效和淘汰统计。 |
| permission | Object | 是 | 权限配置快照、当前实际允许能力和权限拒绝次数。 |

ffi 字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| enabled | Bool | 是 | 当前构建是否启用 FFI feature。 |
| open_libraries | Int | 是 | 当前逻辑打开的动态库数量，上限 32。 |
| buffers | Int | 是 | 当前存活的 FfiBuffer 数量，上限 256。 |
| buffer_bytes | Int | 是 | 当前 FfiBuffer 按 16 字节向上取整后的实际分配总量，上限 64 MiB。 |

I/O 默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_IO_WORKERS | CPU 线程数，最大 64 | 共享 Tokio runtime 工作线程数。 |
| BT_IO_BLOCKING_WORKERS | CPU 线程数，最大 64 | 有界 blocking pool 工作线程数。 |
| BT_IO_BLOCKING_QUEUE | 256，最大 8192 | blocking pool 等待队列长度。 |
| BT_IO_TIMEOUT_MS | 30000 | 默认同步等待超时时间，单位毫秒。 |
| BT_IO_SHUTDOWN_TIMEOUT_MS | 1000 | blocking pool 关闭等待时间，单位毫秒。 |

io 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| async_runtime_started | Bool | 是 | 共享 Tokio runtime 是否已经初始化。 |
| async_active | Int | 是 | 当前正在执行的异步 I/O 任务数量。 |
| async_completed | Int | 是 | 已完成的异步 I/O 任务数量。 |
| async_failed | Int | 是 | 执行失败的异步 I/O 任务数量。 |
| async_timeouts | Int | 是 | 同步等待异步任务结果时发生超时的次数。 |
| async_rejected | Int | 是 | 因运行时关闭或调度失败被拒绝的异步任务数量。 |
| blocking_pool_started | Bool | 是 | 有界 blocking pool 是否已经初始化。 |
| blocking_queued | Int | 是 | 当前排队等待执行的 blocking 任务数量。 |
| blocking_running | Int | 是 | 当前正在执行的 blocking 任务数量。 |
| blocking_completed | Int | 是 | 已完成的 blocking 任务数量。 |
| blocking_rejected | Int | 是 | 因队列满或线程池关闭被拒绝的 blocking 任务数量。 |
| blocking_timeouts | Int | 是 | blocking 任务等待结果超时次数。 |
| blocking_shutdown | Bool | 是 | blocking pool 是否已经进入关闭状态。 |
| config | Object | 是 | I/O 配置快照，包含 `async_workers`、`blocking_workers`、`blocking_queue_limit`、`default_timeout_ms`、`shutdown_timeout_ms`。 |

io.config 字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| async_workers | Int | 是 | 共享 Tokio runtime 工作线程数。 |
| blocking_workers | Int | 是 | 有界 blocking pool 工作线程数。 |
| blocking_queue_limit | Int | 是 | blocking pool 等待队列长度上限。 |
| default_timeout_ms | Int | 是 | 默认同步等待超时时间，单位毫秒。 |
| shutdown_timeout_ms | Int | 是 | blocking pool 关闭等待时间，单位毫秒。 |

task 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| executor_started | Bool | 是 | 后台 task 执行器是否已经初始化。 |
| queue_limit | Int | 是 | 后台 task 等待队列长度上限。 |
| workers | Int | 是 | 后台 task worker 数量。 |
| queued | Int | 是 | 当前排队等待执行的 task 数量。 |
| running | Int | 是 | 当前正在执行的 task 数量。 |
| completed | Int | 是 | 已完成的 task 数量。 |
| rejected | Int | 是 | 因队列满或执行器关闭被拒绝的 task 数量。 |

timer 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| runtime_started | Bool | 是 | 定时器运行时是否已经初始化。 |
| active | Int | 是 | 当前活动定时器数量。 |
| queued | Int | 是 | 当前调度堆中的定时器条目数量。 |
| limit | Int | 是 | 当前进程允许的活动定时器数量上限。 |
| event_queue_limit | Int | 是 | 单个 VM 定时器事件队列长度上限。 |

net 默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_NET_EVENT_QUEUE | 4096，最大 65536 | TCP、UDP、WebSocket 后台事件投递到 VM 的有界队列长度。 |
| BT_NET_CONNECTION_LIMIT | 4096，最大 65536 | 单协议连接或 socket 数量上限。 |
| BT_NET_MESSAGE_LIMIT | 1048576，最大 16777216 | 单条 TCP/UDP/WebSocket 消息字节上限。 |
| BT_NET_WRITE_QUEUE | 1024，最大 8192 | 单个 TCP/WebSocket 连接的待写命令队列长度。 |
| BT_NET_IDLE_TTL_MS | 0 | TCP/WebSocket 连接空闲关闭时间，单位毫秒；0 表示不因空闲主动关闭。 |

net 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| runtime_started | Bool | 是 | 网络运行时是否已经初始化。 |
| web_services | Int | 是 | 当前由 `net.listen({type:'web'})` 或 Web 运行器持有的 Web 服务数量。 |
| event_services | Int | 是 | 当前 TCP、UDP、WebSocket 事件型服务数量。 |
| event_queue_bounded | Bool | 是 | 是否启用有界网络事件队列。当前固定为 `true`。 |
| event_queue_limit | Int/Empty | 是 | 网络事件队列上限。未启用事件队列时为 `empty`。 |
| event_queue_queued | Int | 是 | 当前等待 VM 分发的网络事件数量。 |
| event_queue_sent | Int | 是 | 已成功投递到 VM 的网络事件数量。 |
| event_queue_rejected | Int | 是 | 因队列满或通道关闭被拒绝的网络事件数量。 |
| connection_limit | Int | 是 | 单协议连接或 socket 数量上限。 |
| message_limit | Int | 是 | 单条消息字节上限。 |
| write_queue_limit | Int | 是 | 单连接写队列上限。 |
| idle_ttl_ms | Int | 是 | TCP/WebSocket 连接空闲关闭时间，单位毫秒；`0` 表示关闭该策略。 |

Bytes 默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_BYTES_LIMIT | 16777216，最大 67108864 | 单个 Bytes 缓冲最大字节数。 |

bytes 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| limit | Int | 是 | 单个 Bytes 缓冲上限，单位字节。 |
| config_error | String/Empty | 是 | Bytes 配置错误文本；无错误时为 `empty`。 |

cache 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| compiled_file_entries | Int | 是 | 当前线程 include/Web 入口文件编译缓存条目数。 |
| compiled_file_limit | Int | 是 | 当前线程文件编译缓存条目上限。 |
| compiled_file_bytes | Int | 是 | 当前线程文件编译缓存估算字节数。 |
| compiled_file_bytes_limit | Int | 是 | 当前线程文件编译缓存估算字节上限。 |
| compiled_file_hits | Int | 是 | 文件编译缓存命中次数。 |
| compiled_file_misses | Int | 是 | 文件编译缓存未命中次数。 |
| compiled_file_invalidations | Int | 是 | 文件元信息、源码指纹、源码模式、编译配置或字节码格式变化导致的失效次数。 |
| compiled_file_evictions | Int | 是 | 文件编译缓存因条目数或字节数达到上限而淘汰的次数。 |
| compiled_file_fingerprint_checks | Int | 是 | 对最近修改文件执行内容指纹复核的次数。 |
| template_fragment_entries | Int | 是 | 当前线程模板片段编译缓存条目数。 |
| template_fragment_limit | Int | 是 | 当前线程模板片段缓存条目上限。 |
| template_fragment_bytes | Int | 是 | 当前线程模板片段缓存估算字节数。 |
| template_fragment_bytes_limit | Int | 是 | 当前线程模板片段缓存估算字节上限。 |
| template_fragment_hits | Int | 是 | 模板片段缓存命中次数。 |
| template_fragment_misses | Int | 是 | 模板片段缓存未命中次数。 |
| template_fragment_evictions | Int | 是 | 模板片段缓存因条目数或字节数达到上限而淘汰的次数。 |
| template_fragment_bypassed | Int | 是 | 模板片段过大或超过缓存容量时跳过缓存的次数。 |
| template_fragment_max_code_bytes | Int | 是 | 单个模板片段允许缓存的最大源码字节数。 |

permission 默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_PERMISSION_ALLOW | 未配置 | 允许能力列表。配置后只允许列表内能力；支持 `fs`、`process`、`net`、`http`、`mysql`、`device`、`env`、`desktop`、`all`、`none`。 |
| BT_PERMISSION_DENY | 未配置 | 拒绝能力列表。拒绝列表优先级高于允许列表。 |

permission 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| denied | Int | 是 | 当前进程内权限拒绝次数。 |
| config | Object | 是 | 权限配置快照。字段见下方 `permission.config 字段`。 |

permission.config 字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| allow_configured | Bool | 是 | 是否显式配置了 `BT_PERMISSION_ALLOW`。 |
| allow | Array | 是 | 允许列表中的能力名称；未配置时返回全部能力。 |
| deny | Array | 是 | 拒绝列表中的能力名称。 |
| allowed | Array | 是 | 当前实际允许的能力名称。 |
| config_error | String/Empty | 是 | 权限配置错误文本；没有错误时为 `empty`。 |

HTTP client 池默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_HTTP_CLIENT_POOL | true | 是否启用 HTTP client 池。 |
| BT_HTTP_CLIENT_POOL_LIMIT | 32，最大 1024 | 最多保留的 client 配置分组数量。 |
| BT_HTTP_CLIENT_IDLE_TTL_MS | 300000 | client 空闲保留时间，单位毫秒；0 表示不按空闲时间淘汰。 |
| BT_HTTP_SLOW_MS | 0 | 慢 HTTP 调用日志阈值，单位毫秒；0 表示关闭。 |

http 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| pool_started | Bool | 是 | HTTP client 池是否已经初始化。 |
| entries | Int | 是 | 当前池内 client 条目数。 |
| hits | Int | 是 | 池命中次数。 |
| misses | Int | 是 | 池未命中次数。 |
| created | Int | 是 | client 创建次数。 |
| evicted | Int | 是 | client 淘汰次数。 |
| bypassed | Int | 是 | 因关闭池或 Cookie 存储语义而绕过池的次数。 |
| build_failed | Int | 是 | client 创建失败次数。 |
| slow_calls | Int | 是 | 超过 `BT_HTTP_SLOW_MS` 的慢调用次数。 |
| config | Object | 是 | 当前 HTTP client 池配置。字段见下方 `http.config 字段`。 |

http.config 字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| enabled | Bool | 是 | 是否启用 HTTP client 池。 |
| pool_limit | Int | 是 | 最多保留的 client 配置分组数量。 |
| idle_ttl_ms | Int | 是 | client 空闲保留时间，单位毫秒；`0` 表示不按空闲时间淘汰。 |
| slow_ms | Int | 是 | 慢 HTTP 调用日志阈值，单位毫秒；`0` 表示关闭。 |
| config_error | String/Empty | 是 | HTTP client 池配置错误文本；没有错误时为 `empty`。 |

MySQL 普通查询连接池默认配置：

| 环境变量 | 默认值 | 说明 |
| ------ | ------ | ------ |
| BT_MYSQL_POOL | true | 是否启用普通查询全局连接池。 |
| BT_MYSQL_POOL_LIMIT | 16，最大 256 | 最多保留的 DSN 分组数量。 |
| BT_MYSQL_POOL_MIN_CONNECTIONS | 0 | 每个连接池最小连接数。 |
| BT_MYSQL_POOL_MAX_CONNECTIONS | 8，最大 1024 | 每个连接池最大连接数。 |
| BT_MYSQL_POOL_IDLE_TTL_MS | 300000 | 连接池空闲保留时间，单位毫秒；0 表示不按空闲时间淘汰。 |
| BT_MYSQL_CONNECT_TIMEOUT_MS | 5000 | 获取连接的超时时间，单位毫秒。 |
| BT_MYSQL_QUERY_TIMEOUT_MS | 30000 | 单次 SQL 调用同步等待超时时间，单位毫秒。 |
| BT_MYSQL_SLOW_MS | 0 | 慢 MySQL 调用日志阈值，单位毫秒；0 表示关闭。 |

mysql 主要字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| pool_started | Bool | 是 | MySQL 全局连接池是否已经初始化。 |
| entries | Int | 是 | 当前池内 DSN 分组数量，不包含 DSN 明文。 |
| connections | Int | 是 | 当前 SQLx 池中已打开连接总数。 |
| idle_connections | Int | 是 | 当前 SQLx 池中空闲连接总数。 |
| hits | Int | 是 | 池命中次数。 |
| misses | Int | 是 | 池未命中次数。 |
| created | Int | 是 | 池创建次数。 |
| evicted | Int | 是 | 池淘汰次数。 |
| bypassed | Int | 是 | 因关闭全局池而绕过池的次数。 |
| build_failed | Int | 是 | 池创建失败次数。 |
| slow_calls | Int | 是 | 超过 `BT_MYSQL_SLOW_MS` 的慢调用次数。 |
| transactions_active | Int | 是 | 当前活动事务数量。 |
| transactions_started | Int | 是 | 事务开始次数。 |
| transactions_committed | Int | 是 | 事务提交次数。 |
| transactions_rolled_back | Int | 是 | 事务回滚次数，包含 `close()` 对活动事务执行的默认回滚。 |
| transactions_closed | Int | 是 | `close()` 成功关闭活动事务次数。 |
| transactions_failed | Int | 是 | 事务开始、提交、回滚或关闭失败次数。 |
| config | Object | 是 | 当前 MySQL 池配置。字段见下方 `mysql.config 字段`。 |

mysql.config 字段：

| 字段 | 类型 | 必定存在 | 说明 |
| ------ | ------ | ------ | ------ |
| enabled | Bool | 是 | 是否启用普通查询全局连接池。 |
| pool_limit | Int | 是 | 最多保留的 DSN 分组数量。 |
| min_connections | Int | 是 | 每个连接池最小连接数。 |
| max_connections | Int | 是 | 每个连接池最大连接数。 |
| idle_ttl_ms | Int | 是 | 连接池空闲保留时间，单位毫秒；`0` 表示不按空闲时间淘汰。 |
| connect_timeout_ms | Int | 是 | 获取连接的超时时间，单位毫秒。 |
| query_timeout_ms | Int | 是 | 单次 SQL 调用同步等待超时时间，单位毫秒。 |
| slow_ms | Int | 是 | 慢 MySQL 调用日志阈值，单位毫秒；`0` 表示关闭。 |
| config_error | String/Empty | 是 | MySQL 池配置错误文本；没有错误时为 `empty`。 |

## 代码示例

```bt
stats = BT.stats()
result = stats.http.config.pool_limit

// 输出：32
print result
```

## 注意事项

- `BT.stats()` 按需读取统计，不会在 VM 普通指令执行时维护重型计数。
- `cache` 统计只反映当前线程的 VM 线程本地缓存；Web 多 worker 场景下，每个 worker 会各自维护缓存。
- 文件编译缓存稳定命中时只检查 mtime、长度和版本；最近修改的文件会低频复核内容指纹，避免同长度快速改写后执行旧字节码。
- `net.event_queue_rejected` 大于 0 表示网络事件队列发生过满载，TCP/WebSocket 消息事件会触发连接关闭，UDP 报文会被丢弃。
- `http.bypassed` 增长通常表示关闭了 HTTP client 池，或请求启用了 `cookie_store(true)`。
- `mysql.entries`、`mysql.connections` 和事务统计不包含 DSN 明文或密码；连接失败和慢调用日志也会避免输出 DSN 密码。
- `bytes.limit` 控制脚本和 I/O 边界能创建的单个 Bytes 最大长度，避免二进制缓冲无上限增长。
- `ffi` 统计只维护打开 Library 和 Buffer 资源额度，不在原生函数调用热路径累计次数或 cache hit。
- `permission.denied` 大于 0 表示脚本触发过被当前配置拒绝的能力；权限拒绝是明确运行时错误，不会返回 `empty`。
- I/O 环境变量配置错误会在第一次使用相关 I/O 能力时报错，不会静默回退到危险默认值。