# BT.stats

## Function

 returns the runtime resource statistics of the current BT process, which is used to locate I/O running boundaries, background tasks, timers, network services, FFI resources and VM cache status.

## Syntax

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

## Parameters

| Parameters | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| None | - | No | None | No parameters required. |

## Return Value

| Type | Description |
| ------ | ------ |
| Object | Returns the runtime resource statistics object. See "Return Object Fields" below for fields. |

## Return object field

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| uptime | Int | Yes | The number of seconds the current BT process has been running, calculated by subtracting `start_time` from the current Unix timestamp. |
| threads | Int | Yes | Number of parallel threads available in the current system. `1` is returned when the read fails. |
| start_time | Int | Yes | BT process startup timestamp, in seconds. |
| io | Object | Yes | Configuration, number of activities, number of completions, number of rejections, and number of timeouts for the process-level I/O runtime and blocking pool. |
| task | Object | Yes | Whether the background task executor is started, the upper limit of the queue, the number of worker threads, the number of queues, the number of runs, the number of completions, and the number of rejections. |
| timer | Object | Yes | Whether the timer runtime is started, the number of active timers, the number of scheduling heap entries, the upper limit, and the single VM event queue upper limit. |
| net | Object | Yes | Network Web services, event services, bounded event queues, connection and message resource limits. |
| http | Object | Yes | HTTP client pool configuration, number of entries, hits, eliminations, creation failures, and slow calls. |
| mysql | Object | Yes | MySQL normal query connection pool configuration, number of DSN groups, number of connections, number of hits, number of eliminations, number of creation failures and number of slow calls. |
| bytes | Object | Yes | Bytes Buffer limit and configuration error. |
| ffi | Object | Yes | Whether FFI is enabled, the number of open dynamic libraries, the number of Buffers and the actual number of allocated bytes. |
| cache | Object | Yes | Current thread include Compilation cache and template fragment cache entry count, byte count, hit, invalidation, and eviction statistics. |
| permission | Object | Yes | Permission configuration snapshot, current actual allowed capabilities and number of permission denials. |

ffi Field:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| enabled | Bool | Yes | Whether the FFI feature is enabled for the current build. |
| open_libraries | Int | Yes | The number of dynamic libraries currently opened logically, the upper limit is 32. |
| buffers | Int | Yes | The current number of surviving FfiBuffers, the upper limit is 256. |
| buffer_bytes | Int | Yes | The actual total allocation of the current FfiBuffer after rounding up to 16 bytes, with an upper limit of 64 MiB. |

I/O default configuration:

| Environment variables | Default value | Description |
| ------ | ------ | ------ |
| BT_IO_WORKERS | Number of CPU threads, maximum 64 | Number of shared Tokio runtime worker threads. |
| BT_IO_BLOCKING_WORKERS | Number of CPU threads, max 64 | Number of bounded blocking pool worker threads. |
| BT_IO_BLOCKING_QUEUE | 256, maximum 8192 | blocking pool wait queue length. |
| BT_IO_TIMEOUT_MS | 30000 | Default synchronization wait timeout, in milliseconds. |
| BT_IO_SHUTDOWN_TIMEOUT_MS | 1000 | Blocking pool shutdown waiting time, in milliseconds. |

io Main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| async_runtime_started | Bool | Yes | Shared Whether the Tokio runtime has been initialized. |
| async_active | Int | Yes | The number of asynchronous I/O tasks currently executing. |
| async_completed | Int | Yes | The number of asynchronous I/O tasks that have been completed. |
| async_failed | Int | Yes | The number of asynchronous I/O tasks that failed. |
| async_timeouts | Int | Yes | The number of timeouts that occurred while waiting synchronously for the results of an asynchronous task. |
| async_rejected | Int | Yes | The number of asynchronous tasks that were rejected due to runtime shutdown or scheduling failure. |
| blocking_pool_started | Bool | Yes | Whether the bounded blocking pool has been initialized. |
| blocking_queued | Int | Yes | The number of blocking tasks currently queued for execution. |
| blocking_running | Int | Yes | The number of blocking tasks currently being executed. |
| blocking_completed | Int | Yes | The number of completed blocking tasks. |
| blocking_rejected | Int | Yes | The number of blocking tasks that were rejected because the queue was full or the thread pool was closed. |
| blocking_timeouts | Int | Yes | The number of blocking task timeouts waiting for results. |
| blocking_shutdown | Bool | Yes | Whether the blocking pool has entered the shutdown state. |
| config | Object | Yes | I/O configuration snapshot, including `async_workers`, `blocking_workers`, `blocking_queue_limit`, `default_timeout_ms`, `shutdown_timeout_ms`. |

