docs/observability.md

@@ -208,22 +208,26 @@ a build error naming the reason rather than telemetry silently going nowhere.
 
 ## Network access
 
-Agent containers can only reach the host on ports 80 and 443 by default. To let
+Agent containers can only reach the host on ports 80 and 443 by default. If
-them reach some other host-local service you run yourself — a database, a
+your OTLP collector runs on a non-standard port on the same host (e.g. a local
-scratch HTTP endpoint — open its port on the bridge:
+dev collector on `:4318`), open that port via:
 
 ```nix
-services.hyperhive.network.exposeHostPorts = [ 5432 ];
+services.hyperhive.network.exposeHostPorts = [ 4318 ];
 ```
 
-and point whatever consumes it at `10.42.0.1:5432` rather than loopback: inside
+Then point the endpoint at the bridge IP rather than loopback:
-a container, loopback is the *container*. The bridge IP is the host's address on
-the `hive-br0` bridge. The service must also bind an address the bridge can
-reach — a `127.0.0.1`-only listener stays unreachable no matter what the
-firewall allows. See `docs/network.md::Reaching host services` for details.
 
-⚠️ **None of this is needed for hyperhive's own telemetry** — `otel.enable`
+```nix
-contributes the collector's port and derives the agent-facing endpoint itself.
+services.hyperhive.otel.endpoint = "http://10.42.0.1:4318";
+```
+
+The bridge IP is the host's address on the `hvbr0` bridge, typically
+`10.42.0.1`. See `docs/network.md::Reaching host services` for details.
+
+⚠️ **You do not need either line for hyperhive's own telemetry** — `otel.enable`
+contributes the collector's port and derives the endpoint itself. The above is
+for pointing something *else* at a host-local service.
 
 ## Built-in resource labels
 

nix/host-modules/hive-network.nix

@@ -93,16 +93,16 @@ in
     exposeHostPorts = lib.mkOption {
       type = lib.types.listOf lib.types.port;
       default = [ ];
-      example = [ 5432 ];
+      example = [ 4318 ];
       description = ''
         TCP ports on the host that agent containers may reach at the bridge
         IP (`bridgeIp`). Each listed port `P` is opened on the bridge-interface
         firewall, so an agent can connect to `''${bridgeIp}:P` (default
         `10.42.0.1:P`).
 
-        Use this to let agents reach a host-local service you run yourself —
+        Use this to let agents reach a host-local service — e.g. an
-        a database, a scratch HTTP endpoint, anything listening on
+        OpenTelemetry collector for `services.hyperhive.otel.endpoint` (set
-        `''${bridgeIp}:P`.
+        `endpoint = "http://''${bridgeIp}:P"`).
 
         **The host service must bind an address reachable from the bridge** —
         `0.0.0.0` or the bridge IP (`bridgeIp`) — not loopback-only. The