feat: basic holepunch metrics

[Frando]

Description

This adds two metrics:

• remote_holepunch_attempt counts the number of remotes for which we initiated holepunching.
• remote_holepunch_success counts the number of remotes where we initiated holepunching and had success

Both are either increased by 0 or 1 during the lifetime of a RemoteStateActor, never more. We incrase _attempt once on the first time when holepunching is initiated. We increase _success once if a new IP path is opened whose remote address is part of the last holepunching round.

I'm not entirely sure if this logic is fully sound, but it's the best I could come up with so far.

Fixes #3695

Breaking Changes

Notes & open questions

Change checklist

• Self-review.
• Documentation updates following the style guide, if relevant.
• Tests if relevant.
• All breaking changes documented.
  • List all breaking changes in the above "Breaking Changes" section.
  • Open an issue or PR on any number0 repos that are affected by this breaking change. Give guidance on how the updates should be handled or do the actual updates themselves. The major ones are:
    • quic-rpc
    • iroh-gossip
    • iroh-blobs
    • dumbpipe
    • sendme

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/iroh/pr/3748/docs/iroh/

Last updated: 2025-12-10T12:24:53Z

[flub]

Help, I find this very hard to think about. What do we really want to measure here? I don't have a good answer to this so find commenting on the PR hard. @Arqu maybe has input on what we really need to have?

Things that are easy to measure:

• number of times we start holepuching
• number of times we explicitly open a path without holepunching (e.g. because it was holepunched in another connection).
• number of times a path was opened for any reason (e.g. on the server side or because of holepunching or because of explicit open_path).
• number of times we abandon a path.
• number of times a path is abandoned.

Things that are hard(er) to measure:

• number of times a path is opened from nat traversal (essentially shown in this PR currently though you also would have to be sure it wasn't from an explict open_path call which is not easy right now)
• number of successful holepunches
• number of failed holepunches

My inclination is to concentrate on the easy ones, but do you learn anything useful from those? You can't do any maths to tell you how good your holepunching is I think, so what's the point even? This goes back to, what are we trying to measure?

[flub]

The "remote_" prefix makes me think this was initiated by the remote.

Essentially the metrics you added are:

• remotes connected to ("remotes_connection_established"?)
• remotes holepunched ("remotes_connection_direct"?)

IIUC. This could be useful I guess. Not sure, it's also a bit weird (see separate comment).

[flub]

One issue with this impl is that this metric would only be incremented on the client, and not the server. But that's a bit counter-intuitive from the user point of view.

[flub]

So I think the original intention was that you could have two metrics like:

• no of connections that were on relay and had holepunch attempts
• no of connections that moved from relay to direct after holepunching

And now you can do maths on them because you can compute the number of connections that did not holepunch and have a holepunching rate. But these metrics fall under the "hard" metrics 😞 I'm not sure how to do them.