io.config Fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| async_workers | Int | Yes | Number of shared Tokio runtime worker threads. |
| blocking_workers | Int | Yes | Number of bounded blocking pool worker threads. |
| blocking_queue_limit | Int | Yes | blocking pool waiting queue length upper limit. |
| default_timeout_ms | Int | Yes | Default synchronization wait timeout, in milliseconds. |
| shutdown_timeout_ms | Int | Yes | blocking pool shutdown waiting time, in milliseconds. |

task main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| executor_started | Bool | Yes | Whether the background task executor has been initialized. |
| queue_limit | Int | Yes | The upper limit of the background task waiting queue length. |
| workers | Int | Yes | Number of background task workers. |
| queued | Int | Yes | The number of tasks currently queued for execution. |
| running | Int | Yes | The number of tasks currently being executed. |
| completed | Int | Yes | The number of completed tasks. |
| rejected | Int | Yes | The number of tasks that were rejected because the queue was full or the executor was shut down. |

timer main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| runtime_started | Bool | Yes | Whether the timer has been initialized during runtime. |
| active | Int | Yes | The number of currently active timers. |
| queued | Int | Yes | The number of timer entries in the current scheduling heap. |
| limit | Int | Yes | The maximum number of active timers allowed for the current process. |
| event_queue_limit | Int | Yes | Maximum single VM timer event queue length. |

net Default configuration:

| Environment Variables | Default Value | Description |
| ------ | ------ | ------ |
| BT_NET_EVENT_QUEUE | 4096, maximum 65536 | TCP, UDP, WebSocket Bounded queue length for background event delivery to the VM. |
| BT_NET_CONNECTION_LIMIT | 4096, maximum 65536 | Maximum number of single-protocol connections or sockets. |
| BT_NET_MESSAGE_LIMIT | 1048576, maximum 16777216 | The upper limit of single TCP/UDP/WebSocket message bytes. |
| BT_NET_WRITE_QUEUE | 1024, maximum 8192 | The length of the queue of pending writes for a single TCP/WebSocket connection. |
| BT_NET_IDLE_TTL_MS | 0 | TCP/WebSocket connection idle closing time, in milliseconds; 0 means not to actively close due to idleness. |

net main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| runtime_started | Bool | Yes | Whether the network runtime has been initialized. |
| web_services | Int | Yes | The number of web services currently held by `net.listen({type:'web'})` or the web runner. |
| event_services | Int | Yes | The current number of TCP, UDP, and WebSocket event services. |
| event_queue_bounded | Bool | Yes | Whether to enable bounded network event queues. Currently fixed to `true`. |
| event_queue_limit | Int/Empty | Yes | Network event queue limit. `empty` when the event queue is not enabled. |
| event_queue_queued | Int | Yes | The number of network events currently waiting for distribution by the VM. |
| event_queue_sent | Int | Yes | The number of network events that were successfully delivered to the VM. |
| event_queue_rejected | Int | Yes | Number of network events that were rejected because the queue was full or the channel was closed. |
| connection_limit | Int | Yes | The maximum number of single-protocol connections or sockets. |
| message_limit | Int | Yes | The upper limit of bytes in a single message. |
| write_queue_limit | Int | Yes | Single connection write queue limit. |
| idle_ttl_ms | Int | Yes | TCP/WebSocket connection idle closing time, in milliseconds; `0` means closing this policy. |

Bytes Default configuration:

| Environment variable | Default value | Description |
| ------ | ------ | ------ |
| BT_BYTES_LIMIT | 16777216, maximum 67108864 | The maximum number of bytes buffered by a single Bytes. |

bytes Main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| limit | Int | Yes | Single Bytes buffer upper limit, unit byte. |
| config_error | String/Empty | Yes | Bytes Configuration error text; `empty` when there is no error. |

