Skip to content

feat(client): add transport health telemetry - #590

Open
aej wants to merge 10 commits into
elixir-grpc:masterfrom
fanatics-live:feat/client-transport-telemetry
Open

feat(client): add transport health telemetry#590
aej wants to merge 10 commits into
elixir-grpc:masterfrom
fanatics-live:feat/client-transport-telemetry

Conversation

@aej

@aej aej commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Problem

Today an observability library can see RPC and logical connection events, but it cannot reliably answer basic transport questions: is the HTTP/2 connection up, did it reconnect, how many streams are active, or has the peer's stream limit been reached?

The only way to get those facts is to inspect Gun/Mint processes or other private state. I don't think observability code should depend on those implementation details.

What this adds

This adds a transport-neutral [:grpc, :client, :transport, ...] telemetry API for both Gun and Mint:

Event Meaning
:started A physical transport has been created but is not usable yet. Generation and active streams both start at zero.
:connected The transport is usable. Includes the generation and whether this was a reconnect.
:connect_error Connection establishment failed at a reliably known resolve, tcp, tls, or http2 stage.
:down An established transport became unavailable. This event owns the count of streams terminated by the loss.
:stopped The transport was permanently removed or explicitly shut down. This is separate from a temporary :down.
:settings The peer's effective SETTINGS_MAX_CONCURRENT_STREAMS changed, or the value is not safely known.
:streams An authoritative active-stream snapshot after the transport's stream table changes.

It also adds optional failure_stage and failure_reason fields to existing client RPC telemetry where the cause is known, for example a deadline, unavailable connection, or stream error.

The intention is that a consumer can calculate logical readiness and capacity across multiple physical transports without using connection references as metric labels.

Deliberate limits

Mint also reports 100 both before an explicit peer limit is known and when the peer really advertises 100. This PR reports that case as :unknown rather than inventing finite capacity. A small upstream Mint hook exposing whether the setting was present would close that gap.

Connect failures are only given a stage (resolve, tcp, tls, or http2) when the adapter exposes that reliably. Error text is not parsed.

Testing

The new events use temporary telemetry handlers in tests

@aej
aej marked this pull request as ready for review September 9, 2026 09:58
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