statsUserOnline enabled but no online statistics appear in API

[ITDiver77]

Xray version: 25.12.8 (from xray --version)
Environment: Docker container (teddysun/xray:latest) with host networking
API port: 10085 (dokodemo-door inbound)
Here is config:
{
"log": {
"loglevel": "info",
"access": "/var/log/xray/access.log",
"error": "/var/log/xray/error.log"
},
"api": {
"tag": "api",
"services": [
"HandlerService",
"StatsService"
]
},
"stats": {},
"policy": {
"levels": {
"0": {
"statsUserUplink": true,
"statsUserDownlink": true,
"statsUserOnline": true
}
},
"system": {
"statsInboundUplink": true,
"statsInboundDownlink": true
}
},
"inbounds": [
{
"port": 443,
"protocol": "vless",
"settings": {
"clients": [
{
"id": "permanent_test_user",
"email": "permanent_test_user@example.com",
"flow": ""
},
{
"id": "a9e7f88c-f6f1-44bd-905a-64879ab84cbc",
"email": "user",
"flow": ""
},
{
"id": "86a82955-8657-43c6-ae74-af724bb06299",
"email": "user1@example.com",
"flow": ""
}
],
"decryption": "none"
},
"streamSettings": {
"network": "tcp",
"security": "reality",
"realitySettings": {
"show": false,
"dest": "www.google.com:443",
"serverNames": ["www.google.com"],
"privateKey": "private-key",
"shortIds": [
"525ec83f86",
"64061320d2",
"04f8996da7",
"0a041b9462"
]
}
}
},
{
"listen": "127.0.0.1",
"port": 10085,
"protocol": "dokodemo-door",
"settings": { "address": "127.0.0.1" },
"tag": "api"
}
],
"outbounds": [
{ "protocol": "freedom", "tag": "direct" },
{ "protocol": "blackhole", "tag": "blocked" }
],
"routing": {
"rules": [
{
"inboundTag": ["api"],
"outboundTag": "api",
"type": "field"
}
]
}
}

What I did:

Enabled statsUserOnline in policy level 0 (the default level for all clients, as none have explicit level set).
Restarted Xray.
Connected two clients(same phone, btw) (using VLESS+REALITY) and generated some traffic.
Queried statistics using:
docker exec -it xray bash -c "xray api statsquery --server=127.0.0.1:10085"

Got result:
{
"stat": [
{
"name": "user>>>user1@example.com>>>traffic>>>downlink",
"value": 14722
},
{
"name": "inbound>>>api>>>traffic>>>uplink",
"value": 170
},
{
"name": "inbound>>>api>>>traffic>>>downlink",
"value": 24
},
{
"name": "user>>>permanent_test_user@example.com>>>traffic>>>uplink",
"value": 26272
},
{
"name": "user>>>permanent_test_user@example.com>>>traffic>>>downlink",
"value": 63520
},
{
"name": "user>>>user1@example.com>>>traffic>>>uplink",
"value": 6863
}
]
}

Why are online user statistics not appearing despite statsUserOnline: true in policy level 0? Is there any additional configuration required? Or is this a known limitation/ bug?

[taubedonner]

TL;DR: this is (very likely) not a bug in your config – Xray deliberately
excludes loopback sources from the online map. If your clients reach Xray
via 127.0.0.1 (nginx/haproxy SNI-mux or CDN-fallback on the same host, a
Docker port published through a local proxy, local testing), online stats
will read 0 forever while traffic counters for the same user keep growing.

OnlineMap.AddIP drops loopback unconditionally, and has since the feature
first shipped in #3637:

https://github.com/XTLS/Xray-core/blob/v26.6.27/app/stats/online_map.go#L36-L39

func (om *OnlineMap) AddIP(ip string) {
	if ip == localhostIPv4 || ip == localhostIPv6 { // "127.0.0.1", "[::1]"
		return
	}

(same check in the original implementation:
https://github.com/XTLS/Xray-core/blob/v24.11.5/app/stats/online_map.go#L37-L41)

Traffic counters are not filtered this way – hence the confusing
asymmetry: user>>>email>>>traffic>>>uplink/downlink grow, but
GetStatsOnline / GetStatsOnlineIpList / GetAllOnlineUsers stay empty
with statsUserOnline: true correctly configured.

Verified empirically on v26.6.27 (VLESS+REALITY, statsUserOnline: true at
level 0, live transfer running through the tunnel during both checks):

client connects to	xray api statsonline	traffic counters
127.0.0.1:8443 (same host)	0 (empty map)	growing
192.168.1.120:8443 (LAN IP of the same host)	value: 1	growing

So protocol-side tracking works fine (both dispatcher paths call
trackOnlineIP – see getLink and WrapLink in
app/dispatcher/default.go,
L216-L218,
improved by the refcount rewrite in
eec2802) – the source IP
is the only variable.

Workarounds if Xray sits behind a same-host proxy:

1. Enable PROXY protocol on the fronting proxy and acceptProxyProtocol on
   the Xray inbound – Xray should then see the real client IP (untested by
   me, please confirm).
2. Or derive "online" panel-side from traffic-counter deltas between polls
   (what e.g. Marzban effectively does) – works regardless of topology.

Probably explains the same symptom in #4496 and #3983. Note #5868
(Hysteria inbound not tracked) is a different, real issue –
CounterConnection not proxying User().

@hossinasaadi @kastov It would be great to at least document the loopback exclusion next to
statsUserOnline, or emit a debug log when an IP is skipped – the silent
empty map is what makes this look like a broken feature.