cache Main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| compiled_file_entries | Int | Yes | The number of current thread include/Web entry file compilation cache entries. |
| compiled_file_limit | Int | Yes | The upper limit of current thread file compilation cache entries. |
| compiled_file_bytes | Int | Yes | The estimated number of bytes in the current thread file compilation cache. |
| compiled_file_bytes_limit | Int | Yes | The estimated byte limit of the current thread file compilation cache. |
| compiled_file_hits | Int | Yes | Number of file compilation cache hits. |
| compiled_file_misses | Int | Yes | Number of file compilation cache misses. |
| compiled_file_invalidations | Int | Yes | The number of failures caused by changes in file metainformation, source code fingerprint, source code mode, compilation configuration, or bytecode format. |
| compiled_file_evictions | Int | Yes | The number of times the file compilation cache has been evicted due to the maximum number of entries or bytes being reached. |
| compiled_file_fingerprint_checks | Int | Yes | The number of times to perform content fingerprint checks on recently modified files. |
| template_fragment_entries | Int | Yes | Number of template fragment compilation cache entries for the current thread. |
| template_fragment_limit | Int | Yes | The upper limit of current thread template fragment cache entries. |
| template_fragment_bytes | Int | Yes | The estimated number of bytes of the current thread's template fragment cache. |
| template_fragment_bytes_limit | Int | Yes | The estimated byte limit of the current thread template fragment cache. |
| template_fragment_hits | Int | Yes | Number of template fragment cache hits. |
| template_fragment_misses | Int | Yes | Number of template fragment cache misses. |
| template_fragment_evictions | Int | Yes | The number of times the template fragment cache has been evicted due to the maximum number of entries or bytes being reached. |
| template_fragment_bypassed | Int | Yes | The number of times the template fragment is cached when it is too large or exceeds the cache capacity. |
| template_fragment_max_code_bytes | Int | Yes | The maximum number of source code bytes allowed to be cached for a single template fragment. |

permission Default configuration:

| Environment variable | Default value | Description |
| ------ | ------ | ------ |
| BT_PERMISSION_ALLOW | Not configured | List of allowed capabilities. After configuration, only the capabilities in the list are allowed; support `fs`, `process`, `net`, `http`, `mysql`, `device`, `env`, `desktop`, `all`, `none`. |
| BT_PERMISSION_DENY | Not configured | Deny capability list. Deny lists have higher priority than allow lists. |

permission main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| denied | Int | Yes | The number of permission denials in the current process. |
| config | Object | Yes | Permission configuration snapshot. See the `permission.config` fields below. |

permission.config Field:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| allow_configured | Bool | Yes | Whether `BT_PERMISSION_ALLOW` is explicitly configured. |
| allow | Array | Yes | Capability name in the allow list; returns all capabilities if not configured. |
| deny | Array | Yes | Name of the capability in the deny list. |
| allowed | Array | Yes | The name of the currently allowed capability. |
| config_error | String/Empty | Yes | Permission configuration error text; `empty` when there is no error. |

HTTP client pool default configuration:

| Environment variable | Default value | Description |
| ------ | ------ | ------ |
| BT_HTTP_CLIENT_POOL | true | Whether to enable the HTTP client pool. |
| BT_HTTP_CLIENT_POOL_LIMIT | 32, maximum 1024 | Maximum number of client configuration groups to retain. |
| BT_HTTP_CLIENT_IDLE_TTL_MS | 300000 | client idle retention time, in milliseconds; 0 means not to be eliminated based on idle time. |
| BT_HTTP_SLOW_MS | 0 | Slow HTTP call log threshold, in milliseconds; 0 means off. |

http main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| pool_started | Bool | Yes | Whether the HTTP client pool has been initialized. |
| entries | Int | Yes | The number of client entries in the current pool. |
| hits | Int | Yes | Number of pool hits. |
| misses | Int | Yes | Number of pool misses. |
| created | Int | Yes | Number of client creations. |
| evicted | Int | Yes | The number of client evictions. |
| bypassed | Int | Yes | The number of times the pool was bypassed due to shutdown or cookie storage semantics. |
| build_failed | Int | Yes | Number of client creation failures. |
| slow_calls | Int | Yes | The number of slow calls exceeding `BT_HTTP_SLOW_MS`. |
| config | Object | Yes | The current HTTP client pool configuration. See the `http.config` fields below. |

http.config Fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| enabled | Bool | Yes | Whether to enable the HTTP client pool. |
| pool_limit | Int | Yes | The maximum number of client configuration groups to retain. |
| idle_ttl_ms | Int | Yes | client idle retention time, in milliseconds; `0` means not to be eliminated based on idle time. |
| slow_ms | Int | Yes | Slow HTTP call log threshold, in milliseconds; `0` means closed. |
| config_error | String/Empty | Yes | HTTP client pool configuration error text; `empty` if there is no error. |

MySQL common query connection pool default configuration:

