Perch Bridge Federation

Status: pre-production. Perch is pre-production (nestr-tools CLAUDE.md:40 @b8f0585), and the bridge is not in the Helm chart: it exists only as a raw manifest, perch/k8s/bridge/deployment.yaml, with image perch-folio-bridge:latest (nestr-tools/perch @f9ec790, read 2026-10-25). No evidence was found that it runs anywhere.

ELI5

The Bridge is a delivery courier: every 30 seconds it visits the Engine’s metrics shop, picks up everything on the shelves, drops the haul at the Folio warehouse, and writes a postcard saying “made it, here’s how heavy the load was”.

Technical Deep Dive

Source: nestr-tools/perch bridge/main.go:21-38,61-67,102-119,172-215 (last changed 2026-06-03), k8s/bridge/deployment.yaml:5-27, helm/templates/ (no bridge template), helm/values.yaml:33-36 @f9ec790; nestr-tools/engine internal/server/rest.go:135 @e9180e4; read 2026-10-25. Defaults re-verified; two corrections: the default Folio URL points at a Materi namespace, and the engine serves /metrics on its API port (8080 on Railway), not on 9090.

perch/bridge/main.go is a small Go service whose job is one-way metric federation from the Engine into a remote /api/v1/write-compatible collector (“Folio”).

Configuration

Push Loop

sequenceDiagram
    participant T as ticker(30s)
    participant B as Bridge
    participant E as Engine /metrics
    participant F as Folio /api/v1/write
    loop every PushInterval
        T->>B: tick
        B->>E: GET /metrics
        E-->>B: text-format families
        B->>F: POST the raw text body, labelled application/x-protobuf
        alt 2xx
            F-->>B: 200
            B->>B: pushes_total++, last_push_timestamp=now, metrics_federated.Set(n)
        else error
            F-->>B: 5xx
            B->>B: push_errors_total++
        end
    end

Bridge’s Own Metrics

perch_bridge_* lets the central system observe the courier itself:

• perch_bridge_pushes_total — counter
• perch_bridge_push_errors_total — counter
• perch_bridge_push_duration_seconds — histogram, buckets [0.01, 0.05, 0.1, 0.5, 1, 2.5, 5, 10]
• perch_bridge_last_push_timestamp_seconds — gauge; alerting target if it stops incrementing
• perch_bridge_metrics_federated — gauge of how many series were in the last push

What does NOT pass through

The Bridge federates Prometheus metrics only. WebSocket events (nestr-007), structured logs, and traces have separate paths — Promtail/Loki for logs, Jaeger for traces (see nestr-010 for the trace-correlator).

Key Terms

• Federation → polling another Prometheus-compatible source and re-emitting the series, optionally with relabeling.
• Remote write → Prometheus’s snappy-compressed protobuf push protocol. The bridge targets a remote-write path but does not speak the protocol: it forwards the text exposition unparsed (bridge/main.go:172-215), so a real remote-write receiver would reject it.
• Folio → a Materi-era collector; the default URL is in the materi-production namespace.

Q&A

Q: What is the default push interval? A: 30 seconds (-push-interval, bridge/main.go:33).

Q: Which protocol does the Bridge use to push to Folio? A: Nominally Prometheus remote write: it POSTs to <folio>/api/v1/write with Content-Type: application/x-protobuf. In fact it sends the engine’s text exposition bytes unchanged, with no protobuf WriteRequest and no snappy framing.

Q: What metric tells you the Bridge itself is healthy? A: perch_bridge_last_push_timestamp_seconds advancing (and perch_bridge_push_errors_total not), served on the bridge’s own /metrics.

Q: What single alert detects a stuck Bridge? A: time() - perch_bridge_last_push_timestamp_seconds > 90 — three missed 30 s ticks.

Q: Does the Bridge re-send series on failure? A: No. A failed push only increments push_errors_total; the next tick re-scrapes fresh series. There is no buffer on disk.

Q: Why pull from /metrics instead of being scraped directly? A: Folio is outside the Engine’s network reach in the typical deployment. The Bridge sits inside the Engine’s cluster and is the only component allowed egress to Folio.

Examples

If Perch is ever stood up with this bridge, perch_bridge_push_errors_total climbing on every tick is the expected first symptom against a genuine remote-write receiver, because the body is text, not snappy protobuf. Fix the encoder before tuning intervals.