Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

collector: render peer attribution on macOS and Windows only for a capable collector

Claudef04c0788088e
diff --git a/CLAUDE.md b/CLAUDE.md
index 88d7ca1f..fdad73fb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,7 +59,7 @@ Supported runtime surfaces today:
- DeepSeek Harness (`dsh`) is installed through two user-level files: `$DSH_HOME/beacon-endpoint-hooks.json` and a row in `$DSH_HOME/cordis.patch.yml`; there is no project scope. The `@deepseek-ai/dsh-hooks-claude-code` bridge that row mounts is not shipped with the CLI (dev dependency only) and must be installed per profile with `@deepseek-ai/dsh-hook-protocol` at exactly the dsh version; a mount dsh cannot load is skipped at boot with only a warning. So `InstallDsh` first runs `hooks.InspectDshBridge` (`internal/endpoint/hooks/dsh_bridge.go`, read-only: the installation found from the `dsh` launcher on PATH, each `$DSH_HOME/profiles/*` resolved Node-style, and rows in any patch layer that mount a bridge by absolute path at Beacon's hooks file) and returns `*DshBridgeUnavailableError` without writing anything when nothing loads a matching bridge; explicit `--harness dsh` fails, `--all` and endpoint install skip with a warning. A healthy by-path mount (how Nix installs it; it must also resolve its declared dsh peers from its own location, because dsh's host-package interception applies only to profile plugins, else `peers_missing`) counts as installed and Beacon writes no row of its own (removing one it wrote earlier) so hooks never run twice. Beacon never installs the packages. `DshStatus.Active`/`Bridge`, discovery (misconfigured when inactive), doctor `dsh_hook_bridge`, and inventory (each profile's patch layer) surface it; tests build on-disk fixtures with `internal/endpoint/hooks/dshtest`. It also installs a Beacon-owned local skill at `$DSH_HOME/skills/beacon-endpoint/SKILL.md` and supports native session backfill from `$DSH_HOME/sessions` through `beacon endpoint dsh sync`, which fills assistant text/reasoning, tool failures, and token usage that the hook bridge does not expose. It rides the Claude-shaped envelope on the hook path, but `run_code` remains `tool.invoked` because nested commands fire their own hooks.
- fx (vercel-labs/fx) telemetry read from the session store fx commits under `~/.fx/sessions/`, covering session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, history compaction, and per-turn token usage plus reported cost. fx exposes no third-party hook, plugin, or OTLP surface -- its lifecycle hooks are compiled into the binary -- so collection is a read of fx's own records, run by `beacon endpoint fx sync`. Every event carries `harness.collection_method=poll`; approvals are not synthesized (fx persists permission feedback text, not a per-call decision, matching the Cline and Pi posture) and no session-end event is invented, since fx sessions are resumable. Implementation lives in `cli/beacon/internal/fxsession` and `cli/beacon/cmd/endpoint_fx.go`.
- Harness² (google-research/harness2) rollouts, read from the executor event streams Harness² records under its runs directory (`$HARNESS2_RUNS_DIR`, `~/harness2/runs`, or a `--runs-dir` an earlier sync was given and the cursor file remembers): OpenCode `run --format json` and Codex `exec --json`, recognized by their first event rather than by file name. Harness² runs Codex under its own `CODEX_HOME` with `--ephemeral` and OpenCode from a source checkout, so Beacon's Codex/OpenCode integrations do not record these sessions. Events carry `harness.name=harness2`, `harness.collection_method=poll`, the executor's own session id, and the rollout's benchmark/task/label/run/trial/attempt/harness fingerprint under `raw.harness2`. Codex `turn.completed` usage is the thread's running total and is differenced per turn; Codex exec lines carry no times, so they take the file's mtime. No prompts (an argv argument, absent from both streams) and no approvals are recorded or synthesized. `testdata/recorded` holds streams recorded from the exact OpenCode and Codex releases Harness² pins; re-record them when it bumps either. Implementation lives in `cli/beacon/internal/harness2session` and `cli/beacon/cmd/endpoint_harness2.go`.
-- Attribution of OTLP events: every account on a machine exports to the same loopback collector, and the exporter's base `user` is the collector process's own account (`asymptoteobserve.NewEvent` reads `$USER`/`$USERNAME`). On Linux, macOS and Windows the collector replaces it with the account that owns the sending socket (peer attribution): `collector.ConfigYAML` renders, only where `collector.PeerAttribution` (`runtime.GOOS` is `linux`, `darwin` or `windows`), the `beacon_otlp_http` receiver (`collector-builder/exporter/beaconjsonexporter/otlphttpreceiver`, the upstream OTLP/HTTP protocol rebuilt on confighttp so `client.Info.Addr` keeps the client port that upstream drops; it replaces `otlp.protocols.http` on the same port and carries the same `include_metadata` and `loopback_host` authenticator, so non-loopback Host headers are refused there too) and the `beacon_peer` processor (`peerprocessor`, right after `memory_limiter` and before `batch`, which loses the connection) on Beacon's own pipelines, never the OTLP forward's, plus `peer_user: true` on beaconjson. `beacon_peer` removes `beacon.peer.uid`/`beacon.peer.user` wherever a sender put them (resource, scope, record, span, span event and link, every datapoint type), then asks `internal/peercred` for the owner of the client socket of exactly this connection: the client address from `client.Info.Addr` and the collector's end from the gRPC peer's `LocalAddr` or net/http's `LocalAddrContextKey` (no server address, no lookup). On Linux `peercred` first asks the kernel with one `NETLINK_SOCK_DIAG` exact four-tuple lookup (`diag_linux.go`, constant cost per export) and scans `/proc/net/tcp{,6}` for the same four-tuple when sock_diag itself is unavailable or, until sock_diag has once answered with a socket, when it says ENOENT (the kernel says that for a missing `tcp_diag` handler too; a socket `/proc` finds then marks sock_diag blind for good); inode 0 (TIME_WAIT/orphan, uid printed 0), no match, or two owners are unknown, never guessed, and an unrelated TIME_WAIT on the same port is skipped. On macOS (`peercred_darwin.go`, parser `pcblist.go`, no cgo) it reads the whole `net.inet.tcp.pcblist_n` sysctl table netstat reads (one read per export, proportional to the machine's TCP sockets) and takes `so_uid` from the `xsocket_n` of the pcb whose `xinpcb_n` is exactly the client four-tuple (IPv4 in the last four address bytes, IPv6 and v4-mapped in all sixteen; offsets from xnu's `#pragma pack(4)` structs, records walked by length and kind and padded to 8, a table without its closing `xinpgen` refused); a pcb with no socket, `SS_NOFDREF` (closed by its owner), or `t_state` CLOSED/LISTEN/TIME_WAIT is passed over even though xnu keeps the creator's uid there. On Windows (`peercred_windows.go`, parser `tcptable.go`) `GetExtendedTcpTable` (`TCP_TABLE_OWNER_PID_ALL`, AF_INET and, for an IPv4 pair too, AF_INET6 for v4-mapped rows; ports in network byte order) gives the owning PID of exactly the four-tuple, skipping PID 0/4 and CLOSED/LISTEN/TIME_WAIT/DELETE_TCB rows; the process is opened (`PROCESS_QUERY_LIMITED_INFORMATION`), the table is read again and must still name that PID (a PID is not reused while a handle is open), and the answer is its token's `TokenUser` SID. A user-mode Windows collector can open only its own account's processes, so other accounts' exports are unknown there. Byte-fixture tests for both parsers run on every OS; the live-socket tests (`peercred_live_test.go`) run only on macOS and Windows CI. The name comes from `internal/accountname` (shared with `beacon_ingest`). The converter reads the peer attributes from the resource only (`mergeSignalAttrs`), and `applyPeerUser` copies them into `user` only with `Options.PeerUser`, and with it every `claude_cowork` event, log, span or datapoint, has an empty `user` (`applyPeerUser`, which every signal passes through, and `normalizeClaudeCoworkContext` for logs; Cowork reaches a collector only through a relay such as `beacon endpoint cowork --ngrok`, so the kernel names the relay's account, and the cloud identity is the sender's own claim; both stay in raw attributes; without `PeerUser` the cloud identity still replaces the collector's account); the `falcon_hec` exporter gets `peer_user: true` too, so LogScale matches the log; with `PeerUser` an unidentified sender gets an empty `user`, never the collector's root, so a recorded root always means root sent it. `CheckComponentsFor` refuses a collector without both where they are rendered. A platform without a lookup (anything but these three) keeps the collector's account, as did macOS and Windows collectors before this (root, or `COMPUTERNAME$` under LocalSystem). Hook and plugin events carry the person's uid or SID from `os/user.Current()` (verified by the OS in restricted mode). The person is also on the session's hook and plugin events, joined by `session.id`; the Sentinel guide carries the KQL. Peer attribution names the account that owns the sending socket, not necessarily the person who ran the agent (a relay, a shared service account, a process that inherited a socket), so never describe it as more than that.
+- Attribution of OTLP events: every account on a machine exports to the same loopback collector, and the exporter's base `user` is the collector process's own account (`asymptoteobserve.NewEvent` reads `$USER`/`$USERNAME`). On Linux, macOS and Windows the collector replaces it with the account that owns the sending socket (peer attribution): `collector.ConfigYAML` renders, only where `collector.PeerAttribution` (`runtime.GOOS` is `linux`, `darwin` or `windows`), the `beacon_otlp_http` receiver (`collector-builder/exporter/beaconjsonexporter/otlphttpreceiver`, the upstream OTLP/HTTP protocol rebuilt on confighttp so `client.Info.Addr` keeps the client port that upstream drops; it replaces `otlp.protocols.http` on the same port and carries the same `include_metadata` and `loopback_host` authenticator, so non-loopback Host headers are refused there too) and the `beacon_peer` processor (`peerprocessor`, right after `memory_limiter` and before `batch`, which loses the connection) on Beacon's own pipelines, never the OTLP forward's, plus `peer_user: true` on beaconjson. `beacon_peer` removes `beacon.peer.uid`/`beacon.peer.user` wherever a sender put them (resource, scope, record, span, span event and link, every datapoint type), then asks `internal/peercred` for the owner of the client socket of exactly this connection: the client address from `client.Info.Addr` and the collector's end from the gRPC peer's `LocalAddr` or net/http's `LocalAddrContextKey` (no server address, no lookup). On Linux `peercred` first asks the kernel with one `NETLINK_SOCK_DIAG` exact four-tuple lookup (`diag_linux.go`, constant cost per export) and scans `/proc/net/tcp{,6}` for the same four-tuple when sock_diag itself is unavailable or, until sock_diag has once answered with a socket, when it says ENOENT (the kernel says that for a missing `tcp_diag` handler too; a socket `/proc` finds then marks sock_diag blind for good); inode 0 (TIME_WAIT/orphan, uid printed 0), no match, or two owners are unknown, never guessed, and an unrelated TIME_WAIT on the same port is skipped. On macOS (`peercred_darwin.go`, parser `pcblist.go`, no cgo) it reads the whole `net.inet.tcp.pcblist_n` sysctl table netstat reads (one read per export, proportional to the machine's TCP sockets) and takes `so_uid` from the `xsocket_n` of the pcb whose `xinpcb_n` is exactly the client four-tuple (IPv4 in the last four address bytes, IPv6 and v4-mapped in all sixteen; offsets from xnu's `#pragma pack(4)` structs, records walked by length and kind and padded to 8, a table without its closing `xinpgen` refused); a pcb with no socket, `SS_NOFDREF` (closed by its owner), or `t_state` CLOSED/LISTEN/TIME_WAIT is passed over even though xnu keeps the creator's uid there. On Windows (`peercred_windows.go`, parser `tcptable.go`) `GetExtendedTcpTable` (`TCP_TABLE_OWNER_PID_ALL`, AF_INET and, for an IPv4 pair too, AF_INET6 for v4-mapped rows; ports in network byte order) gives the owning PID of exactly the four-tuple, skipping PID 0/4 and CLOSED/LISTEN/TIME_WAIT/DELETE_TCB rows and client ends already closed (FIN_WAIT1/2, CLOSING, LAST_ACK, which can keep an exited process's PID); the process is opened (`PROCESS_QUERY_LIMITED_INFORMATION`), the table is read again and must still name that PID (a PID is not reused while a handle is open), and the answer is its token's `TokenUser` SID. A user-mode Windows collector can open only its own account's processes, so other accounts' exports are unknown there. Byte-fixture tests for both parsers run on every OS; the live-socket tests (`peercred_live_test.go`) run only on macOS and Windows CI. The name comes from `internal/accountname` (shared with `beacon_ingest`). The converter reads the peer attributes from the resource only (`mergeSignalAttrs`), and `applyPeerUser` copies them into `user` only with `Options.PeerUser`, and with it every `claude_cowork` event, log, span or datapoint, has an empty `user` (`applyPeerUser`, which every signal passes through, and `normalizeClaudeCoworkContext` for logs; Cowork reaches a collector only through a relay such as `beacon endpoint cowork --ngrok`, so the kernel names the relay's account, and the cloud identity is the sender's own claim; both stay in raw attributes; without `PeerUser` the cloud identity still replaces the collector's account); the `falcon_hec` exporter gets `peer_user: true` too, so LogScale matches the log; with `PeerUser` an unidentified sender gets an empty `user`, never the collector's root, so a recorded root always means root sent it. On macOS and Windows the config renders peer attribution only for a collector that lists the no-op marker extension `beacon_peer_lookup` (`peerlookupextension`, in `builder.yaml`, named by no config) in `beacon-otelcol components` (`collector.PeerAttributionFor`, `peerLookupMarkerRequired`): older collectors already carry `beacon_peer` and `beacon_otlp_http` with a lookup that is unsupported there, and `peer_user` would leave their events with no `user`, so a new CLI with one (`--collector`, a CLI-only upgrade, a repair before the collector is replaced) or with a collector that cannot list its components keeps the previous config. `ConfigYAML` decides from the binary `cfg.Collector.BinaryPath` resolves to, the one install, repair and the CI session check (`ConfigYAMLWithPeer` takes the decision explicitly); Linux needs no marker and is unchanged. `CheckComponentsFor` refuses a collector without both where they are rendered, from the same listing. A platform without a lookup (anything but these three) keeps the collector's account, as did macOS and Windows collectors before this (root, or `COMPUTERNAME$` under LocalSystem). Hook and plugin events carry the person's uid or SID from `os/user.Current()` (verified by the OS in restricted mode). The person is also on the session's hook and plugin events, joined by `session.id`; the Sentinel guide carries the KQL. Peer attribution names the account that owns the sending socket, not necessarily the person who ran the agent (a relay, a shared service account, a process that inherited a socket), so never describe it as more than that.
- Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.
- OpenClaw Gateway uses a Beacon-managed plugin directory plus OpenClaw's own diagnostics OTLP guidance (`beacon endpoint integrations openclaw`). The plugin's `before_tool_call` hook is fail-closed, so the handler dispatches synchronously and returns without awaiting. Conversation hooks, including `llm_output`, require `plugins.entries.beacon-endpoint.hooks.allowConversationAccess`; without it, token and agent-message coverage is partial. Beacon reads OpenClaw JSON/JSON5 config for advice but does not rewrite it.
- GitHub Copilot CLI uses MDM/customer-managed OTLP HTTP for live spans and approval-like activity, plus `beacon endpoint copilot sync` to backfill local session records from `~/.copilot/session-state`. Poll events carry assistant text, complete tool results, command/file details, and token usage with `harness.collection_method=poll`, plus the shutdown's session-wide `totalNanoAiu` differenced into `gen_ai.usage.cost_usd` once per shutdown (10^9 nano-AIU = one AI credit = US$0.01), only for sessions started on or after the 2026-06-01 AI-credit cutover (`cli/beacon/internal/copilotsession/cost.go`); approvals still come only from the live OTLP path and are not synthesized from persisted records.
diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.go
index 6fac7677..32b863dd 100644
--- a/cli/beacon/internal/endpoint/collector/collector.go
+++ b/cli/beacon/internal/endpoint/collector/collector.go
@@ -162,21 +162,79 @@ const (
OTLPHTTPReceiver = "beacon_otlp_http"
)
-// PeerAttribution reports whether ConfigYAML renders peer attribution: on the platforms where the
+// PeerAttribution reports whether ConfigYAML can render peer attribution: on the platforms where the
// processor can ask the kernel who owns a loopback client socket (Linux: sock_diag or /proc/net/tcp;
// macOS: the net.inet.tcp.pcblist_n table; Windows: GetExtendedTcpTable and the owning process's
-// token). Elsewhere it would name nobody, so the upstream HTTP receiver stays as it was. A var so
-// tests on any platform can render either form.
+// token). Elsewhere it would name nobody, so the upstream HTTP receiver stays as it was. On macOS and
+// Windows it also takes a collector that can do the lookup (PeerAttributionFor). A var so tests on
+// any platform can render either form.
var PeerAttribution = runtime.GOOS == "linux" || runtime.GOOS == "darwin" || runtime.GOOS == "windows"
+// PeerLookupExtension is the marker a collector lists in `beacon-otelcol components` when its
+// beacon_peer can identify senders on macOS and Windows (collector-builder/.../peerlookupextension).
+// No config names it.
+const PeerLookupExtension = "beacon_peer_lookup"
+
+// peerLookupMarkerRequired is where a collector must list PeerLookupExtension for its config to
+// render peer attribution: macOS and Windows. Collectors released before peer attribution reached
+// them already carry beacon_peer and beacon_otlp_http, with a lookup that always answers
+// "unsupported" there; a config with peer_user would give every OTLP event from such a collector no
+// user at all, where it used to carry the collector's account. So a new CLI with an older collector
+// (--collector, a CLI-only upgrade, a repair before the collector is replaced) keeps the previous
+// config. Linux collectors have done the lookup since beacon_peer first shipped, so Linux needs no
+// marker and renders exactly as before. A var so tests on any platform can take either path.
+var peerLookupMarkerRequired = runtime.GOOS == "darwin" || runtime.GOOS == "windows"
+
+// PeerAttributionFor reports whether the config for the collector binary renders peer attribution.
+// Where the marker is required, a binary that does not list it -- including one that cannot list
+// its components at all -- gets the config without peer attribution: it records the collector's
+// account, as before, rather than no one.
+func PeerAttributionFor(binary string) bool {
+ if !PeerAttribution {
+ return false
+ }
+ if !peerLookupMarkerRequired {
+ return true
+ }
+ if binary == "" {
+ return false
+ }
+ listed, ok := readComponents(binary)
+ return ok && listed.has("extension", PeerLookupExtension)
+}
+
+// peerAttributionForConfig is PeerAttributionFor the collector cfg runs: the binary install,
+// repair and the CI session resolve from cfg.Collector.BinaryPath, and check with
+// CheckComponentsFor, before they write the config.
+func peerAttributionForConfig(cfg endpointconfig.Config) bool {
+ if !PeerAttribution {
+ return false
+ }
+ if !peerLookupMarkerRequired {
+ return true
+ }
+ binary, err := ResolveBinary(cfg.Collector.BinaryPath)
+ if err != nil {
+ return false
+ }
+ return PeerAttributionFor(binary)
+}
+
+// ConfigYAML renders the collector config for cfg, with peer attribution where the collector cfg
+// runs can do the lookup (see PeerAttributionFor).
func ConfigYAML(cfg endpointconfig.Config) string {
+ return ConfigYAMLWithPeer(cfg, peerAttributionForConfig(cfg))
+}
+
+// ConfigYAMLWithPeer renders the collector config for cfg with or without peer attribution.
+func ConfigYAMLWithPeer(cfg endpointconfig.Config, peer bool) string {
endpointconfig.NormalizeDestinations(&cfg)
exporterNames := []string{"beaconjson"}
splunkExporter := splunkHECYAML(cfg)
if splunkExporter != "" {
exporterNames = append(exporterNames, "splunk_hec")
}
- falconExporter := falconHECYAML(cfg)
+ falconExporter := falconHECYAML(cfg, peer)
if falconExporter != "" {
exporterNames = append(exporterNames, "falcon_hec")
}
@@ -246,7 +304,7 @@ func ConfigYAML(cfg endpointconfig.Config) string {
// writes, and only then. The OTLP forward's pipelines do not run it, so Beacon's attribution
// never reaches that backend.
receivers, httpReceiverYAML, otlpHTTPYAML, peerYAML, peerStep, peerExporterYAML := "[otlp]", "", "", "", "", ""
- if PeerAttribution {
+ if peer {
receivers = "[otlp, " + OTLPHTTPReceiver + "]"
httpReceiverYAML = fmt.Sprintf(" %s:\n endpoint: 127.0.0.1:%d\n%s", OTLPHTTPReceiver, cfg.Collector.HTTPPort, loopbackHostAuthYAML(" "))
peerYAML = " " + PeerProcessor + ": {}\n"
@@ -412,7 +470,7 @@ func splunkHECYAML(cfg endpointconfig.Config) string {
return b.String()
}
-func falconHECYAML(cfg endpointconfig.Config) string {
+func falconHECYAML(cfg endpointconfig.Config, peer bool) string {
if cfg.Destinations == nil || cfg.Destinations.FalconHEC == nil || !cfg.Destinations.FalconHEC.Enabled {
return ""
}
@@ -430,7 +488,7 @@ func falconHECYAML(cfg endpointconfig.Config) string {
if cfg.ClaudeCaptureModelContext {
fmt.Fprintf(&b, " capture_model_context: true\n")
}
- if PeerAttribution {
+ if peer {
// falcon_hec converts on its own, after beacon_peer in the same pipelines, so it is told to
// trust the account beacon_peer resolved just as beaconjson is; otherwise LogScale would
// record the collector's account for an event runtime.jsonl attributes to its sender.
diff --git a/cli/beacon/internal/endpoint/collector/components.go b/cli/beacon/internal/endpoint/collector/components.go
index 1a766d49..33e3d5fc 100644
--- a/cli/beacon/internal/endpoint/collector/components.go
+++ b/cli/beacon/internal/endpoint/collector/components.go
@@ -22,6 +22,54 @@ var listComponents = func(ctx context.Context, binary string) ([]byte, error) {
return exec.CommandContext(ctx, binary, "components").Output()
}
+type namedComponents []struct {
+ Name string `yaml:"name"`
+}
+
+// componentListing is what `beacon-otelcol components` prints, by kind.
+type componentListing struct {
+ Receivers namedComponents `yaml:"receivers"`
+ Processors namedComponents `yaml:"processors"`
+ Extensions namedComponents `yaml:"extensions"`
+ Exporters namedComponents `yaml:"exporters"`
+}
+
+func (l componentListing) has(kind, name string) bool {
+ var list namedComponents
+ switch kind {
+ case "receiver":
+ list = l.Receivers
+ case "processor":
+ list = l.Processors
+ case "extension":
+ list = l.Extensions
+ case "exporter":
+ list = l.Exporters
+ }
+ for _, c := range list {
+ if c.Name == name {
+ return true
+ }
+ }
+ return false
+}
+
+// readComponents lists binary's components. ok is false for a binary that cannot list them -- a
+// stand-in, or a build without the command -- or whose listing does not parse: nothing to judge it on.
+func readComponents(binary string) (componentListing, bool) {
+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+ defer cancel()
+ out, err := listComponents(ctx, binary)
+ if err != nil {
+ return componentListing{}, false
+ }
+ var listed componentListing
+ if yaml.Unmarshal(out, &listed) != nil || len(listed.Processors) == 0 {
+ return componentListing{}, false
+ }
+ return listed, true
+}
+
// CheckComponents refuses a collector binary that is older than the config this CLI writes.
//
// Packages and archives ship the collector beside the CLI from the same release, so this fails only
@@ -42,30 +90,20 @@ func CheckComponents(binary string, extensions ...string) error {
// CheckComponentsFor is CheckComponents with the processors and exporters the config will use
// beyond Beacon's own -- the OTLP forward's -- refused the same way. Where ConfigYAML renders peer
// attribution, its receiver and processor are required too.
+//
+// Which config that is depends on the collector: on macOS and Windows peer attribution is rendered
+// only for a collector that lists PeerLookupExtension (see PeerAttributionFor), so its receiver and
+// processor are required exactly when the listing says the config will name them.
func CheckComponentsFor(binary string, extensions, processors, exporters []string) error {
+ listed, ok := readComponents(binary)
+ if !ok {
+ return nil
+ }
var receivers []string
- if PeerAttribution {
+ if PeerAttribution && (!peerLookupMarkerRequired || listed.has("extension", PeerLookupExtension)) {
processors = append(append([]string{}, processors...), PeerProcessor)
receivers = append(receivers, OTLPHTTPReceiver)
}
- ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
- defer cancel()
- out, err := listComponents(ctx, binary)
- if err != nil {
- return nil
- }
- type named []struct {
- Name string `yaml:"name"`
- }
- var listed struct {
- Receivers named `yaml:"receivers"`
- Processors named `yaml:"processors"`
- Extensions named `yaml:"extensions"`
- Exporters named `yaml:"exporters"`
- }
- if yaml.Unmarshal(out, &listed) != nil || len(listed.Processors) == 0 {
- return nil
- }
have := map[string]bool{}
for _, c := range listed.Processors {
have["processor/"+c.Name] = true
diff --git a/cli/beacon/internal/endpoint/collector/peer_test.go b/cli/beacon/internal/endpoint/collector/peer_test.go
index 954140ea..7c94401b 100644
--- a/cli/beacon/internal/endpoint/collector/peer_test.go
+++ b/cli/beacon/internal/endpoint/collector/peer_test.go
@@ -1,7 +1,9 @@
package collector
import (
+ "errors"
"os"
+ "path/filepath"
"runtime"
"strings"
"testing"
@@ -14,19 +16,48 @@ import (
// TestMain changes it.
var shippedPeerAttribution = PeerAttribution
+// shippedMarkerRequired is peerLookupMarkerRequired as the package sets it for this platform.
+var shippedMarkerRequired = peerLookupMarkerRequired
+
// The other tests in this package pin the config rendered without peer attribution (a platform with
// no lookup); the tests below set PeerAttribution themselves.
func TestMain(m *testing.M) {
PeerAttribution = false
+ peerLookupMarkerRequired = false
os.Exit(m.Run())
}
+// withPeerAttribution renders peer attribution the way Linux does, for any collector.
func withPeerAttribution(t *testing.T) {
t.Helper()
PeerAttribution = true
t.Cleanup(func() { PeerAttribution = false })
}
+// withPeerAttributionIfMarked renders it the way macOS and Windows do: only for a collector that
+// lists PeerLookupExtension.
+func withPeerAttributionIfMarked(t *testing.T) {
+ t.Helper()
+ withPeerAttribution(t)
+ peerLookupMarkerRequired = true
+ t.Cleanup(func() { peerLookupMarkerRequired = false })
+}
+
+// fakeCollector is an executable file for cfg.Collector.BinaryPath; what it lists comes from
+// stubComponents.
+func fakeCollector(t *testing.T) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "beacon-otelcol")
+ if err := os.WriteFile(path, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+func rendersPeer(text string) bool {
+ return strings.Contains(text, PeerProcessor) || strings.Contains(text, OTLPHTTPReceiver) || strings.Contains(text, "peer_user")
+}
+
type renderedConfig struct {
Receivers map[string]any `yaml:"receivers"`
Processors map[string]any `yaml:"processors"`
@@ -148,6 +179,112 @@ func TestPeerAttributionIsOnWhereTheLookupExists(t *testing.T) {
if shippedPeerAttribution != want {
t.Fatalf("PeerAttribution on %s = %v, want %v", runtime.GOOS, shippedPeerAttribution, want)
}
+ // Linux collectors have done the lookup since beacon_peer shipped; on macOS and Windows only a
+ // collector that says so does.
+ if wantMarker := runtime.GOOS == "darwin" || runtime.GOOS == "windows"; shippedMarkerRequired != wantMarker {
+ t.Fatalf("peerLookupMarkerRequired on %s = %v, want %v", runtime.GOOS, shippedMarkerRequired, wantMarker)
+ }
+}
+
+// On macOS and Windows a collector from before peer attribution reached them lists beacon_peer and
+// beacon_otlp_http, but its lookup names nobody there. Its config stays the previous one, so OTLP
+// events keep the collector's account instead of losing their user, and install does not require
+// the peer components of it.
+func TestAnOlderCollectorKeepsThePreviousConfigWhereTheMarkerIsRequired(t *testing.T) {
+ withPeerAttributionIfMarked(t)
+ cfg := testConfig(t)
+ cfg.Collector.BinaryPath = fakeCollector(t)
+
+ stubComponents(t, peerComponents, nil) // beacon_peer and beacon_otlp_http, no marker
+ if PeerAttributionFor(cfg.Collector.BinaryPath) {
+ t.Fatal("PeerAttributionFor an unmarked collector = true")
+ }
+ text := ConfigYAML(cfg)
+ if rendersPeer(text) {
+ t.Fatalf("config for an unmarked collector renders peer attribution:\n%s", text)
+ }
+ if text != ConfigYAMLWithPeer(cfg, false) {
+ t.Fatalf("config for an unmarked collector differs from the previous config:\n%s", text)
+ }
+ if err := WriteConfig(cfg); err != nil {
+ t.Fatal(err)
+ }
+ if written, err := os.ReadFile(cfg.Collector.ConfigPath); err != nil || rendersPeer(string(written)) {
+ t.Fatalf("WriteConfig wrote peer attribution for an unmarked collector (%v):\n%s", err, written)
+ }
+ if err := CheckComponents(cfg.Collector.BinaryPath); err != nil {
+ t.Fatalf("CheckComponents = %v, want an unmarked collector accepted", err)
+ }
+ // Even one without the peer components at all: the config it gets does not name them.
+ stubComponents(t, strings.Replace(strings.Replace(peerComponents, " - name: beacon_peer\n", "", 1), " - name: beacon_otlp_http\n", "", 1), nil)
+ if err := CheckComponents(cfg.Collector.BinaryPath); err != nil {
+ t.Fatalf("CheckComponents = %v; a collector that gets no peer attribution needs neither component", err)
+ }
+ if rendersPeer(ConfigYAML(cfg)) {
+ t.Fatal("config renders peer attribution for a collector without its components")
+ }
+
+ // A collector that cannot list its components is not judged, and gets the previous config.
+ stubComponents(t, "", errors.New("unknown command"))
+ if rendersPeer(ConfigYAML(cfg)) || CheckComponents(cfg.Collector.BinaryPath) != nil {
+ t.Fatal("a collector that cannot list its components got peer attribution or was refused")
+ }
+ // As does a config whose collector cannot be found.
+ cfg.Collector.BinaryPath = filepath.Join(t.TempDir(), "missing")
+ stubComponents(t, markedPeerComponents, nil)
+ if rendersPeer(ConfigYAML(cfg)) {
+ t.Fatal("peer attribution rendered for a collector that does not exist")
+ }
+}
+
+// A collector that lists the marker gets peer attribution, and must then have its components.
+func TestAMarkedCollectorGetsPeerAttributionWhereTheMarkerIsRequired(t *testing.T) {
+ withPeerAttributionIfMarked(t)
+ cfg := testConfig(t)
+ cfg.Collector.BinaryPath = fakeCollector(t)
+ stubComponents(t, markedPeerComponents, nil)
+ if !PeerAttributionFor(cfg.Collector.BinaryPath) {
+ t.Fatal("PeerAttributionFor a marked collector = false")
+ }
+ text := ConfigYAML(cfg)
+ if text != ConfigYAMLWithPeer(cfg, true) {
+ t.Fatalf("config for a marked collector is not the peer config:\n%s", text)
+ }
+ out := render(t, cfg)
+ if _, ok := out.Processors[PeerProcessor]; !ok {
+ t.Fatalf("no %s processor:\n%s", PeerProcessor, text)
+ }
+ if out.Exporters["beaconjson"].(map[string]any)["peer_user"] != true {
+ t.Fatalf("beaconjson peer_user missing:\n%s", text)
+ }
+ if err := CheckComponents(cfg.Collector.BinaryPath); err != nil {
+ t.Fatalf("CheckComponents = %v, want a marked collector accepted", err)
+ }
+ stubComponents(t, strings.Replace(markedPeerComponents, " - name: beacon_peer\n", "", 1), nil)
+ if err := CheckComponents(cfg.Collector.BinaryPath); err == nil || !strings.Contains(err.Error(), `"beacon_peer" processor`) {
+ t.Fatalf("CheckComponents = %v, want the missing processor named", err)
+ }
+}
+
+// Linux needs no marker: every collector there renders and requires peer attribution, as before.
+func TestLinuxNeedsNoMarker(t *testing.T) {
+ withPeerAttribution(t)
+ cfg := testConfig(t)
+ cfg.Collector.BinaryPath = fakeCollector(t)
+ for _, listing := range []string{peerComponents, markedPeerComponents} {
+ stubComponents(t, listing, nil)
+ if !PeerAttributionFor(cfg.Collector.BinaryPath) || ConfigYAML(cfg) != ConfigYAMLWithPeer(cfg, true) {
+ t.Fatalf("Linux config without peer attribution for listing:\n%s", listing)
+ }
+ }
+ stubComponents(t, "", errors.New("unknown command"))
+ if !rendersPeer(ConfigYAML(cfg)) {
+ t.Fatal("Linux config lost peer attribution for a collector that cannot list its components")
+ }
+ stubComponents(t, strings.Replace(peerComponents, " - name: beacon_peer\n", "", 1), nil)
+ if err := CheckComponents(cfg.Collector.BinaryPath); err == nil {
+ t.Fatal("Linux accepted a collector without beacon_peer")
+ }
}
// Without peer attribution the config is what it always was.
@@ -180,6 +317,9 @@ extensions:
- name: loopback_host
`
+// markedPeerComponents is a collector that also lists the macOS/Windows lookup marker.
+var markedPeerComponents = strings.Replace(peerComponents, " - name: loopback_host\n", " - name: loopback_host\n - name: "+PeerLookupExtension+"\n", 1)
+
// A collector from before peer attribution would refuse the whole config at start; install says so
// first, as it does for every other component.
func TestCheckComponentsRequiresPeerAttributionWhereItIsRendered(t *testing.T) {
diff --git a/collector-builder/builder.yaml b/collector-builder/builder.yaml
index 48dd7399..31fd7958 100644
--- a/collector-builder/builder.yaml
+++ b/collector-builder/builder.yaml
@@ -5,7 +5,7 @@ dist:
receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.121.0
- # OTLP/HTTP that keeps the client's port, so beacon_peer can name the sending account (Linux).
+ # OTLP/HTTP that keeps the client's port, so beacon_peer can name the sending account.
- gomod: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter v0.0.0
import: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/otlphttpreceiver
path: ./exporter/beaconjsonexporter
@@ -45,6 +45,11 @@ extensions:
- gomod: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter v0.0.0
import: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/beaconingestextension
path: ./exporter/beaconjsonexporter
+ # A marker no config names: listed by `beacon-otelcol components`, it tells the CLI this
+ # collector's beacon_peer can identify senders on macOS and Windows as well as Linux.
+ - gomod: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter v0.0.0
+ import: github.com/asymptote-labs/agent-beacon/collector-builder/exporter/beaconjsonexporter/peerlookupextension
+ path: ./exporter/beaconjsonexporter
replaces:
- github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve => ../../../pkg/asymptoteobserve
diff --git a/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension.go b/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension.go
new file mode 100644
index 00000000..385b5ff6
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension.go
@@ -0,0 +1,46 @@
+// Package peerlookupextension is a marker: a collector that lists the beacon_peer_lookup extension
+// in `beacon-otelcol components` has a beacon_peer processor that can ask the operating system who
+// owns a loopback client socket on Linux, macOS and Windows.
+//
+// Collectors from before macOS and Windows support already carry beacon_peer and beacon_otlp_http,
+// built with a lookup that always answers "unsupported" there, so their component lists alone do
+// not tell the CLI whether peer attribution would name anyone. A config rendered with peer_user for
+// such a collector would record every OTLP event with no user at all, where it used to carry the
+// collector's account. The CLI therefore renders peer attribution on macOS and Windows only for a
+// collector that lists this extension, and the previous config otherwise.
+//
+// The extension does nothing, and no config needs to name it; it exists to be listed. Being an
+// extension in the collector's own build, it cannot be present without the peercred code it
+// stands for, unlike a version number, which development builds and forks do not keep.
+package peerlookupextension
+
+import (
+ "context"
+
+ "go.opentelemetry.io/collector/component"
+ "go.opentelemetry.io/collector/extension"
+)
+
+// Type is the component name the CLI looks for.
+const Type = "beacon_peer_lookup"
+
+var componentType = component.MustNewType(Type)
+
+// Config has no settings.
+type Config struct{}
+
+func NewFactory() extension.Factory {
+ return extension.NewFactory(
+ componentType,
+ func() component.Config { return &Config{} },
+ func(context.Context, extension.Settings, component.Config) (extension.Extension, error) {
+ return noop{}, nil
+ },
+ component.StabilityLevelBeta,
+ )
+}
+
+type noop struct{}
+
+func (noop) Start(context.Context, component.Host) error { return nil }
+func (noop) Shutdown(context.Context) error { return nil }
diff --git a/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension_test.go b/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension_test.go
new file mode 100644
index 00000000..ab1502cb
--- /dev/null
+++ b/collector-builder/exporter/beaconjsonexporter/peerlookupextension/extension_test.go
@@ -0,0 +1,28 @@
+package peerlookupextension
+
+import (
+ "context"
+ "testing"
+
+ "go.opentelemetry.io/collector/component/componenttest"
+ "go.opentelemetry.io/collector/extension/extensiontest"
+)
+
+// The CLI matches this exact name in `beacon-otelcol components`; renaming it turns peer attribution
+// off on macOS and Windows for every collector built after the rename.
+func TestTheMarkerIsListedUnderItsName(t *testing.T) {
+ f := NewFactory()
+ if got := f.Type().String(); got != "beacon_peer_lookup" {
+ t.Fatalf("type = %q, want beacon_peer_lookup", got)
+ }
+ ext, err := f.Create(context.Background(), extensiontest.NewNopSettings(f.Type()), f.CreateDefaultConfig())
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := ext.Start(context.Background(), componenttest.NewNopHost()); err != nil {
+ t.Fatal(err)
+ }
+ if err := ext.Shutdown(context.Background()); err != nil {
+ t.Fatal(err)
+ }
+}