Skip to content

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

Let user-mode and system-mode collectors coexist (health-check port)

Claude00a36e9d9909
diff --git a/cli/beacon/cmd/endpoint.go b/cli/beacon/cmd/endpoint.go
index 8ae63fe7..f4606221 100644
--- a/cli/beacon/cmd/endpoint.go
+++ b/cli/beacon/cmd/endpoint.go
@@ -27,6 +27,7 @@ var endpointOpts struct {
jsonOutput bool
grpcPort int
httpPort int
+ healthPort int
collectorPath string
includeRuntimeMetrics bool
includeCodexSpans bool
@@ -418,6 +419,7 @@ func init() {
endpointInstallCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", endpointHarnessAuto, "Harnesses to configure: auto (detected runtimes), all, or a comma-separated list")
endpointInstallCmd.Flags().IntVar(&endpointOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")
endpointInstallCmd.Flags().IntVar(&endpointOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
+ endpointInstallCmd.Flags().IntVar(&endpointOpts.healthPort, "health-port", 0, "Local collector health-check port; 0 derives it from --otlp-http-port (13133 with the default ports)")
endpointInstallCmd.Flags().StringVar(&endpointOpts.collectorPath, "collector", "", "Path to a beacon-otelcol binary")
endpointInstallCmd.Flags().BoolVar(&endpointOpts.includeRuntimeMetrics, "include-runtime-metrics", false, "Include generic process/runtime OTLP metrics and harness operational metrics (OpenClaw, Copilot CLI) in the runtime JSONL log")
endpointInstallCmd.Flags().BoolVar(&endpointOpts.includeCodexSpans, "include-codex-spans", false, "Include high-volume Codex OTLP spans for troubleshooting")
@@ -439,6 +441,7 @@ func init() {
endpointRepairCmd.Flags().StringVar(&endpointOpts.harnesses, "harness", endpointHarnessAuto, "Harnesses to configure: auto (detected runtimes), all, or a comma-separated list")
endpointRepairCmd.Flags().IntVar(&endpointOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")
endpointRepairCmd.Flags().IntVar(&endpointOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
+ endpointRepairCmd.Flags().IntVar(&endpointOpts.healthPort, "health-port", 0, "Local collector health-check port; 0 derives it from --otlp-http-port (13133 with the default ports)")
endpointRepairCmd.Flags().StringVar(&endpointOpts.collectorPath, "collector", "", "Path to a beacon-otelcol binary")
endpointRepairCmd.Flags().BoolVar(&endpointOpts.includeRuntimeMetrics, "include-runtime-metrics", false, "Include generic process/runtime OTLP metrics and harness operational metrics (OpenClaw, Copilot CLI) in the runtime JSONL log")
endpointRepairCmd.Flags().BoolVar(&endpointOpts.includeCodexSpans, "include-codex-spans", false, "Include high-volume Codex OTLP spans for troubleshooting")
diff --git a/cli/beacon/cmd/endpoint_healthport_test.go b/cli/beacon/cmd/endpoint_healthport_test.go
new file mode 100644
index 00000000..964271eb
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_healthport_test.go
@@ -0,0 +1,21 @@
+package cmd
+
+import "testing"
+
+// #447: the health-check port is settable per install, like the OTLP ports, and defaults to 0 so
+// the lifecycle derives it rather than every install getting a fixed 13133.
+func TestEndpointInstallAndRepairExposeHealthPortFlag(t *testing.T) {
+ for _, cmd := range []string{"install", "repair"} {
+ c := endpointInstallCmd
+ if cmd == "repair" {
+ c = endpointRepairCmd
+ }
+ flag := c.Flags().Lookup("health-port")
+ if flag == nil {
+ t.Fatalf("endpoint %s has no --health-port flag", cmd)
+ }
+ if flag.DefValue != "0" {
+ t.Fatalf("endpoint %s --health-port default = %q, want 0 (derive from the OTLP ports)", cmd, flag.DefValue)
+ }
+ }
+}
diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.go
index 4ac6baea..7ea51eb7 100644
--- a/cli/beacon/cmd/endpoint_install.go
+++ b/cli/beacon/cmd/endpoint_install.go
@@ -119,6 +119,7 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {
Harnesses: selection.OTLP,
GRPCPort: endpointOpts.grpcPort,
HTTPPort: endpointOpts.httpPort,
+ HealthPort: endpointOpts.healthPort,
CollectorPath: endpointOpts.collectorPath,
StartService: !endpointOpts.noStart,
IncludeRuntimeMetrics: endpointOpts.includeRuntimeMetrics,
@@ -290,6 +291,7 @@ func runEndpointRepair(cmd *cobra.Command, args []string) error {
Harnesses: selection.OTLP,
GRPCPort: endpointOpts.grpcPort,
HTTPPort: endpointOpts.httpPort,
+ HealthPort: endpointOpts.healthPort,
CollectorPath: endpointOpts.collectorPath,
StartService: !endpointOpts.noStart,
IncludeRuntimeMetrics: endpointOpts.includeRuntimeMetrics,
diff --git a/cli/beacon/internal/ci/healthport_test.go b/cli/beacon/internal/ci/healthport_test.go
new file mode 100644
index 00000000..c5698540
--- /dev/null
+++ b/cli/beacon/internal/ci/healthport_test.go
@@ -0,0 +1,37 @@
+package ci
+
+import (
+ "os"
+ "strings"
+ "testing"
+)
+
+// A `beacon ci` collector on custom OTLP ports gets the same derived health port an endpoint
+// install would, rather than always 13133, so it can run beside an endpoint collector.
+func TestProvisionDerivesTheHealthPortFromTheOTLPPorts(t *testing.T) {
+ t.Setenv("RUNNER_TEMP", t.TempDir())
+ collector := fakeExecutable(t, "collector", "#!/bin/sh\nsleep 60\n")
+ oldResolve := resolveCollectorBinary
+ resolveCollectorBinary = func(string) (string, error) { return collector, nil }
+ t.Cleanup(func() { resolveCollectorBinary = oldResolve })
+
+ for _, tc := range []struct {
+ grpc, http int
+ want string
+ }{
+ {0, 0, "endpoint: 127.0.0.1:13133\n"},
+ {5317, 5318, "endpoint: 127.0.0.1:14133\n"},
+ } {
+ session, err := Provision(Options{CollectorPath: collector, Harness: "claude", GRPCPort: tc.grpc, HTTPPort: tc.http})
+ if err != nil {
+ t.Fatalf("Provision: %v", err)
+ }
+ data, err := os.ReadFile(session.ConfigPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(data), "health_check:\n "+tc.want) {
+ t.Fatalf("ports %d/%d: collector config health_check does not contain %q:\n%s", tc.grpc, tc.http, tc.want, data)
+ }
+ }
+}
diff --git a/cli/beacon/internal/ci/session.go b/cli/beacon/internal/ci/session.go
index 7102f26b..8685e99d 100644
--- a/cli/beacon/internal/ci/session.go
+++ b/cli/beacon/internal/ci/session.go
@@ -133,6 +133,7 @@ func Provision(opts Options) (*Session, error) {
cfg.Collector.SpoolPath = filepath.Join(baseDir, "spool", "otlp.jsonl")
cfg.Collector.GRPCPort = grpcPort
cfg.Collector.HTTPPort = httpPort
+ cfg.Collector.HealthPort = endpointconfig.DeriveHealthCheckPort(grpcPort, httpPort)
cfg.Collector.IncludeCodexSpans = opts.IncludeCodexSpans
forward, err := normalizeForward(opts.Forward)
if err != nil {
diff --git a/cli/beacon/internal/endpoint/collector/collector.go b/cli/beacon/internal/endpoint/collector/collector.go
index 925c31d5..88445b10 100644
--- a/cli/beacon/internal/endpoint/collector/collector.go
+++ b/cli/beacon/internal/endpoint/collector/collector.go
@@ -16,7 +16,6 @@ import (
const (
BinaryName = "beacon-otelcol"
PackagedBinaryPath = "/opt/beacon/bin/beacon-otelcol"
- HealthCheckPort = 13133
)
var (
@@ -30,6 +29,7 @@ type Status struct {
ConfigPath string `json:"config_path,omitempty"`
GRPCPort int `json:"grpc_port"`
HTTPPort int `json:"http_port"`
+ HealthPort int `json:"health_port"`
GRPCReady bool `json:"grpc_ready"`
HTTPReady bool `json:"http_ready"`
HealthReady bool `json:"health_ready"`
@@ -168,7 +168,7 @@ exporters:
%s
extensions:
health_check:
- endpoint: 127.0.0.1:13133
+ endpoint: 127.0.0.1:%d
service:
telemetry:
@@ -188,7 +188,7 @@ service:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: %s
-`, cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, cfg.LogPath, runtimeMetricsYAML+codexSpansYAML+splunkExporter+falconExporter, exporters, exporters, exporters)
+`, cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, cfg.LogPath, runtimeMetricsYAML+codexSpansYAML+splunkExporter+falconExporter, endpointconfig.HealthCheckPort(cfg.Collector), exporters, exporters, exporters)
}
func splunkHECYAML(cfg endpointconfig.Config) string {
@@ -256,21 +256,23 @@ func falconHECYAML(cfg endpointconfig.Config) string {
func CheckStatus(cfg endpointconfig.Config) Status {
binary := DiscoverBinary(cfg.Collector.BinaryPath)
+ healthPort := endpointconfig.HealthCheckPort(cfg.Collector)
status := Status{
BinaryPath: binary,
ConfigPath: cfg.Collector.ConfigPath,
GRPCPort: cfg.Collector.GRPCPort,
HTTPPort: cfg.Collector.HTTPPort,
+ HealthPort: healthPort,
GRPCReady: portOpen(cfg.Collector.GRPCPort),
HTTPReady: portOpen(cfg.Collector.HTTPPort),
- HealthReady: healthReady(),
+ HealthReady: healthReady(healthPort),
}
if binary == "" {
status.Message = "OpenTelemetry Collector binary was not found on PATH"
} else if !status.GRPCReady && !status.HTTPReady {
status.Message = "Collector ports are not listening"
} else if !status.HealthReady {
- status.Message = "Collector health check is not ready"
+ status.Message = fmt.Sprintf("Collector health check on 127.0.0.1:%d is not ready", healthPort)
}
return status
}
@@ -292,23 +294,35 @@ func WaitUntilReady(cfg endpointconfig.Config, timeout time.Duration) error {
}
}
-func WaitForPortsAvailable(grpcPort, httpPort int, timeout time.Duration) error {
+// WaitForPortsAvailable waits for every port the collector will bind -- the two OTLP receivers
+// and the health_check extension -- to be free, and names the ones that stay taken.
+//
+// The health port is checked with the others because it fails the collector just as surely: a
+// second collector whose OTLP ports were free but whose health port was held by the first used to
+// pass this wait, exit on start, and be reported as "Collector ports are not listening" (#447).
+func WaitForPortsAvailable(grpcPort, httpPort, healthPort int, timeout time.Duration) error {
deadline := time.Now().Add(timeout)
for {
grpcAvailable := PortAvailable(grpcPort)
httpAvailable := PortAvailable(httpPort)
- if grpcAvailable && httpAvailable {
+ healthAvailable := PortAvailable(healthPort)
+ if grpcAvailable && httpAvailable && healthAvailable {
return nil
}
if time.Now().After(deadline) {
+ var busy []string
switch {
case !grpcAvailable && !httpAvailable:
- return fmt.Errorf("OTLP gRPC port %d and HTTP port %d are already in use", grpcPort, httpPort)
+ busy = append(busy, fmt.Sprintf("OTLP gRPC port %d and HTTP port %d are already in use", grpcPort, httpPort))
case !grpcAvailable:
- return fmt.Errorf("OTLP gRPC port %d is already in use", grpcPort)
- default:
- return fmt.Errorf("OTLP HTTP port %d is already in use", httpPort)
+ busy = append(busy, fmt.Sprintf("OTLP gRPC port %d is already in use", grpcPort))
+ case !httpAvailable:
+ busy = append(busy, fmt.Sprintf("OTLP HTTP port %d is already in use", httpPort))
+ }
+ if !healthAvailable {
+ busy = append(busy, fmt.Sprintf("collector health-check port %d is already in use (another Beacon collector, such as a system-mode install, may hold it; choose another with --health-port)", healthPort))
}
+ return fmt.Errorf("%s", strings.Join(busy, "; "))
}
time.Sleep(250 * time.Millisecond)
}
@@ -332,9 +346,9 @@ func portOpen(port int) bool {
return true
}
-func healthReady() bool {
+func healthReady(port int) bool {
client := http.Client{Timeout: 500 * time.Millisecond}
- resp, err := client.Get(fmt.Sprintf("http://127.0.0.1:%d/", HealthCheckPort))
+ resp, err := client.Get(fmt.Sprintf("http://127.0.0.1:%d/", port))
if err != nil {
return false
}
diff --git a/cli/beacon/internal/endpoint/collector/collector_test.go b/cli/beacon/internal/endpoint/collector/collector_test.go
index db50cc4a..fefe6a92 100644
--- a/cli/beacon/internal/endpoint/collector/collector_test.go
+++ b/cli/beacon/internal/endpoint/collector/collector_test.go
@@ -244,7 +244,7 @@ func TestWaitForPortsAvailableWaitsForTransientListeners(t *testing.T) {
_ = httpListener.Close()
}()
- if err := WaitForPortsAvailable(grpcPort, httpPort, 2*time.Second); err != nil {
+ if err := WaitForPortsAvailable(grpcPort, httpPort, freeTestPort(t), 2*time.Second); err != nil {
t.Fatalf("WaitForPortsAvailable returned error: %v", err)
}
}
@@ -262,7 +262,7 @@ func TestWaitForPortsAvailableReportsPersistentConflict(t *testing.T) {
httpPort := httpListener.Addr().(*net.TCPAddr).Port
_ = httpListener.Close()
- err = WaitForPortsAvailable(grpcListener.Addr().(*net.TCPAddr).Port, httpPort, 50*time.Millisecond)
+ err = WaitForPortsAvailable(grpcListener.Addr().(*net.TCPAddr).Port, httpPort, freeTestPort(t), 50*time.Millisecond)
if err == nil || !strings.Contains(err.Error(), "OTLP gRPC port") {
t.Fatalf("WaitForPortsAvailable error = %v, want gRPC port conflict", err)
}
@@ -368,7 +368,7 @@ func TestPortAvailabilityAndOpenChecks(t *testing.T) {
}
func TestCheckStatusDoesNotTreatOpenOTLPPortsAsHealthy(t *testing.T) {
- if healthReady() {
+ if healthReady(endpointconfig.DefaultHealthCheckPort) {
t.Skip("collector health check endpoint is already active")
}
bin := filepath.Join(t.TempDir(), stubCollectorName())
@@ -403,7 +403,7 @@ func TestCheckStatusDoesNotTreatOpenOTLPPortsAsHealthy(t *testing.T) {
}
func TestHealthReadyChecksCollectorHealthEndpoint(t *testing.T) {
- if !PortAvailable(HealthCheckPort) {
+ if !PortAvailable(endpointconfig.DefaultHealthCheckPort) {
t.Skip("collector health check port is already in use")
}
server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -423,7 +423,7 @@ func TestHealthReadyChecksCollectorHealthEndpoint(t *testing.T) {
<-done
})
- if !healthReady() {
+ if !healthReady(endpointconfig.DefaultHealthCheckPort) {
t.Fatal("healthReady() = false, want true")
}
}
diff --git a/cli/beacon/internal/endpoint/collector/healthport_test.go b/cli/beacon/internal/endpoint/collector/healthport_test.go
new file mode 100644
index 00000000..68815ce5
--- /dev/null
+++ b/cli/beacon/internal/endpoint/collector/healthport_test.go
@@ -0,0 +1,150 @@
+package collector
+
+import (
+ "net"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strconv"
+ "strings"
+ "testing"
+ "time"
+)
+
+func freeTestPort(t *testing.T) int {
+ t.Helper()
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer ln.Close()
+ return ln.Addr().(*net.TCPAddr).Port
+}
+
+// serveHealth answers 200 on a free loopback port, standing in for the health_check extension.
+func serveHealth(t *testing.T) int {
+ t.Helper()
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(http.StatusOK)
+ })}
+ done := make(chan struct{})
+ go func() {
+ _ = server.Serve(ln)
+ close(done)
+ }()
+ t.Cleanup(func() {
+ _ = server.Close()
+ <-done
+ })
+ return ln.Addr().(*net.TCPAddr).Port
+}
+
+// #447: the rendered collector config used to hardcode 127.0.0.1:13133 whatever the install asked for.
+func TestConfigYAMLRendersTheConfiguredHealthPort(t *testing.T) {
+ cfg := testConfig(t)
+ cfg.Collector.HealthPort = 13143
+
+ yaml := ConfigYAML(cfg)
+
+ if !strings.Contains(yaml, "health_check:\n endpoint: 127.0.0.1:13143\n") {
+ t.Fatalf("collector config does not bind the configured health port:\n%s", yaml)
+ }
+ if strings.Contains(yaml, "13133") {
+ t.Fatalf("collector config still carries the fixed 13133:\n%s", yaml)
+ }
+}
+
+// Upgrade safety: re-rendering a config recorded before the field existed keeps the port the
+// running collector already binds.
+func TestConfigYAMLKeepsTheDefaultHealthPortForALegacyConfig(t *testing.T) {
+ cfg := testConfig(t)
+ cfg.Collector.HealthPort = 0
+
+ yaml := ConfigYAML(cfg)
+
+ if !strings.Contains(yaml, "health_check:\n endpoint: 127.0.0.1:13133\n") {
+ t.Fatalf("legacy config should render the default health port:\n%s", yaml)
+ }
+}
+
+// Status and the install readiness wait have to probe the port the collector was told to bind.
+func TestCheckStatusProbesTheConfiguredHealthPort(t *testing.T) {
+ healthPort := serveHealth(t)
+ cfg := testConfig(t)
+ cfg.Collector.GRPCPort = freeTestPort(t)
+ cfg.Collector.HTTPPort = freeTestPort(t)
+ cfg.Collector.HealthPort = healthPort
+
+ status := CheckStatus(cfg)
+
+ if !status.HealthReady {
+ t.Fatalf("HealthReady = false with a healthy endpoint on the configured port %d: %#v", healthPort, status)
+ }
+ if status.HealthPort != healthPort {
+ t.Fatalf("status HealthPort = %d, want %d", status.HealthPort, healthPort)
+ }
+}
+
+func TestCheckStatusNamesTheHealthPortItProbed(t *testing.T) {
+ grpcLn, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer grpcLn.Close()
+ httpLn, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer httpLn.Close()
+ cfg := testConfig(t)
+ cfg.Collector.BinaryPath = writeStubCollector(t)
+ cfg.Collector.GRPCPort = grpcLn.Addr().(*net.TCPAddr).Port
+ cfg.Collector.HTTPPort = httpLn.Addr().(*net.TCPAddr).Port
+ cfg.Collector.HealthPort = freeTestPort(t)
+
+ status := CheckStatus(cfg)
+
+ if status.HealthReady {
+ t.Fatalf("HealthReady = true with nothing on the health port: %#v", status)
+ }
+ if want := "127.0.0.1:" + strconv.Itoa(cfg.Collector.HealthPort); !strings.Contains(status.Message, want) {
+ t.Fatalf("Message = %q, want it to name %s", status.Message, want)
+ }
+}
+
+// #447: the readiness preflight used to check only the OTLP ports, so a health port held by the
+// system collector passed it and the install failed later with an error blaming the OTLP ports.
+func TestWaitForPortsAvailableReportsAHealthPortConflict(t *testing.T) {
+ healthLn, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer healthLn.Close()
+ healthPort := healthLn.Addr().(*net.TCPAddr).Port
+
+ err = WaitForPortsAvailable(freeTestPort(t), freeTestPort(t), healthPort, 50*time.Millisecond)
+
+ if err == nil {
+ t.Fatal("WaitForPortsAvailable returned nil with the health port held")
+ }
+ msg := err.Error()
+ if !strings.Contains(msg, "health-check port "+strconv.Itoa(healthPort)) || !strings.Contains(msg, "--health-port") {
+ t.Fatalf("error = %q, want it to name health-check port %d and --health-port", msg, healthPort)
+ }
+ if strings.Contains(msg, "OTLP") {
+ t.Fatalf("error = %q blames the OTLP ports, which are free", msg)
+ }
+}
+
+func writeStubCollector(t *testing.T) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), stubCollectorName())
+ if err := os.WriteFile(path, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
diff --git a/cli/beacon/internal/endpoint/collector/startlog.go b/cli/beacon/internal/endpoint/collector/startlog.go
new file mode 100644
index 00000000..7f3efc69
--- /dev/null
+++ b/cli/beacon/internal/endpoint/collector/startlog.go
@@ -0,0 +1,107 @@
+package collector
+
+import (
+ "bufio"
+ "bytes"
+ "io"
+ "os"
+ "strings"
+)
+
+const (
+ // startLogReadLimit bounds how much of the collector's log is read back after a failed start.
+ // The line that explains an exit on start is at the end, and a launchd log under /tmp is
+ // appended to across every restart, so there is no reason to read the whole file.
+ startLogReadLimit = 64 << 10
+ // startLogLineLimit keeps one pathological line from swamping the install error it is quoted in.
+ startLogLineLimit = 400
+)
+
+// LogSize reports the current size of the collector log at path, or zero when there is none.
+//
+// Taken before the collector is started so LogErrorSince reads only what this start wrote: the
+// launchd and supervised logs are appended to across runs, and quoting a line left by some earlier
+// failure would misdirect the person reading the install error.
+func LogSize(path string) int64 {
+ if path == "" {
+ return 0
+ }
+ info, err := os.Stat(path)
+ if err != nil {
+ return 0
+ }
+ return info.Size()
+}
+
+// LogErrorSince returns the line that best explains a collector that did not become ready: the
+// last line written after offset that reads as an error, or failing that the last non-empty line.
+// It returns "" when nothing was written.
+//
+// The collector writes its fatal reason to stderr and exits -- "failed to bind to address
+// 127.0.0.1:13133 ... address already in use" was the #447 case -- and an install that reports only
+// "ports are not listening" hides that reason in a file the user has no cause to open.
+func LogErrorSince(path string, offset int64) string {
+ if path == "" {
+ return ""
+ }
+ f, err := os.Open(path)
+ if err != nil {
+ return ""
+ }
+ defer f.Close()
+ info, err := f.Stat()
+ if err != nil {
+ return ""
+ }
+ size := info.Size()
+ if offset < 0 || offset > size {
+ // Smaller than when the start began: rotated or truncated, so all of it is new.
+ offset = 0
+ }
+ if size-offset > startLogReadLimit {
+ offset = size - startLogReadLimit
+ }
+ if _, err := f.Seek(offset, io.SeekStart); err != nil {
+ return ""
+ }
+ data, err := io.ReadAll(io.LimitReader(f, startLogReadLimit))
+ if err != nil {
+ return ""
+ }
+ var lastLine, lastError string
+ scanner := bufio.NewScanner(bytes.NewReader(data))
+ scanner.Buffer(make([]byte, 0, 4096), startLogReadLimit)
+ for scanner.Scan() {
+ line := strings.TrimSpace(scanner.Text())
+ if line == "" {
+ continue
+ }
+ lastLine = line
+ if looksLikeError(line) {
+ lastError = line
+ }
+ }
+ line := lastError
+ if line == "" {
+ line = lastLine
+ }
+ return truncateLogLine(line)
+}
+
+func looksLikeError(line string) bool {
+ lower := strings.ToLower(line)
+ for _, marker := range []string{"error", "failed", "fatal", "panic"} {
+ if strings.Contains(lower, marker) {
+ return true
+ }
+ }
+ return false
+}
+
+func truncateLogLine(line string) string {
+ runes := []rune(line)
+ if len(runes) <= startLogLineLimit {
+ return line
+ }
+ return string(runes[:startLogLineLimit]) + "..."
+}
diff --git a/cli/beacon/internal/endpoint/collector/startlog_test.go b/cli/beacon/internal/endpoint/collector/startlog_test.go
new file mode 100644
index 00000000..5ef7842f
--- /dev/null
+++ b/cli/beacon/internal/endpoint/collector/startlog_test.go
@@ -0,0 +1,76 @@
+package collector
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func appendLog(t *testing.T, path, text string) {
+ t.Helper()
+ f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer f.Close()
+ if _, err := f.WriteString(text); err != nil {
+ t.Fatal(err)
+ }
+}
+
+// The #447 line, as the collector wrote it, must reach the install error -- and a failure left in
+// the same appended-to file by an earlier run must not be quoted in its place.
+func TestLogErrorSinceQuotesOnlyWhatThisStartWrote(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "collector.err")
+ appendLog(t, path, "Error: stale failure from an earlier run\n")
+ offset := LogSize(path)
+ bind := `Failed to start extension health_check failed to bind to address 127.0.0.1:13133: listen tcp 127.0.0.1:13133: bind: address already in use`
+ appendLog(t, path, "2026-09-04T17:00:00Z info service starting\n"+bind+"\n2026-09-04T17:00:01Z info shutdown complete\n")
+
+ got := LogErrorSince(path, offset)
+
+ if got != strings.TrimSpace(bind) {
+ t.Fatalf("LogErrorSince = %q, want the bind failure", got)
+ }
+}
+
+func TestLogErrorSinceFallsBackToTheLastLine(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "collector.out")
+ appendLog(t, path, "first\n\nsomething odd happened\n\n")
+ if got := LogErrorSince(path, 0); got != "something odd happened" {
+ t.Fatalf("LogErrorSince = %q, want the last non-empty line", got)
+ }
+}
+
+func TestLogErrorSinceIsEmptyWhenNothingNewWasWritten(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "collector.err")
+ appendLog(t, path, "Error: old\n")
+ if got := LogErrorSince(path, LogSize(path)); got != "" {
+ t.Fatalf("LogErrorSince = %q, want empty", got)
+ }
+ if got := LogErrorSince(filepath.Join(t.TempDir(), "missing"), 0); got != "" {
+ t.Fatalf("LogErrorSince(missing) = %q, want empty", got)
+ }
+ if got := LogErrorSince("", 0); got != "" {
+ t.Fatalf("LogErrorSince(\"\") = %q, want empty", got)
+ }
+}
+
+// A log that shrank since the offset was taken was rotated or truncated, so all of it is new.
+func TestLogErrorSinceReadsAFileThatShrankFromTheStart(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "collector.err")
+ appendLog(t, path, "Error: bind failed\n")
+ if got := LogErrorSince(path, 1<<20); got != "Error: bind failed" {
+ t.Fatalf("LogErrorSince = %q, want the line in the truncated file", got)
+ }
+}
+
+func TestLogErrorSinceBoundsALongLine(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "collector.err")
+ appendLog(t, path, "Error: "+strings.Repeat("x", 5000)+"\n")
+ got := LogErrorSince(path, 0)
+ if len([]rune(got)) > startLogLineLimit+3 || !strings.HasPrefix(got, "Error: ") || !strings.HasSuffix(got, "...") {
+ t.Fatalf("LogErrorSince returned %d runes, want at most %d with an ellipsis", len([]rune(got)), startLogLineLimit+3)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/config/config.go b/cli/beacon/internal/endpoint/config/config.go
index 262e0b16..1ae2a677 100644
--- a/cli/beacon/internal/endpoint/config/config.go
+++ b/cli/beacon/internal/endpoint/config/config.go
@@ -23,6 +23,10 @@ const (
UserConfigPath = ".beacon/endpoint/config.json"
DefaultGRPCPort = 4317
DefaultHTTPPort = 4318
+ // DefaultHealthCheckPort is where the collector's health_check extension listens on an
+ // install with the default OTLP ports, and on any configuration written before the port was
+ // recorded (see HealthCheckPort).
+ DefaultHealthCheckPort = 13133
)
// SystemBaseDir is the single source of truth for the system-mode state directory.
@@ -124,10 +128,15 @@ type AutoUpdate struct {
}
type Collector struct {
- BinaryPath string `json:"binary_path,omitempty"`
- ConfigPath string `json:"config_path,omitempty"`
- GRPCPort int `json:"grpc_port"`
- HTTPPort int `json:"http_port"`
+ BinaryPath string `json:"binary_path,omitempty"`
+ ConfigPath string `json:"config_path,omitempty"`
+ GRPCPort int `json:"grpc_port"`
+ HTTPPort int `json:"http_port"`
+ // HealthPort is the collector health_check extension's loopback port. Zero, which is what a
+ // config.json written before the field existed decodes to, means DefaultHealthCheckPort:
+ // that is the port such an install rendered into its collector config. Read it through
+ // HealthCheckPort rather than directly.
+ HealthPort int `json:"health_port,omitempty"`
SpoolPath string `json:"spool_path,omitempty"`
IncludeRuntimeMetrics bool `json:"include_runtime_metrics,omitempty"`
IncludeCodexSpans bool `json:"include_codex_spans,omitempty"`
@@ -192,6 +201,69 @@ func Default(userMode bool, logPath string) Config {
}
}
+// HealthCheckPort is the port the collector's health_check extension listens on for this config.
+//
+// A config with no recorded port predates the field, and every such install rendered the fixed
+// DefaultHealthCheckPort into its collector config, so that is the answer for it; deriving one
+// here instead would point status at a port the running collector never bound.
+func HealthCheckPort(collector Collector) int {
+ if collector.HealthPort > 0 {
+ return collector.HealthPort
+ }
+ return DefaultHealthCheckPort
+}
+
+// DeriveHealthCheckPort picks the health-check port for an install that did not name one.
+//
+// The port moves with the OTLP HTTP port: it is DefaultHealthCheckPort shifted by however far the
+// HTTP port was moved from DefaultHTTPPort. The default install therefore keeps 13133, and a second
+// collector installed on alternate OTLP ports -- a user-mode endpoint beside the system one, which
+// is the case that needs different ports at all -- gets a different health port without being
+// told (4328 gives 13143). The fixed port was why those two could not run together (#447).
+//
+// When that shift leaves the valid range or lands on an OTLP port, the next free-looking neighbour
+// of the HTTP port is used instead. The result is a pure function of the two ports, so install,
+// repair and status agree without consulting anything else.
+func DeriveHealthCheckPort(grpcPort, httpPort int) int {
+ if grpcPort <= 0 {
+ grpcPort = DefaultGRPCPort
+ }
+ if httpPort <= 0 {
+ httpPort = DefaultHTTPPort
+ }
+ candidates := []int{
+ DefaultHealthCheckPort + (httpPort - DefaultHTTPPort),
+ httpPort + 1,
+ httpPort - 1,
+ httpPort + 2,
+ httpPort - 2,
+ }
+ for _, port := range candidates {
+ if validPort(port) && port != grpcPort && port != httpPort {
+ return port
+ }
+ }
+ return DefaultHealthCheckPort
+}
+
+// ValidateCollectorPorts rejects a health-check port the collector could not bind: outside the TCP
+// range, or shared with an OTLP receiver, which would make the collector fail at start with a bind
+// error rather than at install with an explanation.
+func ValidateCollectorPorts(collector Collector) error {
+ health := HealthCheckPort(collector)
+ if !validPort(health) {
+ return fmt.Errorf("collector health-check port %d is out of range; choose a port between 1 and 65535 with --health-port", health)
+ }
+ if health == collector.GRPCPort || health == collector.HTTPPort {
+ return fmt.Errorf("collector health-check port %d is also an OTLP receiver port; choose a different --health-port", health)
+ }
+ return nil
+}
+
+func validPort(port int) bool {
+ return port > 0 && port <= 65535
+}
+
func InventoryDefaults() InventorySettings {
return InventorySettings{
Enabled: true,
diff --git a/cli/beacon/internal/endpoint/config/healthport_test.go b/cli/beacon/internal/endpoint/config/healthport_test.go
new file mode 100644
index 00000000..dd64096e
--- /dev/null
+++ b/cli/beacon/internal/endpoint/config/healthport_test.go
@@ -0,0 +1,120 @@
+package config
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// The default install must keep the port every existing endpoint, doc, and packaging smoke test
+// already expects.
+func TestDeriveHealthCheckPortKeepsTheDefaultForTheDefaultPorts(t *testing.T) {
+ if got := DeriveHealthCheckPort(DefaultGRPCPort, DefaultHTTPPort); got != DefaultHealthCheckPort {
+ t.Fatalf("DeriveHealthCheckPort(defaults) = %d, want %d", got, DefaultHealthCheckPort)
+ }
+ if got := DeriveHealthCheckPort(0, 0); got != DefaultHealthCheckPort {
+ t.Fatalf("DeriveHealthCheckPort(0, 0) = %d, want %d", got, DefaultHealthCheckPort)
+ }
+}
+
+// #447: a user-mode install moved to alternate OTLP ports must get a health port that differs from
+// the system collector's, or the two cannot run together.
+func TestDeriveHealthCheckPortMovesWithTheHTTPPort(t *testing.T) {
+ for _, tc := range []struct{ grpc, http, want int }{
+ {4327, 4328, 13143},
+ {14317, 14318, 23133},
+ {5317, 5318, 14133},
+ } {
+ if got := DeriveHealthCheckPort(tc.grpc, tc.http); got != tc.want {
+ t.Errorf("DeriveHealthCheckPort(%d, %d) = %d, want %d", tc.grpc, tc.http, got, tc.want)
+ }
+ }
+}
+
+// Whatever the OTLP ports, the derived port has to be one the collector can bind next to them.
+func TestDeriveHealthCheckPortIsAlwaysValidAndDistinct(t *testing.T) {
+ for http := 1; http <= 65535; http++ {
+ for _, grpc := range []int{http - 1, http + 1, DefaultGRPCPort, DefaultHealthCheckPort + (http - DefaultHTTPPort)} {
+ if grpc <= 0 || grpc > 65535 || grpc == http {
+ continue
+ }
+ got := DeriveHealthCheckPort(grpc, http)
+ if got <= 0 || got > 65535 || got == grpc || got == http {
+ t.Fatalf("DeriveHealthCheckPort(%d, %d) = %d, want a valid port distinct from both", grpc, http, got)
+ }
+ }
+ }
+}
+
+// Upgrade safety: a config.json written before the field existed rendered 13133 into its collector
+// config, so status and repair must keep reading 13133 for it rather than deriving a new one.
+func TestHealthCheckPortIsTheDefaultForAConfigWithoutTheField(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ path := ConfigPath(true)
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ legacy := `{"user_mode": true, "log_path": "/tmp/runtime.jsonl", "collector": {"grpc_port": 4327, "http_port": 4328}}`
+ if err := os.WriteFile(path, []byte(legacy), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ cfg, err := Load(true)
+ if err != nil {
+ t.Fatalf("Load legacy config: %v", err)
+ }
+ if cfg.Collector.HealthPort != 0 {
+ t.Fatalf("legacy config decoded HealthPort = %d, want 0", cfg.Collector.HealthPort)
+ }
+ if got := HealthCheckPort(cfg.Collector); got != DefaultHealthCheckPort {
+ t.Fatalf("HealthCheckPort(legacy) = %d, want %d", got, DefaultHealthCheckPort)
+ }
+}
+
+func TestHealthPortRoundTripsThroughConfigJSON(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ cfg := Default(true, filepath.Join(home, "runtime.jsonl"))
+ cfg.Collector.HealthPort = 13143
+ path, err := Save(cfg)
+ if err != nil {
+ t.Fatal(err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(data), `"health_port": 13143`) {
+ t.Fatalf("config.json does not record the health port:\n%s", data)
+ }
+ loaded, err := Load(true)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got := HealthCheckPort(loaded.Collector); got != 13143 {
+ t.Fatalf("HealthCheckPort after round trip = %d, want 13143", got)
+ }
+}
+
+func TestValidateCollectorPortsRejectsAHealthPortTheCollectorCannotBind(t *testing.T) {
+ ok := Collector{GRPCPort: 4327, HTTPPort: 4328, HealthPort: 13143}
+ if err := ValidateCollectorPorts(ok); err != nil {
+ t.Fatalf("valid ports rejected: %v", err)
+ }
+ if err := ValidateCollectorPorts(Collector{GRPCPort: 4317, HTTPPort: 4318}); err != nil {
+ t.Fatalf("legacy config (no health port) rejected: %v", err)
+ }
+ for name, c := range map[string]Collector{
+ "same as gRPC": {GRPCPort: 4327, HTTPPort: 4328, HealthPort: 4327},
+ "same as HTTP": {GRPCPort: 4327, HTTPPort: 4328, HealthPort: 4328},
+ "out of range": {GRPCPort: 4327, HTTPPort: 4328, HealthPort: 70000},
+ } {
+ err := ValidateCollectorPorts(c)
+ if err == nil || !strings.Contains(err.Error(), "--health-port") {
+ t.Errorf("%s: ValidateCollectorPorts error = %v, want one naming --health-port", name, err)
+ }
+ }
+}
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
index e330e6e4..894829e2 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
@@ -86,13 +86,13 @@ func lingerCheck() Check {
func checkCollectorHealth(cfg endpointconfig.Config) Check {
status := collector.CheckStatus(cfg)
if status.HealthReady {
- return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: StatusOK, Severity: SeverityInfo, Message: "collector health check is ready", Evidence: "health_check_ready"}
+ return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", status.HealthPort), Status: StatusOK, Severity: SeverityInfo, Message: "collector health check is ready", Evidence: "health_check_ready"}
}
message := status.Message
if message == "" {
message = "collector health check is not ready"
}
- return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", collector.HealthCheckPort), Status: StatusWarn, Severity: SeverityMedium, Message: message, Evidence: "health_check_unavailable"}
+ return Check{Name: "collector_health", Target: fmt.Sprintf("127.0.0.1:%d", status.HealthPort), Status: StatusWarn, Severity: SeverityMedium, Message: message, Evidence: "health_check_unavailable"}
}
func HasFailures(checks []Check) bool {
diff --git a/cli/beacon/internal/endpoint/diagnostics/healthport_test.go b/cli/beacon/internal/endpoint/diagnostics/healthport_test.go
new file mode 100644
index 00000000..b3e9436d
--- /dev/null
+++ b/cli/beacon/internal/endpoint/diagnostics/healthport_test.go
@@ -0,0 +1,40 @@
+package diagnostics
+
+import (
+ "net"
+ "path/filepath"
+ "strconv"
+ "testing"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+// Doctor's collector_health check has to report the port this endpoint's collector binds, not the
+// fixed 13133, or a user-mode endpoint beside the system one is diagnosed against the wrong collector.
+func TestCollectorHealthCheckTargetsTheConfiguredHealthPort(t *testing.T) {
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ port := ln.Addr().(*net.TCPAddr).Port
+ _ = ln.Close()
+ cfg := endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl"))
+ cfg.Collector.HealthPort = port
+
+ check := checkCollectorHealth(cfg)
+
+ if want := "127.0.0.1:" + strconv.Itoa(port); check.Target != want {
+ t.Fatalf("collector_health target = %q, want %q", check.Target, want)
+ }
+}
+
+func TestCollectorHealthCheckTargetsTheDefaultPortForALegacyConfig(t *testing.T) {
+ cfg := endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl"))
+ cfg.Collector.HealthPort = 0
+
+ check := checkCollectorHealth(cfg)
+
+ if check.Target != "127.0.0.1:13133" {
+ t.Fatalf("collector_health target = %q, want 127.0.0.1:13133", check.Target)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/lifecycle/healthport_test.go b/cli/beacon/internal/endpoint/lifecycle/healthport_test.go
new file mode 100644
index 00000000..fb4c3f44
--- /dev/null
+++ b/cli/beacon/internal/endpoint/lifecycle/healthport_test.go
@@ -0,0 +1,271 @@
+package lifecycle
+
+import (
+ "net"
+ "net/http"
+ "os"
+ "path/filepath"
+ "runtime"
+ "strconv"
+ "strings"
+ "testing"
+ "time"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/service"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+func shortTimeouts(t *testing.T) {
+ t.Helper()
+ oldReady, oldRelease := collectorReadyTimeout, portReleaseTimeout
+ collectorReadyTimeout, portReleaseTimeout = 1500*time.Millisecond, 100*time.Millisecond
+ t.Cleanup(func() { collectorReadyTimeout, portReleaseTimeout = oldReady, oldRelease })
+}
+
+// No-regression: the default install, which is what a package upgrade re-runs, keeps 13133.
+func TestBuildConfigKeepsTheDefaultHealthPortForTheDefaultOTLPPorts(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ cfg := buildConfig(InstallOptions{UserMode: true, GRPCPort: endpointconfig.DefaultGRPCPort, HTTPPort: endpointconfig.DefaultHTTPPort})
+ if cfg.Collector.HealthPort != endpointconfig.DefaultHealthCheckPort {
+ t.Fatalf("HealthPort = %d, want %d", cfg.Collector.HealthPort, endpointconfig.DefaultHealthCheckPort)
+ }
+}
+
+// #447: `install --user --otlp-grpc-port 4327 --otlp-http-port 4328` beside a system collector
+// must not be handed the system collector's health port.
+func TestBuildConfigMovesTheHealthPortWithAlternateOTLPPorts(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ cfg := buildConfig(InstallOptions{UserMode: true, GRPCPort: 4327, HTTPPort: 4328})
+ if cfg.Collector.HealthPort != 13143 {
+ t.Fatalf("HealthPort = %d, want 13143", cfg.Collector.HealthPort)
+ }
+}
+
+// A health port recorded by an earlier install on other OTLP ports must not survive a reinstall
+// that moves them; it is derived from this install's ports, like the OTLP ports themselves.
+func TestBuildConfigDerivesTheHealthPortFromThisInstallsPorts(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ previous := endpointconfig.Default(true, filepath.Join(home, "runtime.jsonl"))
+ previous.Collector.GRPCPort, previous.Collector.HTTPPort, previous.Collector.HealthPort = 4327, 4328, 13143
+ if _, err := endpointconfig.Save(previous); err != nil {
+ t.Fatal(err)
+ }
+ cfg := buildConfig(InstallOptions{UserMode: true, GRPCPort: 4337, HTTPPort: 4338})
+ if cfg.Collector.HealthPort != 13153 {
+ t.Fatalf("HealthPort = %d, want 13153 derived from the new HTTP port", cfg.Collector.HealthPort)
+ }
+}
+
+func TestBuildConfigHonorsAnExplicitHealthPort(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ cfg := buildConfig(InstallOptions{UserMode: true, GRPCPort: 4327, HTTPPort: 4328, HealthPort: 23456})
+ if cfg.Collector.HealthPort != 23456 {
+ t.Fatalf("HealthPort = %d, want the explicit 23456", cfg.Collector.HealthPort)
+ }
+}
+
+func TestPreflightRejectsAHealthPortThatIsAlsoAnOTLPPort(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ cfg := endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl"))
+ cfg.Collector.GRPCPort = freePort(t)
+ cfg.Collector.HTTPPort = freePort(t)
+ cfg.Collector.HealthPort = cfg.Collector.HTTPPort
+
+ // Rejected even for --no-start: the written collector config could never start.
+ err := preflight(cfg, false, service.KindSupervised)
+ if err == nil || !strings.Contains(err.Error(), "--health-port") {
+ t.Fatalf("preflight error = %v, want a --health-port collision error", err)
+ }
+}
+
+// #447: the system collector holds the health port, the user install's OTLP ports are free. The
+// install must stop before writing anything, and say which port is the problem.
+func TestPreflightRejectsAHealthPortHeldByAnotherCollector(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ shortTimeouts(t)
+ held, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer held.Close()
+ cfg := endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl"))
+ cfg.Collector.GRPCPort = freePort(t)
+ cfg.Collector.HTTPPort = freePort(t)
+ cfg.Collector.HealthPort = held.Addr().(*net.TCPAddr).Port
+
+ err = preflight(cfg, true, service.KindSupervised)
+
+ if err == nil {
+ t.Fatal("preflight passed with the health port held by another process")
+ }
+ msg := err.Error()
+ if !strings.Contains(msg, "health-check port "+strconv.Itoa(cfg.Collector.HealthPort)) || !strings.Contains(msg, "--health-port") {
+ t.Fatalf("preflight error = %q, want it to name the health-check port and --health-port", msg)
+ }
+ if strings.Contains(msg, "OTLP gRPC port") || strings.Contains(msg, "OTLP HTTP port") {
+ t.Fatalf("preflight error = %q blames the OTLP ports, which are free", msg)
+ }
+}
+
+// No-regression: a reinstall that moves only the gRPC port keeps the derived health port, which this
+// mode's own running collector still holds until the install restarts it. That is not a conflict.
+func TestPreflightAllowsAHealthPortHeldByThisModesRunningCollector(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ shortTimeouts(t)
+ held, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer held.Close()
+ writeRunningSupervisedState(t)
+ cfg := endpointconfig.Default(true, filepath.Join(home, "runtime.jsonl"))
+ cfg.Collector.GRPCPort = freePort(t)
+ cfg.Collector.HTTPPort = freePort(t)
+ cfg.Collector.HealthPort = held.Addr().(*net.TCPAddr).Port
+
+ if err := preflight(cfg, true, service.KindSupervised); err != nil {
+ t.Fatalf("preflight rejected a health port held by this mode's own running collector: %v", err)
+ }
+}
+
+// Upgrade safety: a legacy user config on alternate OTLP ports ran its collector on 13133, and the
+// reinstall a package upgrade runs moves it to the derived port. Its own running collector holds the
+// OTLP ports and answers health on the old port; preflight must recognise it rather than wait out
+// the timeout and blame the OTLP ports.
+func TestPreflightRecognisesItsOwnCollectorWhileTheHealthPortMoves(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ shortTimeouts(t)
+ writeRunningSupervisedState(t)
+ grpcLn, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer grpcLn.Close()
+ httpLn, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer httpLn.Close()
+ oldHealth := serveHealthOK(t)
+
+ previous := endpointconfig.Default(true, filepath.Join(home, "runtime.jsonl"))
+ previous.Collector.GRPCPort = grpcLn.Addr().(*net.TCPAddr).Port
+ previous.Collector.HTTPPort = httpLn.Addr().(*net.TCPAddr).Port
+ previous.Collector.HealthPort = oldHealth
+ if _, err := endpointconfig.Save(previous); err != nil {
+ t.Fatal(err)
+ }
+ cfg := previous
+ cfg.Collector.HealthPort = freePort(t)
+
+ if err := preflight(cfg, true, service.KindSupervised); err != nil {
+ t.Fatalf("preflight rejected a reinstall over this mode's own collector: %v", err)
+ }
+}
+
+// The end-to-end #447 symptom: a collector that exits on start used to fail the install with only
+// "Collector ports are not listening". The install error has to carry the collector's own reason.
+func TestInstallErrorQuotesTheCollectorsOwnStartFailure(t *testing.T) {
+ if runtime.GOOS == "windows" {
+ t.Skip("the stand-in collector is a shell script")
+ }
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ shortTimeouts(t)
+ installFakeInventoryJob(t, false)
+
+ bindFailure := "Error: failed to start extensions: failed to bind to address 127.0.0.1:13143: listen tcp 127.0.0.1:13143: bind: address already in use"
+ collectorPath := filepath.Join(home, "bin", "beacon-otelcol")
+ if err := os.MkdirAll(filepath.Dir(collectorPath), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ script := "#!/bin/sh\necho 'info starting collector' >&2\necho '" + bindFailure + "' >&2\nexit 1\n"
+ if err := os.WriteFile(collectorPath, []byte(script), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ // A failure left by an earlier run in the same appended-to log must not be quoted.
+ logPath := service.Manager{UserMode: true, Kind: service.KindSupervised}.CollectorLog().Path
+ if err := os.MkdirAll(filepath.Dir(logPath), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(logPath, []byte("Error: stale failure from an earlier run\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+
+ _, err := Install(InstallOptions{
+ UserMode: true,
+ LogPath: filepath.Join(home, ".beacon", "endpoint", "logs", "runtime.jsonl"),
+ Harnesses: []string{},
+ GRPCPort: freePort(t),
+ HTTPPort: freePort(t),
+ HealthPort: freePort(t),
+ CollectorPath: collectorPath,
+ StartService: true,
+ ServiceKind: service.KindSupervised,
+ })
+
+ if err == nil {
+ t.Fatal("Install succeeded with a collector that exits on start")
+ }
+ msg := err.Error()
+ if !strings.Contains(msg, bindFailure) {
+ t.Fatalf("install error = %q, want it to quote the collector's bind failure", msg)
+ }
+ if strings.Contains(msg, "stale failure") {
+ t.Fatalf("install error = %q quotes a line from an earlier run", msg)
+ }
+ if !strings.Contains(msg, logPath) {
+ t.Fatalf("install error = %q, want it to name the log %s", msg, logPath)
+ }
+}
+
+func TestCollectorStartErrorPointsAtTheJournalWhenThereIsNoFile(t *testing.T) {
+ base := os.ErrDeadlineExceeded
+ err := collectorStartError(base, service.CollectorLog{Hint: "journalctl --user -u beacon-collector.service"}, 0)
+ if !strings.Contains(err.Error(), "journalctl --user -u beacon-collector.service") {
+ t.Fatalf("error = %q, want the journal hint", err)
+ }
+ if got := collectorStartError(base, service.CollectorLog{}, 0); got != base {
+ t.Fatalf("error with no log location = %v, want the original", got)
+ }
+}
+
+// writeRunningSupervisedState records this test process as the user-mode supervised collector, so
+// the backend reports it loaded and running without starting anything.
+func writeRunningSupervisedState(t *testing.T) {
+ t.Helper()
+ pidfile, err := service.Manager{UserMode: true, Kind: service.KindSupervised}.UnitPath()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := os.MkdirAll(filepath.Dir(pidfile), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ state := `{"pid": ` + strconv.Itoa(os.Getpid()) + `, "program": "/bin/beacon-otelcol", "config_path": "/tmp/otelcol.yaml"}`
+ if err := os.WriteFile(pidfile, []byte(state), 0o644); err != nil {
+ t.Fatal(err)
+ }
+}
+
+func serveHealthOK(t *testing.T) int {
+ t.Helper()
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ server := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusOK) })}
+ done := make(chan struct{})
+ go func() {
+ _ = server.Serve(ln)
+ close(done)
+ }()
+ t.Cleanup(func() {
+ _ = server.Close()
+ <-done
+ })
+ return ln.Addr().(*net.TCPAddr).Port
+}
diff --git a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
index 141cf469..ef4ff901 100644
--- a/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
+++ b/cli/beacon/internal/endpoint/lifecycle/lifecycle.go
@@ -23,6 +23,12 @@ import (
var (
writeCollectorConfig = endpointcollector.WriteConfig
+ // collectorReadyTimeout is how long Install waits for a started collector to answer on all of
+ // its ports. A variable so tests of a collector that exits on start need not wait it out.
+ collectorReadyTimeout = 10 * time.Second
+ // portReleaseTimeout is how long preflight waits for a busy collector port to be released,
+ // which covers a collector that is still shutting down from a previous uninstall or repair.
+ portReleaseTimeout = 10 * time.Second
saveEndpointConfig = endpointconfig.Save
appendInstallEvent = writer.AppendEvent
detectUpdaterInstall = selfupdate.DetectInstall
@@ -180,11 +186,14 @@ func inventoryHeartbeatStatus(requestedUserMode bool, logPath string) InventoryH
}
type InstallOptions struct {
- UserMode bool
- LogPath string
- Harnesses []string
- GRPCPort int
- HTTPPort int
+ UserMode bool
+ LogPath string
+ Harnesses []string
+ GRPCPort int
+ HTTPPort int
+ // HealthPort is the collector health_check port. Zero derives it from the OTLP ports
+ // (endpointconfig.DeriveHealthCheckPort), which keeps 13133 for the default ports.
+ HealthPort int
CollectorPath string
StartService bool
IncludeRuntimeMetrics bool
@@ -501,6 +510,10 @@ func Install(opts InstallOptions) (InstallResult, error) {
// the two decisions disagreeing about the state they are reasoning about.
wasRunning := manager.Status().Running
tx.ServiceWasRunning = wasRunning
+ // Note where the collector's log ends before starting it, so a failed start can quote
+ // what this start wrote rather than whatever an earlier run left in the same file.
+ collectorLog := manager.CollectorLog()
+ collectorLogOffset := endpointcollector.LogSize(collectorLog.Path)
if wasRunning {
if err := manager.Restart(); err != nil {
tx.Rollback(manifest)
@@ -524,9 +537,9 @@ func Install(opts InstallOptions) (InstallResult, error) {
manifest.LingerEnabled = lingerOutcome.Enabled
manifest.LingerDetail = lingerOutcome.Detail
}
- if err := endpointcollector.WaitUntilReady(cfg, 10*time.Second); err != nil {
+ if err := endpointcollector.WaitUntilReady(cfg, collectorReadyTimeout); err != nil {
tx.Rollback(manifest)
- return InstallResult{}, err
+ return InstallResult{}, collectorStartError(err, collectorLog, collectorLogOffset)
}
}
tx.Track(manifestPath(cfg.UserMode))
@@ -861,6 +874,14 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {
if opts.HTTPPort != 0 {
cfg.Collector.HTTPPort = opts.HTTPPort
}
+ // Derived afresh from the ports in effect rather than carried from the existing config, the
+ // same way the OTLP ports themselves are taken from this install's options: an install that
+ // moves the OTLP ports has to move the health port with them, or a user-mode collector moved
+ // off the system one's ports would still collide with it on 13133.
+ cfg.Collector.HealthPort = opts.HealthPort
+ if cfg.Collector.HealthPort == 0 {
+ cfg.Collector.HealthPort = endpointconfig.DeriveHealthCheckPort(cfg.Collector.GRPCPort, cfg.Collector.HTTPPort)
+ }
cfg.Collector.BinaryPath = opts.CollectorPath
cfg.Collector.IncludeRuntimeMetrics = opts.IncludeRuntimeMetrics
cfg.Collector.IncludeCodexSpans = opts.IncludeCodexSpans
@@ -882,6 +903,26 @@ func buildConfig(opts InstallOptions) endpointconfig.Config {
return cfg
}
+// collectorStartError adds the collector's own explanation to a readiness failure.
+//
+// The readiness check can only see the symptom -- ports not listening, health check not ready --
+// and the symptom points at the wrong thing when the collector exited on start: a user-mode
+// collector killed by a health-check port the system collector held was reported as "Collector
+// ports are not listening", which blames the OTLP ports (#447). The collector's last error line
+// names the real cause.
+func collectorStartError(err error, log service.CollectorLog, offset int64) error {
+ if log.Path != "" {
+ if line := endpointcollector.LogErrorSince(log.Path, offset); line != "" {
+ return fmt.Errorf("%w; collector reported: %s (full log: %s)", err, line, log.Path)
+ }
+ return fmt.Errorf("%w; the collector wrote nothing new to %s", err, log.Path)
+ }
+ if log.Hint != "" {
+ return fmt.Errorf("%w; for the collector's own error see %s", err, log.Hint)
+ }
+ return err
+}
+
func installDestination(cfg endpointconfig.Config) *schema.DestinationInfo {
destination := &schema.DestinationInfo{Type: "local_jsonl", Mode: "file", Status: "configured"}
if cfg.Destinations != nil && cfg.Destinations.SplunkHEC != nil && cfg.Destinations.SplunkHEC.Enabled {
@@ -982,32 +1023,63 @@ func preflight(cfg endpointconfig.Config, startService bool, kind service.Kind)
return fmt.Errorf("system install needs elevated privileges; %s, or omit --system for the default user install",
SystemPrivilegeHint())
}
+ if err := endpointconfig.ValidateCollectorPorts(cfg.Collector); err != nil {
+ return err
+ }
if !startService {
return nil
}
+ healthPort := endpointconfig.HealthCheckPort(cfg.Collector)
grpcAvailable := endpointcollector.PortAvailable(cfg.Collector.GRPCPort)
httpAvailable := endpointcollector.PortAvailable(cfg.Collector.HTTPPort)
- if grpcAvailable && httpAvailable {
+ healthAvailable := endpointcollector.PortAvailable(healthPort)
+ if grpcAvailable && httpAvailable && healthAvailable {
return nil
}
- if existingCollectorReady(cfg, kind) {
+ own := service.Manager{UserMode: cfg.UserMode, Kind: kind}.Status()
+ if own.Loaded && existingCollectorReady(cfg) {
return nil
}
- if err := endpointcollector.WaitForPortsAvailable(cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, 10*time.Second); err != nil {
- return fmt.Errorf("%w; if this persists, another process may be using Beacon's OTLP receiver ports", err)
+ // This mode's own running collector may be what holds the health port: a reinstall that moves
+ // only the gRPC port keeps the same derived health port, and the restart that follows releases
+ // it. Only a health port held while this mode's collector is not running -- by the system
+ // collector, beside a first user-mode install -- is a conflict worth failing on here.
+ if grpcAvailable && httpAvailable && own.Running {
+ return nil
+ }
+ if err := endpointcollector.WaitForPortsAvailable(cfg.Collector.GRPCPort, cfg.Collector.HTTPPort, healthPort, portReleaseTimeout); err != nil {
+ return fmt.Errorf("%w; if this persists, another process may be using the ports Beacon's collector needs", err)
}
return nil
}
-// The kind is threaded through rather than re-detected: preflight already honours an explicit
-// --service=, and auto-detecting here would consult a different backend than the one the install
-// is about to use.
-func existingCollectorReady(cfg endpointconfig.Config, kind service.Kind) bool {
- if !(service.Manager{UserMode: cfg.UserMode, Kind: kind}).Status().Loaded {
+// existingCollectorReady reports whether this mode's loaded collector is already serving the OTLP
+// ports this install asks for, in which case the busy ports are its own and the install's restart
+// releases them.
+//
+// Its health endpoint is looked for on the port this install will use and, failing that, on the one
+// recorded by the install that started it. The two differ whenever the health port moves under a
+// running collector -- a legacy config with alternate OTLP ports, which ran on 13133, being
+// reinstalled onto its derived port, or an explicit --health-port change -- and probing only the
+// new port would take the endpoint's own collector for a stranger holding its ports.
+//
+// The caller has already checked that the service is loaded: the kind is threaded through rather
+// than re-detected, since preflight honours an explicit --service= and auto-detecting would consult
+// a different backend than the one the install is about to use.
+func existingCollectorReady(cfg endpointconfig.Config) bool {
+ status := endpointcollector.CheckStatus(cfg)
+ if !status.GRPCReady || !status.HTTPReady {
return false
}
- status := endpointcollector.CheckStatus(cfg)
- return status.GRPCReady && status.HTTPReady && status.HealthReady
+ if status.HealthReady {
+ return true
+ }
+ existing, err := endpointconfig.Load(cfg.UserMode)
+ if err != nil || endpointconfig.HealthCheckPort(existing.Collector) == status.HealthPort {
+ return false
+ }
+ existing.Collector.GRPCPort, existing.Collector.HTTPPort = cfg.Collector.GRPCPort, cfg.Collector.HTTPPort
+ return endpointcollector.CheckStatus(existing).HealthReady
}
func configureHarnesses(cfg endpointconfig.Config) ([]string, error) {
diff --git a/cli/beacon/internal/endpoint/service/collectorlog_test.go b/cli/beacon/internal/endpoint/service/collectorlog_test.go
new file mode 100644
index 00000000..0b827666
--- /dev/null
+++ b/cli/beacon/internal/endpoint/service/collectorlog_test.go
@@ -0,0 +1,46 @@
+package service
+
+import (
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// A failed install can only quote the collector's reason if it reads the file the backend actually
+// sends stderr to -- the plist's StandardErrorPath and the supervised log -- or, where there is no
+// file, tells the reader where to look.
+func TestCollectorLogNamesWhereEachBackendSendsStderr(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+
+ launchd := Manager{UserMode: true, Kind: KindLaunchd}.CollectorLog()
+ if launchd.Path != "/tmp/"+UserLabel+".err" {
+ t.Errorf("launchd user log = %q, want /tmp/%s.err", launchd.Path, UserLabel)
+ }
+ if !strings.Contains(plist(UserLabel, "/bin/otelcol", "/tmp/otelcol.yaml"), "<string>"+launchd.Path+"</string>") {
+ t.Errorf("launchd log path %q is not the plist's StandardErrorPath", launchd.Path)
+ }
+ if got := (Manager{UserMode: false, Kind: KindLaunchd}).CollectorLog().Path; got != "/tmp/"+SystemLabel+".err" {
+ t.Errorf("launchd system log = %q, want /tmp/%s.err", got, SystemLabel)
+ }
+
+ supervised := Manager{UserMode: true, Kind: KindSupervised}.CollectorLog()
+ if want := filepath.Join(home, ".beacon", "endpoint", "collector.out"); supervised.Path != want {
+ t.Errorf("supervised log = %q, want %q", supervised.Path, want)
+ }
+
+ systemd := Manager{UserMode: true, Kind: KindSystemd}.CollectorLog()
+ if systemd.Path != "" || !strings.Contains(systemd.Hint, "journalctl --user -u "+SystemdUserUnit) {
+ t.Errorf("systemd user log = %+v, want a journalctl --user hint", systemd)
+ }
+ if hint := (Manager{UserMode: false, Kind: KindSystemd}).CollectorLog().Hint; strings.Contains(hint, "--user") || !strings.Contains(hint, SystemdSystemUnit) {
+ t.Errorf("systemd system hint = %q", hint)
+ }
+
+ windows := Manager{UserMode: false, Kind: KindWindowsService}.CollectorLog()
+ if windows.Path != "" || !strings.Contains(windows.Hint, WindowsServiceName) {
+ t.Errorf("windows system log = %+v, want an event-log hint naming %s", windows, WindowsServiceName)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/service/launchd.go b/cli/beacon/internal/endpoint/service/launchd.go
index a5c37fd1..11ce3c1c 100644
--- a/cli/beacon/internal/endpoint/service/launchd.go
+++ b/cli/beacon/internal/endpoint/service/launchd.go
@@ -249,6 +249,12 @@ func serviceDomain(userMode bool) string {
return "system"
}
+// launchdStderrPath is the collector job's StandardErrorPath, kept beside the plist template that
+// writes it so the two cannot drift.
+func launchdStderrPath(label string) string {
+ return "/tmp/" + label + ".err"
+}
+
func plist(label, program, configPath string) string {
return fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -269,8 +275,8 @@ func plist(label, program, configPath string) string {
<key>StandardOutPath</key>
<string>/tmp/%s.out</string>
<key>StandardErrorPath</key>
- <string>/tmp/%s.err</string>
+ <string>%s</string>
</dict>
</plist>
-`, label, program, configPath, label, label)
+`, label, program, configPath, label, launchdStderrPath(label))
}
diff --git a/cli/beacon/internal/endpoint/service/service.go b/cli/beacon/internal/endpoint/service/service.go
index de62fa75..0aa7b8df 100644
--- a/cli/beacon/internal/endpoint/service/service.go
+++ b/cli/beacon/internal/endpoint/service/service.go
@@ -311,6 +311,39 @@ func (m Manager) Status() Status {
return s
}
+// CollectorLog says where the collector's stderr goes under this backend, so a collector that
+// exits during an install's readiness wait can be reported with its own reason rather than a
+// generic "not listening" (#447).
+//
+// Path is set when the output lands in a file Beacon can read back: launchd's StandardErrorPath
+// and the supervised backend's log. Hint says where to look for the backends whose output is not a
+// file: a journalctl command for systemd, and the event log for the Windows service, whose SCM
+// captures no stdout at all.
+type CollectorLog struct {
+ Path string
+ Hint string
+}
+
+// CollectorLog reports where the collector's own error output can be found.
+func (m Manager) CollectorLog() CollectorLog {
+ switch b := m.backend().(type) {
+ case launchdBackend:
+ return CollectorLog{Path: launchdStderrPath(b.label(m.UserMode))}
+ case supervisedBackend:
+ return CollectorLog{Path: supervisedLogPath(m.UserMode)}
+ case systemdBackend:
+ scope := ""
+ if m.UserMode {
+ scope = "--user "
+ }
+ return CollectorLog{Hint: fmt.Sprintf("journalctl %s-u %s -n 50 --no-pager", scope, b.label(m.UserMode))}
+ case windowsBackend:
+ return CollectorLog{Hint: "the Windows Application event log, source " + WindowsServiceName}
+ default:
+ return CollectorLog{}
+ }
+}
+
// stateDir is where service-owned runtime state (pidfiles) lives. Derived from the endpoint
// config so it tracks the single SystemBaseDir definition rather than duplicating it.
func stateDir(userMode bool) string { return endpointconfig.BaseDir(userMode) }
diff --git a/cli/beacon/internal/endpoint/service/supervised.go b/cli/beacon/internal/endpoint/service/supervised.go
index 806c8006..25134ce8 100644
--- a/cli/beacon/internal/endpoint/service/supervised.go
+++ b/cli/beacon/internal/endpoint/service/supervised.go
@@ -124,7 +124,7 @@ func (b supervisedBackend) load(userMode bool) error {
// started it. Without this, the collector would die with the shell that ran install.
cmd.SysProcAttr = detachAttrs()
// Logs go to a file next to the runtime log, since there is no journal here.
- logPath := filepath.Join(stateDir(userMode), "collector.out")
+ logPath := supervisedLogPath(userMode)
if f, ferr := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644); ferr == nil {
cmd.Stdout = f
cmd.Stderr = f
@@ -233,3 +233,8 @@ func processAlive(pid int) bool {
}
return pidAlive(pid)
}
+
+// supervisedLogPath is the file a supervised collector's stdout and stderr are appended to.
+func supervisedLogPath(userMode bool) string {
+ return filepath.Join(stateDir(userMode), "collector.out")
+}
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index 40e27145..9ffb31f9 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -29,6 +29,7 @@ The `claude` harness writes both Claude Code's OpenTelemetry settings and its us
| `--harness <selection>` | Harnesses to configure. Defaults to `auto`, which installs every detected integration Beacon can configure and reports detected manual or poll-only integrations. Use `all` to force every installable integration, or pass an exact comma-separated list such as `claude,codex,cursor,kimi`. DeepSeek Harness and Kimi Code are user-level only. An explicit list preserves exact-selection behavior |
| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` |
| `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` |
+| `--health-port <port>` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that is changed (HTTP port `4328` gives `13143`), so a second collector on alternate OTLP ports does not collide with the first |
| `--collector <path>` | Path to a `beacon-otelcol` binary |
| `--no-start` | Write files without starting the collector service |
| `--no-browser` | During interactive setup, print the sign-in URL instead of opening a browser. Useful where no browser can be opened, though the URL still has to be opened on this machine |
@@ -202,9 +203,17 @@ beacon endpoint hooks install --harness grok --level project
System-mode install (`--system`) is supported on macOS and on Linux distributions that use systemd. Omit `--system` for the default non-root local install. GitHub Copilot CLI and Factory Droid OTLP use launch-environment settings rather tha Beacon-managed shell-profile edits.
</Note>
-## Known limitations
+## Running user and system mode together
-A user-mode collector cannot run beside a system-mode one on the same machine. The collector health-check port (`127.0.0.1:13133`) is fixed, so the second collector cannot bind it; the install fails with `Collector ports are not listening` and rolls back the endpoint files it wrote. Either write the user-mode files without starting the service (`beacon endpoint install --user --no-start`) or uninstall the system endpoint first (`sudo beacon endpoint uninstall --system`). Tracked as [GitHub issue #447](https://github.com/asymptote-labs/agent-beacon/issues/447).
+A user-mode collector can run beside a system-mode one on the same machine when the two use different ports. Give the user install its own OTLP ports; its health-check port moves with them:
+
+```bash title="Install a user-mode endpoint beside the system one"
+beacon endpoint install --user --otlp-grpc-port 4327 --otlp-http-port 4328
+```
+
+That collector listens on `127.0.0.1:4327`, `127.0.0.1:4328`, and health check `127.0.0.1:13143`. Pass `--health-port` to choose the health-check port yourself. The port is recorded as `collector.health_port` in `config.json`, and `beacon endpoint status` checks the recorded port. A config written before the field existed has no `health_port` and keeps using `13133`.
+
+If a port the collector needs is already taken, the install stops before it writes anything and names that port. If the collector starts but exits before it is ready, the install error quotes the collector's last error line and gives the path of its log, then rolls back.
## Related
diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdx
index b4e937e1..443c18d6 100644
--- a/docs/cli/endpoint-paths.mdx
+++ b/docs/cli/endpoint-paths.mdx
@@ -21,6 +21,8 @@ Beacon manages different paths depending on whether you install in user mode or
| OTLP HTTP | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` | `127.0.0.1:4318` |
| Collector health check | `127.0.0.1:13133` | `127.0.0.1:13133` | `127.0.0.1:13133` | `127.0.0.1:13133` |
+These are the default ports. `--otlp-grpc-port`, `--otlp-http-port`, and `--health-port` change them per install. When `--otlp-http-port` changes and no `--health-port` is given, the health-check port moves by the same amount, so a user-mode collector on alternate ports can run beside the system one. The ports in use are recorded under `collector` in `config.json`.
+
On Windows the system log directory sits under the base directory rather than in a separate location, because there is no `/var/log` equivalent. `%ProgramData%` and `%ProgramFiles%` are read from the environment rather than hardcoded, so a relocated or localized install is found rather than missed.
## Service definitions
diff --git a/docs/cli/endpoint-repair.mdx b/docs/cli/endpoint-repair.mdx
index aded2a6a..4657b9d9 100644
--- a/docs/cli/endpoint-repair.mdx
+++ b/docs/cli/endpoint-repair.mdx
@@ -25,6 +25,7 @@ During repair, Beacon removes the existing managed service before reinstalling i
| `--harness <selection>` | Harnesses to configure. Defaults to `auto`, which repairs every detected integration Beacon can configure. Use `all` to force every installable integration, or pass an exact comma-separated list such as `claude,codex,cursor,kimi`. DeepSeek Harness and Kimi Code are user-level only |
| `--otlp-grpc-port <port>` | Local OTLP gRPC port. Defaults to `4317` |
| `--otlp-http-port <port>` | Local OTLP HTTP port. Defaults to `4318` |
+| `--health-port <port>` | Local collector health-check port. Defaults to `13133`, moved by the same amount as `--otlp-http-port` when that is changed (HTTP port `4328` gives `13143`), so a second collector on alternate OTLP ports does not collide with the first |
| `--collector <path>` | Path to a `beacon-otelcol` binary |
| `--no-start` | Write files without starting the collector service |
| `--service <kind>` | Service manager to use: `auto` (default), `launchd`, `systemd`, or `none` for a supervised collector process |
diff --git a/docs/support/troubleshooting.mdx b/docs/support/troubleshooting.mdx
index 6a358ccf..cc58ef85 100644
--- a/docs/support/troubleshooting.mdx
+++ b/docs/support/troubleshooting.mdx
@@ -39,7 +39,7 @@ description: "Solutions for common issues when setting up and using Beacon."
After uninstalling hooks, restart the affected agent or IDE so new sessions pick up the updated hook configuration. See the [hook command docs](/cli/hooks#beacon-endpoint-hooks-uninstall) for supported harness names and flags.
</Accordion>
<Accordion title="beacon endpoint install fails with Collector ports are not listening">
- A user-mode collector cannot run beside a system-mode one, because the collector health-check port `127.0.0.1:13133` is fixed, so the install rolls back; run `beacon endpoint install --user --no-start` or uninstall the system endpoint first. Tracked as [GitHub issue #447](https://github.com/asymptote-labs/agent-beacon/issues/447).
+ The collector did not start listening, and the install rolled back. The error goes on to quote the collector's own last error line and the path of its log. On systemd and Windows it names where to look instead. A bind error there (`address already in use`) means another process, often a second Beacon collector, holds one of the ports. To run a user-mode endpoint beside a system-mode one, give it alternate OTLP ports, for example `beacon endpoint install --user --otlp-grpc-port 4327 --otlp-http-port 4328`. Its health-check port moves with them, or you can set one with `--health-port`. See [running user and system mode together](/cli/endpoint-install#running-user-and-system-mode-together).
</Accordion>
<Accordion title="Endpoint package self-update is not running">
For signed macOS package installs, self-update is off by default. Check the