Skip to content

feat(ws): client websocket request, close and per-client notification metrics - #1

Draft
snowkide wants to merge 1 commit into
mainfrom
feat/ws-client-metrics
Draft

snowkide wants to merge 1 commit into
mainfrom
feat/ws-client-metrics

Conversation

@snowkide

@snowkide snowkide commented Oct 15, 2026 •

Copy link
Copy Markdown

Client WebSocket traffic is only partly visible in metrics. Requests that reach the network are counted in erpc_network_request_received_total exactly like HTTP ones. Requests rejected before the network (invalid JSON, disallowed method, failed auth, consumer rate limit, network unavailable) are not counted at all, and nothing records why connections close. This builds on the subscription metrics from erpc#1255 instead of adding parallel ones:

  • transport (http|ws) as a trailing label on erpc_network_request_received_total, recorded on NormalizedRequest (defaults to http).
  • erpc_websocket_requests_total{project,network,category,user,agent_name,outcome}: every request on a client connection, batch items individually, including pre-network rejections. Outcomes: ok, error, rate_limited, invalid, invalid_batch, method_not_allowed, unauthorized, network_unavailable. category stays n/a until auth and network until the network resolves, so rejected requests cannot create series from a method name or chain id the client chose.
  • erpc_websocket_connections_closed_total{project,network,close_code,initiator}, with close_code bounded to RFC 6455 1000-1015, else other.
  • network on erpc_websocket_connections_active, so open connections can be broken down per network like the subscription metrics.
  • user/agent_name on erpc_websocket_notifications_sent_total and erpc_websocket_subscription_notifications_dropped_total, captured at eth_subscribe. Both become labeled counters, so metrics.customizations can drop the per-client labels.

Notes for review:

Verification

Based on fork main @ f97c9f6 (erpc/erpc 0.5.0 @ 204f98c).

  • go build ./..., go vet on touched packages and gofmt -l on touched files are clean.
  • go test ./common/ -run TestNormalizedRequest_Transport, go test ./telemetry/ ./indexer/adapters/wsclient/: ok.
  • go test ./erpc/ -run 'TestWebSocket|TestWs|TestSubscription|TestHttpServer_WebSocket': ok.
  • With -race, only TestWebSocket_ProjectsSharingANetworkUseTheirOwnUpstreams fails, and TestWebSocket_UnsubscribeIsScopedToConnection is flaky (1 in 5); both fail the same way on plain main.
  • New/updated tests: TestWebSocket_RequestAccounting, TestWebSocket_RequestAccountingAuthRateLimited, TestWebSocket_CloseCodeLabelIsBounded, TestNormalizedRequest_TransportDefaultsToHttp, TestWebSocket_LogsSubscribeOnAllUpstreamsAndDedupe.

AI assistance

  • Model: anthropic/claude-opus-5.5
  • Harness / skills: Claude Code
  • Human-reviewed: no, pending

🤖 Generated with Claude Code

@snowkide
snowkide force-pushed the feat/ws-client-metrics branch from 4be4dbf to 9371482 Compare November 3, 2026 10:57
@snowkide snowkide changed the title feat(metrics): client WebSocket request, connection and per-client notification metrics feat(ws): client websocket request, close and per-client notification metrics Nov 3, 2026
@snowkide
snowkide changed the base branch from main to upstream-main November 3, 2026 11:06
@snowkide
snowkide force-pushed the feat/ws-client-metrics branch from 9371482 to 1071e70 Compare November 3, 2026 11:23
@snowkide
snowkide changed the base branch from upstream-main to main November 3, 2026 11:23
@snowkide
snowkide force-pushed the feat/ws-client-metrics branch from 1071e70 to 51e00bb Compare November 3, 2026 13:31
@snowkide
snowkide force-pushed the feat/ws-client-metrics branch from 51e00bb to 1504e16 Compare November 4, 2026 14:03
… metrics

Client WebSocket traffic is only partly visible in metrics: requests that
reach the network are counted in network_request_received_total exactly
like HTTP ones, requests rejected before the network (invalid JSON,
disallowed method, failed auth, consumer rate limit, network unavailable)
are not counted at all, and nothing records why connections close. The
subscription metrics cover connections, subscriptions and notifications
per network, but not per client.

- network_request_received_total gains a trailing transport label
  ("http" or "ws"), recorded on NormalizedRequest and defaulting to "http".
- erpc_websocket_requests_total{project,network,category,user,agent_name,
  outcome} counts every JSON-RPC request on a client connection (batch
  items individually), including pre-network rejections. outcome is one of
  ok, error, rate_limited, invalid, invalid_batch, method_not_allowed,
  unauthorized, network_unavailable. category stays "n/a" until the
  request is authenticated and network until the network resolves, so a
  rejected request cannot mint series from a client-chosen method name or
  chain id.
- erpc_websocket_connections_closed_total{project,close_code,initiator}.
  initiator is "client" when the peer ended the connection (its close
  code, or 1006 when it vanished or stopped answering pings) and "server"
  otherwise. close_code is bounded to the RFC 6455 range 1000-1015, else
  "other".
- websocket_notifications_sent_total and
  websocket_subscription_notifications_dropped_total gain trailing user
  and agent_name labels, captured at eth_subscribe time and carried on the
  subscription (wsclient.SubscriptionLabels). Both become labeled counters,
  so metrics.customizations can drop the per-client labels.

Docs: Metrics section in operation/websocket, rows in reference/metrics,
and the transport label wherever network_request_received_total labels
are listed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@snowkide
snowkide force-pushed the feat/ws-client-metrics branch from 1504e16 to 457777b Compare November 5, 2026 13:52

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant