Skip to content

feat: telemetry foundation (TCP client + framing + Node Info) #941

@HanaYukii

Description

@HanaYukii

Sub-issue of #775 (JIP-3 Telemetry).

Scope

Foundation for JIP-3 telemetry. No emission yet, only the wire/runtime substrate that all subsequent stages build on.

  • TCP client with 4-byte LE length framing
  • Node Info encoding (no timestamp, no discriminator; first byte is protocol version)
  • Event ID counter: per-connection, post-increment from 0
  • Multi-range drop window (dropRange{first_id, count, first_ts, last_ts}) with sequencer mutex around ID + enqueue/drop record
  • Reconnect with exponential backoff (1s → 30s, infinite retry)
  • --telemetry HOST:PORT CLI flag
  • Client API: Enabled() / Emit / EmitLazy(disc, builder) / EmitFollowup / EmitFollowupLazy / Close
  • InvalidID = ^uint64(0) sentinel for disabled / reconnecting / degraded states
  • Writer goroutine with defer recover() and graceful Close (drain envelopes, flush drop_ranges, FIN, 5s timeout)
  • Common-type codec: Option<T>, String<N> (UTF-8 + len cap), len++[T], bool, fixed-int LE, Reason
  • Contract test framework skeleton at internal/telemetry/contract_test.go
  • Golden vector fixtures at testdata/wire_fixtures/

Dependencies

  • Parent: JIP-3: Telemetry #775
  • Q-blocker: none (Q1-independent; foundation can land before main loop work resolves)
  • Design: docs/jip3-telemetry-design.md (Architecture, Wire Protocol, Event ID + Lazy API + Backpressure)

Acceptance

  • All codec roundtrip + golden vector tests pass
  • mockTcpServer integration: lifecycle, reconnect, concurrent emit, interleaved drop, bridge invariants, panic recover, Close
  • E2E: docker-compose JamTART, Node Info on /api/ws, stress overflow validates Dropped ID alignment
  • Reviewer signoff

Metadata

Metadata

Assignees

Labels

featnew feature for the user, not a new feature for build script

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions