Skip to content

Add vendor-neutral telemetry (metrics + tracing) for v6.4.0 - #342

Open
jchristn wants to merge 3 commits into
mainfrom
feature/telemetry-6.4.0
Open

Add vendor-neutral telemetry (metrics + tracing) for v6.4.0#342
jchristn wants to merge 3 commits into
mainfrom
feature/telemetry-6.4.0

Conversation

@jchristn

@jchristn jchristn commented Aug 2, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds standardized, vendor-neutral telemetry to WatsonTcp so it can be observed by Radiant, the OpenTelemetry SDK, Prometheus, or any compatible host with no dependency on any telemetry
backend
. WatsonTcp emits into a System.Diagnostics.Metrics.Meter and a System.Diagnostics.ActivitySource, both named WatsonTcp; hosts subscribe by name. This is a minor release (6.3.2
6.4.0), purely additive, no breaking changes.

What's included

  • WatsonTcpMetrics (public) — the consumer contract: stable source names, 24 metric names, 6 span names, UCUM units, and tag keys as constants.
  • WatsonTcpInstrumentation (internal, IDisposable) — per-instance Meter + ActivitySource, all counters/histograms/observable-gauges and span factories; disposed with its owner. Every recording
    call is null-guarded and fire-and-forget, so telemetry can never throw into the send/receive/connection path.
  • Wired through the client/server lifecycle: send/receive + bytes, connection admission outcomes, disconnections by DisconnectReason, handshake, authentication, connection authorization, synchronous
    request/response/timeout/expiry, exceptions (funnelled through one helper), transient accept errors, stream drain, and uptime.
  • Metric tags are low-cardinality only (role, protocol, outcome, reason, …); high-cardinality identifiers (client GUID, remote endpoint, conversation GUID) go on spans only.
  • Settings.EnableMetrics / Settings.EnableTracing (default true) on both settings classes; when metrics are off, no Meter is created at all.
  • References System.Diagnostics.DiagnosticSource 8.0.1 on the down-level target frameworks only (in-box on net8.0/net10.0).

Testing

  • 17 new positive and negative telemetry tests using the BCL MeterListener/ActivityListener (zero third-party test deps), plus a new telemetry suite and a --suite filter for the console runner.
  • Covers counters/bytes, connection gauges + outcomes, disconnect-by-reason, sync round-trip + timeout, handshake success + failure, auth success + failure, authorization allow + reject, blocked-IP
    rejection, transient accept error, metrics-disabled → no measurements, tracing-disabled → no spans, span tags, and a cardinality guard.
  • 126/126 tests pass on net8.0 and net10.0 (109 existing + 17 new), no regressions.
  • Release build clean (0 warnings) across all six target frameworks.

Docs

README (New in v6.4.0), CHANGELOG, ARCHITECTURE (§11 Telemetry), CLAUDE.md, and a new consumer-facing TELEMETRY.md (full metric catalog, tag dictionaries, Prometheus series names, PromQL examples). The
design/implementation plan is preserved at archive/TELEMETRY_PLAN.md.

jchristn and others added 3 commits July 29, 2026 08:12
Emit metrics and distributed-tracing spans through System.Diagnostics.Metrics
(Meter "WatsonTcp") and System.Diagnostics.ActivitySource (ActivitySource
"WatsonTcp"), consumable by Radiant, the OpenTelemetry SDK, Prometheus, and
others with no dependency on any telemetry backend.

- Add public WatsonTcpMetrics contract (source/metric/span/tag-key constants)
- Add internal WatsonTcpInstrumentation (per-instance Meter/ActivitySource,
  24 metrics, 6 spans, observable gauges), disposed with its owner
- Wire recording into client/server lifecycle: send/receive, connect/disconnect
  by reason, handshake, auth, authorization, sync request/response/timeout,
  exceptions (funnelled), transient accept errors, stream drain, uptime
- Keep metric tags low-cardinality; put GUIDs/endpoints on spans only
- Add Settings.EnableMetrics/EnableTracing (default true) to both settings
- Reference System.Diagnostics.DiagnosticSource on down-level TFMs only
- Add 17 positive/negative telemetry tests (BCL MeterListener/ActivityListener)
  and a telemetry suite; 126/126 pass on net8.0 and net10.0
- Bump version to 6.4.0; update README, CHANGELOG, ARCHITECTURE, CLAUDE
- Replace TELEMETRY.md with a consumer integration guide; archive the plan

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SrLigwKj3JqRXPzZZq8fU2
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