feat(recipe): pattern-2 IB link flap OTTL stanza (#393)

[trilamsr]

Summary

Closes #393. Ships the metric-side OTTL projection from
node_exporter --collector.infiniband's node_infiniband_port_state_id
Gauge onto the customer-stable hw.network.ib.* namespace
(hw.network.ib.port.state int + hw.network.ib.device +
hw.network.ib.port.num) so pattern #2's IBLinkFlapDetector
consumes the same vendor-neutral wire shape regardless of whether the
underlying source is node_exporter, a Mellanox exporter, or the
mlx5_core journald stream.

Detector library + processor wiring already shipped in #391 (closed
#300). Only the metric-side input recipe was missing — pattern #2 was
configured-but-quiet on real deployments. This PR closes that gap.

Wire contract (node_exporter raw → hw.network.ib.*)

node_infiniband_port_state_id{device="mlx5_0", port="1"} = 4
                                                          (IBA phys_state ID)
            ↓ transform/ib_to_hw_semconv
Gauge metric "hw.network.ib.port.state" with datapoint attrs:
  hw.network.ib.device  = "mlx5_0"        (str, from `device` label)
  hw.network.ib.port.num = 1              (int, from Int(`port` label))
  value                  = 4              (int, the phys_state ID)

The future RFC-0014 PR-B metrics→logs bridge emitter (shared with
patterns #3/#4/#5/#10) will lift these three attributes onto a log
record at emit time. The bridge log-record schema for pattern #2 is
pinned in docs/integrations/prometheus-scrape.md §Pattern #2 — hw.network.ib.port.state (issue #393) so PR-B has no per-pattern
reconstruction work to do.

The companion series node_infiniband_state{state="<name>"} (string
label) is intentionally NOT mapped — the detector
(module/processor/patterndetectorprocessor/ib_link_flap.go) compares
state.Int() against patterns.IBPortState* integer constants, so
the string variant would round-trip wrong.

No detector code change required

The detector reads three attribute names off a log record:
hw.network.ib.port.state, hw.network.ib.device,
hw.network.ib.port.num. The recipe stanza stamps the exact same
three names on the metric datapoint. The wire format port.Int()
expects (the projector at
module/processor/patterndetectorprocessor/ib_link_flap.go line 39
calls int(port.Int())) is satisfied because the OTTL Int() cast
on the Prometheus port string label produces a pdata int Value.
Confirmed by the new TestRecipe_IBLinkFlap_RoundTripFiresVerdict
test.

Root cause + scope

• Root cause of ottl(pattern-2): node_infiniband -> hw.network.ib.* recipe #393: missing metric-side OTTL stanza. Fixed.
• Out of scope (separate blocker, tracked under Recipe extension: emit hw.gpu.nvlink.* + wire metrics path for pattern-1 detector #260 PR-B): the
  metrics→logs bridge emitter. Upstream-blocked at OTel-contrib v0.130
  — transformprocessor's metric_statements cannot reference
  log.* paths and no contrib connector emits log records from a
  metrics pipeline (per
  RFC-0014).
  The recipe doc explicitly documents this gating relationship; PR-B
  is shared with patterns Add NORTHSTARS, RFC-0002, and Q1 MILESTONES #3/Wave 1: governance bootstrap (CODEOWNERS, DCO, signing) #4/Apply Wave-1 follow-ups: tests, automation, doc-truth #5/Tighten developer and PR feedback loops #10 and lands the bridge once.

Files changed

• docs/integrations/examples/prometheus-scrape.yaml — new
  transform/ib_to_hw_semconv processor; wired into the
  metrics/scrape pipeline. Validates with ./_build/tracecore validate (exit 0).
• docs/integrations/prometheus-scrape.md — new "Pattern Bump the gh-actions group across 1 directory with 4 updates #2 —
  InfiniBand link flap" projection section, intro updated from "Two"
  to "Three OTTL transforms", and bridge log-record contract
  subsection added under the "Metrics-to-logs bridge contract"
  section.
• docs/patterns/pattern-2-ib-link-flap.md — deleted "Integration
  gap" section, replaced with "Integration recipe" pointing at the
  shipped stanza; updated "Why node_exporter sees it" prose to drop
  the "pending" hedge.
• module/processor/patterndetectorprocessor/ib_link_flap_recipe_test.go
  — new file. TestRecipe_IBLinkFlap_StanzaPinsWireContract parses
  the example YAML and asserts every load-bearing token is present
  (source metric name, three hw.network.ib.* attrs, the Int()
  cast on the port label, the transform name, and the pipeline
  wiring). TestRecipe_IBLinkFlap_RoundTripFiresVerdict simulates
  the end-to-end path: builds plog.Logs with the exact attribute
  shape the recipe stamps and asserts the processor emits a flap
  verdict.

Test plan

• ./_build/tracecore validate --config=docs/integrations/examples/prometheus-scrape.yaml → exit 0
• bash scripts/validator-recipe.sh → 9 validated, 3 skipped (non-linux host)
• bash scripts/doc-check.sh → clean (no orphan test refs)
• go test ./module/processor/patterndetectorprocessor/... -count=1 → PASS (incl. the two new tests + all 5 existing IB tests)
• go build ./... and go vet ./... → clean
• Pre-commit hooks: golangci-lint 0 issues, go mod verify, attribute-namespace-check 100/100
• Mutation-verified: dropping hw.network.ib.port.state from the recipe yaml fails TestRecipe_IBLinkFlap_StanzaPinsWireContract with the expected remediation message naming the missing identifier
• CI on the PR (waiting on push)

feat(recipe): InfiniBand link-flap OTTL stanza projecting node_exporter's `node_infiniband_port_state_id` onto the tracecore-canonical `hw.network.ib.*` namespace (`hw.network.ib.port.state` int + `hw.network.ib.device` + `hw.network.ib.port.num`). Pattern #2's `IBLinkFlapDetector` now has its metric-side input wired; metrics→logs bridge emitter remains gated on RFC-0014 PR-B (#260).

[trilamsr]

APPROVED. Independent review complete.

Top findings

1. Recipe placement: CONSISTENT. Uses docs/integrations/examples/prometheus-scrape.yaml matching feat(recipes): OTTL stanzas + bridge for pattern #7 (#364 #365) #406 (pattern-7 OTTL recipe). No drift from audit audit(wave-2026-06-01): post-wave cross-cut review #421.

2. Attribute cross-check: VERIFIED. OTTL stanza stamps hw.network.ib.port.state (int) + hw.network.ib.device (str) + hw.network.ib.port.num (int cast via Int()) — exact match to pattern-2 walkthrough (docs(pattern-2): author IB link flap operator walkthrough #391) and detector reads (module/processor/patterndetectorprocessor/ib_link_flap.go::projectIBPortStateRecord).

3. Test coverage: SOUND. Two new tests pin the contract end-to-end:

   • TestRecipe_IBLinkFlap_StanzaPinsWireContract — semantic gate on recipe YAML; mutation-verified (PR body confirms dropping any attribute fails the test).
   • TestRecipe_IBLinkFlap_RoundTripFiresVerdict — round-trip from metric-shaped attributes → detector verdict. Uses existing extractIBLinkFlapVerdicts helper (not broken out-of-thin-air).

4. RFC-0014 PR-B blocker: HONESTLY NAMED. PR body, docs, and code comments all pin the metrics→logs emitter as out-of-scope (separate PR-B, OTel-contrib gated). Bridge log-record schema pinned in prometheus-scrape.md §Pattern #2 bridge contract so PR-B has no per-pattern reconstruction work.

5. Verdict fixture alignment (test(sdk): single-source verdict fixtures across Go + Python (#368) #398): CORRECT. Pattern ID = "2" (not "21"). Detector emits PatternIDIBLinkFlap as built from patterns.IBPortStateRecord projector output. All prior wire-format tests in ib_link_flap_test.go continue to pass unchanged.

SHIP