feat(http): add client instrumentation and metrics

[Pouyanpi]

Description

Adds privacy-safe tracing and request-duration metrics as a decorator over the
shared HTTP client contract introduced in Stack 9.

Design principle: instrumentation observes the client boundary without owning
request or client lifecycle. http_call, IORails, and other callers can keep
using the same HTTPClient contract, while tracing and metrics remain optional
and independently configurable.

Related Issue(s)

• Internal tracking: NGUARD-857, NGUARD-860

AI Assistance

• No AI tools were used.
• AI tools were used; a human reviewed and can explain every change (tool: Codex).

Codex assisted with implementation, validation, and stack restructuring. Check
the disclosure box after human review.

Checklist

• I've read the CONTRIBUTING guidelines.
• This PR links to a triaged issue assigned to me.
• My PR title follows the project commit convention.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• I've noted any verification beyond CI and any checks I couldn't run.
• I did not update generated changelog files manually.
• I addressed all CodeRabbit, Greptile, and other review comments, or replied with why no change is needed.
• @mentions of the person or team responsible for reviewing proposed changes.

Summary by CodeRabbit

• New Features
  • Added optional OpenTelemetry instrumentation for outgoing HTTP requests.
  • HTTP traces now include request, response, retry, error, and duration details while excluding sensitive values.
  • Added HTTP request-duration metrics with status and error information.
  • Instrumentation can be enabled through the public HTTP client interface and safely avoids duplicate wrapping.

[codecov]

Codecov Report

❌ Patch coverage is 99.45652% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
nemoguardrails/tracing/constants.py	96.15%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

The PR adds optional tracing and request-duration metrics around the shared HTTP client while preserving the existing request and ownership contracts.

• Adds an idempotent InstrumentedHTTPClient decorator with independently configurable tracing and metrics.
• Records privacy-conscious HTTP span attributes, response details, retries, errors, and duration metrics.
• Serializes client closure and leaves failed or cancelled cleanup attempts retryable.
• Adds coverage for telemetry behavior, privacy constraints, metric failures, idempotent wrapping, and concurrent cleanup.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the current close implementation serializes concurrent callers, reports cleanup failures to each caller, and keeps failed or cancelled cleanup retryable.

Important Files Changed

Filename	Overview
nemoguardrails/http/instrumented.py	Adds the instrumentation decorator and correctly fixes both previously reported close-state and concurrent-close failures by locking cleanup and marking closure only after success.
nemoguardrails/http/telemetry.py	Adds isolated tracing and duration-metric helpers that preserve request outcomes when telemetry operations fail.
nemoguardrails/tracing/constants.py	Adds HTTP semantic-convention constants and lazily initialized request-duration instrumentation.
tests/http/test_instrumentation.py	Covers tracing, metrics, privacy, error preservation, wrapping idempotency, and serialized retryable cleanup.
nemoguardrails/http/init.py	Exposes the new instrumented client and factory helper through the HTTP package API.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant Instrumented as InstrumentedHTTPClient
  participant Telemetry
  participant Wrapped as Wrapped HTTPClient
  Caller->>Instrumented: request(method, url, ...)
  Instrumented->>Telemetry: start span and duration metric
  Instrumented->>Wrapped: request(method, url, ...)
  Wrapped-->>Instrumented: HTTPResponse or exception
  Instrumented->>Telemetry: record status, retry count, size, or error type
  Instrumented-->>Caller: preserve response or exception
  Caller->>Instrumented: close()
  Instrumented->>Instrumented: acquire close lock
  Instrumented->>Wrapped: close()
  Wrapped-->>Instrumented: success or failure
  alt success
    Instrumented->>Instrumented: mark closed
  else failure or cancellation
    Instrumented->>Instrumented: remain retryable
  end

Loading

_{Reviews (4): Last reviewed commit: "docs(http): cite OpenTelemetry bucket gu..." | Re-trigger Greptile}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds OpenTelemetry tracing and request-duration metrics for HTTP clients, including semantic attributes, error and retry telemetry, idempotent client wrapping, public exports, and comprehensive asynchronous tests.

Changes

HTTP instrumentation

Layer / File(s)	Summary
Telemetry contracts and instruments nemoguardrails/tracing/constants.py, nemoguardrails/http/telemetry.py	Defines HTTP semantic attributes, duration instruments, span creation, request/response attributes, error recording, and duration measurement.
Instrumented client and public API nemoguardrails/http/instrumented.py, nemoguardrails/http/__init__.py	Wraps HTTP clients with optional tracing and metrics, preserves close behavior, avoids duplicate instrumentation, and exposes the new APIs.
Instrumentation behavior validation tests/http/test_instrumentation.py	Tests spans, metrics, retries, errors, propagation, passthrough behavior, idempotence, lifecycle handling, sensitive-data exclusion, and telemetry failure isolation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant instrument_http_client
  participant InstrumentedHTTPClient
  participant HTTPClient
  participant OpenTelemetry
  Caller->>instrument_http_client: request instrumentation
  instrument_http_client->>InstrumentedHTTPClient: create or reuse wrapper
  InstrumentedHTTPClient->>OpenTelemetry: start span and duration measurement
  InstrumentedHTTPClient->>HTTPClient: forward HTTP request
  HTTPClient-->>InstrumentedHTTPClient: return HTTPResponse
  InstrumentedHTTPClient->>OpenTelemetry: record response attributes and metrics
  InstrumentedHTTPClient-->>Caller: return HTTPResponse

Loading

Possibly related PRs

• NVIDIA-NeMo/Guardrails#2209: Establishes retry annotations consumed by the new HTTP telemetry.
• NVIDIA-NeMo/Guardrails#2211: Updates the same HTTP package exports used by this change.

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.26% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Test Results For Major Changes	⚠️ Warning	This is a major feature/refactor, but the PR description lacks explicit test results or testing notes.	Add a brief testing section with what was run and the outcome (or note why it couldn’t be run), plus any relevant perf/regression data.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding HTTP client instrumentation and metrics.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pouyanpi/rail-library-stack-10-http-instrumentation

---

_{Comment @coderabbitai help to get the list of available commands.}

[tgasser-nv]

I reviewed the first commit (sha 71ca58d) only, thanks for the second commit to show how this would integrate into IORails. Here are the comments on the first commit, can you remove the IORails-related commit before you merge?

High level comments:

• Can you address the Greptile 3/5 and feedback?
• Can you add tests to improve coverage?