| Environment variable | Default value | Description |
| ------ | ------ | ------ |
| BT_MYSQL_POOL | true | Whether to enable the common query global connection pool. |
| BT_MYSQL_POOL_LIMIT | 16, maximum 256 | Maximum number of DSN packets to retain. |
| BT_MYSQL_POOL_MIN_CONNECTIONS | 0 | Minimum number of connections per connection pool. |
| BT_MYSQL_POOL_MAX_CONNECTIONS | 8, maximum 1024 | Maximum number of connections per connection pool. |
| BT_MYSQL_POOL_IDLE_TTL_MS | 300000 | Connection pool idle retention time, in milliseconds; 0 means no elimination based on idle time. |
| BT_MYSQL_CONNECT_TIMEOUT_MS | 5000 | Get the connection timeout, in milliseconds. |
| BT_MYSQL_QUERY_TIMEOUT_MS | 30000 | Synchronization wait timeout for a single SQL call, in milliseconds. |
| BT_MYSQL_SLOW_MS | 0 | Slow MySQL call log threshold, in milliseconds; 0 means closed. |

mysql main fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| pool_started | Bool | Yes | Whether the MySQL global connection pool has been initialized. |
| entries | Int | Yes | The number of DSN packets in the current pool, excluding DSN plaintext. |
| connections | Int | Yes | The total number of open connections in the current SQLx pool. |
| idle_connections | Int | Yes | Total number of idle connections in the current SQLx pool. |
| hits | Int | Yes | Number of pool hits. |
| misses | Int | Yes | Number of pool misses. |
| created | Int | Yes | Number of pool creations. |
| evicted | Int | Yes | Number of pool evictions. |
| bypassed | Int | Yes | The number of times the pool was bypassed due to closing the global pool. |
| build_failed | Int | Yes | Number of pool creation failures. |
| slow_calls | Int | Yes | The number of slow calls exceeding `BT_MYSQL_SLOW_MS`. |
| transactions_active | Int | Yes | The current number of active transactions. |
| transactions_started | Int | Yes | Number of transactions started. |
| transactions_committed | Int | Yes | Number of transaction commits. |
| transactions_rolled_back | Int | Yes | Number of transaction rollbacks, including the default rollback performed by `close()` on active transactions. |
| transactions_closed | Int | Yes | `close()` Number of active transactions successfully closed. |
| transactions_failed | Int | Yes | The number of transaction start, commit, rollback, or close failures. |
| config | Object | Yes | The current MySQL pool configuration. See the `mysql.config` fields below. |

mysql.config Field:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| enabled | Bool | Yes | Whether to enable the normal query global connection pool. |
| pool_limit | Int | Yes | The maximum number of DSN groups to retain. |
| min_connections | Int | Yes | Minimum number of connections per connection pool. |
| max_connections | Int | Yes | The maximum number of connections per connection pool. |
| idle_ttl_ms | Int | Yes | The idle retention time of the connection pool, in milliseconds; `0` means that it will not be eliminated according to the idle time. |
| connect_timeout_ms | Int | Yes | Get the connection timeout, in milliseconds. |
| query_timeout_ms | Int | Yes | Synchronization wait timeout for a single SQL call, in milliseconds. |
| slow_ms | Int | Yes | Slow MySQL call log threshold, in milliseconds; `0` means closed. |
| config_error | String/Empty | Yes | MySQL pool configuration error text; `empty` if there is no error. |

## Code Examples

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

// Output: 32
print result
```

## Notes

- `BT.stats()` reads statistics on demand and does not maintain heavy counts during normal VM instruction execution.
- `cache` statistics only reflect the VM thread local cache of the current thread; in a Web multi-worker scenario, each worker will maintain its own cache.
- Only mtime, length and version are checked when the file compilation cache is stably hit; recently modified files will be reviewed at low frequency for content fingerprints to avoid executing old bytecode after rapid rewriting of the same length.
- `net.event_queue_rejected` greater than 0 indicates that the network event queue is overloaded, TCP/WebSocket message events will trigger the connection to be closed, and UDP messages will be discarded.
 - `http.bypassed` growth usually indicates that the HTTP client pool is turned off, or that `cookie_store(true)` is requested to be enabled.
 - `mysql.entries`, `mysql.connections` and transaction statistics do not contain DSN plaintext or passwords; connection failure and slow call logs also avoid printing DSN passwords.
 - `bytes.limit` controls the maximum length of a single Bytes that scripts and I/O boundaries can create to avoid unlimited growth of the binary buffer.
- `ffi` statistics only maintain open Library and Buffer resource quotas, not the cumulative number of native function call hot paths or cache hits.
 - `permission.denied` greater than 0 indicates that the script triggered a capability that is denied by the current configuration; permission denial is an explicit runtime error and does not return `empty`.
 - Misconfiguration of I/O environment variables will result in an error the first time the relevant I/O capability is used, without silently falling back to dangerous default values.