docs(metrics): introduce METRICS_CHANGELOG.md

Add a single discovery point for Prometheus metric additions, changes,
and removals so node operators and dashboard maintainers do not need to
scan individual pull requests. Sectioning mirrors java-tron GitHub
Releases (Notice / New Features / ... grouped by module) for
consistency with the rest of the repository.

The 4.8.2 section records the two metrics introduced in tronprotocol#6624
(`tron:block_transaction_count`, `tron:sr_set_change`) and a
Pre-4.8.2 baseline snapshot of all metrics emitted prior to this file,
so the document doubles as a quick reference catalog. Per-version
provenance for baseline entries is not tracked; the file points at
git log on common/src/main/java/org/tron/common/prometheus/ for that.

Author: warku123

METRICS_CHANGELOG.md

@@ -0,0 +1,85 @@
+Metrics Changelog
+=================
+
+This file tracks Prometheus metric additions, changes, and removals in java-tron. For the full set of metrics emitted today, see the references at the bottom.
+
+**4.8.2**
+
+### New Metrics
+
+#### Core
+
+- `tron:block_transaction_count` (Histogram, label `miner_address`) — per-block transaction count, sampled at the entry of `Manager#pushBlock` before any early return so duplicate, stale, and fork-switched pushes are observed alongside applied blocks. Primary use cases: empty-block detection per super representative, and per-SR throughput observation. Default buckets: `[0, 1, 10, 50, 100, 200, 500, 1000, 2000, 5000]`. ([#6624](https://github.com/tronprotocol/java-tron/pull/6624))
+
+#### Consensus
+
+- `tron:sr_set_change` (Counter, labels `witness`, `event`) — incremented once per witness whenever the active SR set rotates at a maintenance boundary. `event` is one of `added` / `removed`. Cardinality grows with the number of distinct witnesses that have ever entered or left the active set, not with the active set size at any given moment. ([#6624](https://github.com/tronprotocol/java-tron/pull/6624))
+
+**Pre-4.8.2 Baseline**
+
+Snapshot of metrics emitted prior to this changelog. Per-version provenance is not tracked here; consult `git log` on [`common/src/main/java/org/tron/common/prometheus/`](common/src/main/java/org/tron/common/prometheus/) for exact origin of each metric.
+
+### Existing Metrics
+
+#### Core (block / transaction processing)
+
+- `tron:header_height` (Gauge) — latest block height on this node.
+- `tron:header_time` (Gauge) — latest block timestamp on this node.
+- `tron:block_push_latency_seconds` (Histogram) — `Manager#pushBlock` latency.
+- `tron:block_process_latency_seconds` (Histogram, label `sync`) — `TronNetDelegate#processBlock` latency.
+- `tron:block_generate_latency_seconds` (Histogram, label `address`) — block generation latency per producer.
+- `tron:block_fetch_latency_seconds` (Histogram) — block fetch latency.
+- `tron:block_receive_delay_seconds` (Histogram) — `receiveTime - blockTime`.
+- `tron:block_fork` (Counter, label `type`) — fork events by type.
+- `tron:lock_acquire_latency_seconds` (Histogram, label `type`) — DB / chain lock acquisition latency.
+- `tron:miner` (Counter, labels `miner`, `type`) — blocks produced by an SR.
+- `tron:miner_latency_seconds` (Histogram, label `miner`) — block mining latency per producer.
+- `tron:miner_delay_seconds` (Histogram, label `miner`) — `actualTime - planTime` for block production.
+- `tron:txs` (Counter, labels `type`, `detail`) — transaction counts.
+- `tron:process_transaction_latency_seconds` (Histogram, labels `type`, `contract`) — transaction processing latency.
+- `tron:verify_sign_latency_seconds` (Histogram, label `type`) — signature verification latency for transactions and blocks.
+- `tron:tx_cache` (Gauge, label `type`) — transaction cache stats.
+- `tron:manager_queue_size` (Gauge, label `type`) — `Manager` queue sizes (pending / popped / queued / repush).
+
+#### Net (P2P)
+
+- `tron:peers` (Gauge, label `type`) — peer counts.
+- `tron:p2p_error` (Counter, label `type`) — P2P error events.
+- `tron:p2p_disconnect` (Counter, label `type`) — P2P disconnect events.
+- `tron:ping_pong_latency_seconds` (Histogram) — peer ping-pong RTT.
+- `tron:message_process_latency_seconds` (Histogram, label `type`) — peer message processing latency.
+- `tron:tcp_bytes` (Histogram, label `type`) — TCP traffic.
+- `tron:udp_bytes` (Histogram, label `type`) — UDP traffic.
+
+#### API
+
+- `tron:http_service_latency_seconds` (Histogram, label `url`) — HTTP endpoint latency.
+- `tron:http_bytes` (Histogram, labels `url`, `status`) — HTTP traffic.
+- `tron:grpc_service_latency_seconds` (Histogram, label `endpoint`) — gRPC endpoint latency.
+- `tron:jsonrpc_service_latency_seconds` (Histogram, label `method`) — JSON-RPC method latency.
+- `tron:internal_service_latency_seconds` (Histogram, labels `class`, `method`) — internal service-call latency.
+- `tron:internal_service_fail` (Counter, labels `class`, `method`) — internal service-call failure count.
+
+#### DB
+
+- `tron:db_size_bytes` (Gauge, labels `type`, `db`, `level`) — LevelDB storage size.
+- `tron:db_sst_level` (Gauge, labels `type`, `db`, `level`) — LevelDB SST files per compaction level.
+- `tron:guava_cache_hit_rate`, `tron:guava_cache_request`, `tron:guava_cache_eviction_count` — Guava cache stats, registered via `GuavaCacheExports` for caches that opt in.
+
+#### System
+
+Emitted by `OperatingSystemExports` (no labels):
+
+- `system_available_cpus`, `system_cpu_load`, `system_load_average`, `system_total_physical_memory_bytes`, `system_free_physical_memory_bytes`, `system_total_swap_spaces_bytes`, `system_free_swap_spaces_bytes`.
+
+#### JVM / process
+
+Auto-emitted by the Prometheus client library via `DefaultExports.initialize()` (`simpleclient_hotspot`). The full list is owned by the upstream library and not enumerated here; see the [client_java](https://github.com/prometheus/client_java) docs. Common ones: `jvm_memory_bytes_*`, `jvm_gc_collection_seconds_*`, `jvm_threads_*`, `process_cpu_seconds_total`, `process_open_fds`, `process_resident_memory_bytes`.
+
+---
+
+**References**
+
+- [Official metrics documentation](https://tronprotocol.github.io/documentation-en/using_javatron/metrics/) — descriptions, configuration, and example queries.
+- [tron-docker `metric_monitor/README.md`](https://github.com/tronprotocol/tron-docker/blob/main/metric_monitor/README.md) — operator-oriented overview with deployment guidance.
+- [java-tron-server (Grafana dashboard 16567)](https://grafana.com/grafana/dashboards/16567-java-tron-server/) — reference dashboard template.