docs: add HashJoinExec metrics to user guide

[fyrsta7]

Which issue does this PR close?

• Closes Include HashJoinExec in the metrics user-guide #19044.

Rationale for this change

HashJoinExec exposes several operator-specific metrics, but the metrics user guide did not document them yet. This PR follows the metrics documentation tracking issue by adding the HashJoinExec section.

What changes are included in this PR?

• Adds HashJoinExec operator-specific metrics to docs/source/user-guide/metrics.md.
• Adds a note near BuildProbeJoinMetrics to keep metric descriptions in sync with the user guide.
• Clarifies that join_time covers join processing after build-side collection.
• Clarifies that probe_hit_rate and avg_fanout measure join-key matches before applying any join filter.

Are these changes tested?

This is a documentation/comment-only change with no runtime behavior change.

Checked locally:

• git diff --check
• cargo fmt --check
• npx prettier@2.7.1 --check docs/source/user-guide/metrics.md
• ./dev/rust_lint.sh
• cd docs && uv run --package datafusion-docs ./build.sh
• DataFusion CLI EXPLAIN ANALYZE queries with and without a join filter

Are there any user-facing changes?

Yes. The metrics user guide now documents the existing HashJoinExec metrics. There are no runtime behavior or public API changes.

AI-assisted contribution note

This change is limited to documentation and comments. I verified the metric names and semantics against BuildProbeJoinMetrics, the HashJoinExec execution path, and local EXPLAIN ANALYZE output. I do not have unknowns or assumptions to call out.

[fyrsta7]

Hi maintainers, just a gentle follow-up on this documentation PR. I have rechecked the metric semantics against the implementation and local EXPLAIN ANALYZE output, and the formatting, lint, and documentation checks pass locally. The full GitHub Actions workflows are currently awaiting approval for a first-time contributor. When you have a chance, could someone please approve the workflows and take a look? Thank you!

[kosiew]

@fyrsta7,

Thanks for adding the HashJoinExec metrics documentation and keeping the BuildProbeJoinMetrics comments in sync. This looks good overall. I just have one small wording suggestion to make the memory metric a bit more precise.

[kosiew]

Could we say "Peak tracked memory used by the build side" instead of "Peak memory used" here? build_mem_used is based on accounting from RecordBatch sizes, ArrayMap and hash-table estimates, and the visited bitmap. That makes it useful for the operator's reservation and accounting, but it is not an allocator-measured process-memory peak.