dht-crawler 指标参考

启用 Cargo feature metrics 后，库通过 metrics facade 记录以下指标。库不安装 recorder、不监听端口，也不依赖任何特定导出协议；Prometheus exporter 应由最终应用安装。

所有 *_total 都是进程生命周期累计 counter。Gauge 是当前值。Histogram 的记录值使用下表标出的单位。

UDP 与 KRPC

指标	类型	标签	单位/含义
`dht_udp_bytes_received_total`	counter	—	Socket 接收字节
`dht_udp_packets_received_total`	counter	`status=ok	dropped_size
`dht_udp_bytes_sent_total`	counter	—	成功发送字节
`dht_udp_packets_sent_total`	counter	`type=query	response`
`dht_udp_query_size_bytes`	histogram	—	find_node query 编码长度，bytes
`dht_messages_processed_total`	counter	`type=q	r
`dht_messages_parse_error_total`	counter	—	bencode/KRPC 解析失败
`dht_queries_total`	counter	`q=ping	find_node
`dht_udp_responses_dropped_total`	counter	`reason=rate_limit`	最终未发送的限流回复
`dht_udp_responses_priority_reserved_total`	counter	`query=ping	get_peers`

dht_udp_bytes_received_total 包含后续被判定为 invalid/queue-full 的 Datagram；发送侧只在 send_to 成功后累计。

指标	类型	标签	含义
`dht_node_pool_size`	gauge	—	当前 FIFO 节点数
`dht_node_pool_oldest_age_seconds`	gauge	—	FIFO 最老节点年龄
`dht_node_pool_admissions_total`	counter	—	新准入节点
`dht_node_pool_replacements_total`	counter	—	满池替换
`dht_node_pool_dropped_total`	counter	`reason=duplicate	rate_limit
`dht_find_node_in_flight`	gauge	—	当前在途 find_node
`dht_find_node_effective_rate_per_second`	gauge	—	Metadata 压力调整后的实际预算
`dht_crawl_queries_sent_total`	counter	`kind=new	revisit
`dht_find_node_responses_total`	counter	—	与 pending transaction 匹配的回复
`dht_find_node_response_unmatched_total`	counter	—	无匹配 pending 的回复
`dht_find_node_timeouts_total`	counter	—	pending 超时
`dht_find_node_send_failures_total`	counter	—	UDP query 发送失败
`dht_crawl_events_dropped_total`	counter	`kind=discovered	response`
`dht_metadata_queue_pressure_ratio`	gauge	—	Metadata depth/capacity，范围 0..1

actor 每秒把内部增量 flush 到 counter，因此 exporter 看到的 counter 可能最多延迟约一秒。

指标	类型	标签	含义
`dht_sample_infohashes_queries_total`	counter	—	已发送的 BEP-51 查询
`dht_sample_infohashes_responses_total`	counter	—	匹配的 BEP-51 响应
`dht_sample_infohashes_timeouts_total`	counter	—	超时的 BEP-51 请求
`dht_sample_infohashes_hashes_total`	counter	—	已接受并送往 Peer lookup 的新 Hash
`dht_sample_infohashes_in_flight`	gauge	—	当前在途采样请求
`dht_sample_infohashes_dropped_total`	counter	`reason=response_queue_full	peer_lookup_queue_full`

指标	类型	标签	含义
`dht_announce_peer_blocked_total`	counter	`reason=invalid_token	filtered`
`dht_info_hashes_discovered_total`	counter	—	token/hash/filter 校验通过的 InfoHash
`dht_metadata_ingress_dropped_total`	counter	`reason=queue_full`	Hash ingress 满导致的丢弃

指标	类型	标签	单位/含义
`dht_metadata_queue_depth`	gauge	—	Pending Hash 数
`dht_metadata_in_flight`	gauge	—	当前 job 数
`dht_metadata_queue_events_total`	counter	`result=inserted	deduplicated
`dht_metadata_queue_wait_seconds`	histogram	—	Hash 从最近发现到首次分派的秒数
`dht_metadata_jobs_dispatched_total`	counter	—	分派 job 数
`dht_metadata_jobs_completed_total`	counter	`result=accepted	fetch_failed
`dht_metadata_worker_join_error_total`	counter	—	worker task join 失败
`dht_metadata_completion_callback_panics_total`	counter	—	完成回调 panic

指标	类型	标签	单位/含义
`dht_metadata_fetch_attempts_total`	counter	—	实际 Peer 尝试
`dht_metadata_peer_attempts_total`	counter	—	与 fetch attempts 相同的 Peer 尝试计数
`dht_metadata_fetch_success_total`	counter	—	成功下载和解析
`dht_metadata_fetch_result_total`	counter	`result=success	failed
`dht_metadata_fetch_fail_total`	counter	`reason=timeout	send_error
`dht_metadata_connection_result_total`	counter	`result=success	failed`
`dht_metadata_handshake_result_total`	counter	`result=success	no_extension_support`
`dht_metadata_fetch_duration_seconds`	histogram	—	端到端 Peer 尝试秒数
`dht_metadata_size_bytes`	histogram	—	完整 bencoded info payload 字节数
`dht_metadata_bytes_downloaded_total`	counter	—	收到的 Metadata piece 数据字节数
`dht_metadata_peer_failure_cache_hits_total`	counter	`reason=timeout	connect_failed`
`dht_metadata_peer_failure_cache_inserts_total`	counter	`reason=timeout	connect_failed`
`dht_metadata_peer_failure_cache_entries`	gauge	—	当前缓存条目数

dht_metadata_fetch_result_total{result="failed"} 汇总非 timeout 的失败，不适合单独用于分析具体原因；详细原因应结合 fetch_fail、connection 和 handshake 指标。

DhtRuntimeStats 始终可用，与 metrics feature 无关：

snapshot() 提供队列、节点池、crawl、Peer 和 UDP 运行状态。
observability_snapshot() 提供 UDP 字节/包、入站查询分类、announce、节点准入、 Metadata 失败分类、failure cache 分类和固定桶。

两套出口在同一事件点更新，但读取时都不是跨字段事务快照；短时间内可能相差一个并发事件，Prometheus 的 crawl actor counter 还可能有最多约一秒 flush 延迟。