The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
docs(kandji): when another tool rewrites the OTLP settings (#1177)
Shukan Shaha2c3c8070edf
diff --git a/docs/guides/kandji-otlp-forward-mdm.mdx b/docs/guides/kandji-otlp-forward-mdm.mdxindex b0510d51..ba4e076d 100644--- a/docs/guides/kandji-otlp-forward-mdm.mdx+++ b/docs/guides/kandji-otlp-forward-mdm.mdx@@ -87,7 +87,7 @@ How you rolled out the existing backend decides what to change. Find the one tha- Set `OTEL_EXPORTER_OTLP_ENDPOINT` to `http://127.0.0.1:4317` and `OTEL_EXPORTER_OTLP_PROTOCOL` to `grpc`.- Remove `OTEL_EXPORTER_OTLP_HEADERS`, every `OTEL_EXPORTER_OTLP_{LOGS,METRICS,TRACES}_ENDPOINT` and `_HEADERS`, and `BETA_TRACING_ENDPOINT`. The backend's credentials move to the forward in Step 5. Left in place, they would be sent to the local collector instead.-**Scripts or profiles that write `~/.claude/settings.json` or `~/.codex/config.toml`.** Beacon rewrites the OTLP settings in both files on every install, upgrade and repair, and replaces Codex's whole `[otel]` table. Retire or unscope the Kandji item that writes the backend's OTLP settings to those files; otherwise it and Beacon overwrite each other on every run.+**Scripts or profiles that write `~/.claude/settings.json` or `~/.codex/config.toml`.** Beacon rewrites the OTLP settings in both files on every install, upgrade and repair, and replaces Codex's whole `[otel]` table. Retire or unscope the Kandji item that writes the backend's OTLP settings to those files; otherwise it and Beacon overwrite each other on every run. If the backend's own agent rewrites them and cannot be turned off, see [When another tool rewrites the OTLP settings](#when-another-tool-rewrites-the-otlp-settings).## Step 2: prepare Google Cloud@@ -319,7 +319,35 @@ The GCS helper (`repair-hooks-and-forwarder.sh`, under `/opt/beacon/jamf` for co- writes and validates `/Library/Application Support/Beacon/Forwarders/gcs-vector.toml` and starts `com.beacon.endpoint.gcs-forwarder`, which uploads the runtime log under `<prefix>/runtime/` and the inventory log under `<prefix>/inventory/`;- repairs the endpoint and installs Claude Code hooks for the logged-in user, keeping the forward from step 1.-Runtime upload starts at the beginning of the log (`BEACON_VECTOR_READ_FROM=beginning`), so the 30-day session backfill the package install wrote reaches GCS as well as everything after it. This applies only the first time the forwarder starts; after that Vector resumes from its checkpoint, so re-running the script uploads nothing twice. Set it to `end` to upload only what is written after the forwarder starts. Inventory always starts at the beginning so the first snapshot is not missed. When nobody is logged in, the forwarder is configured but the hook step fails, so the script reports a failure until a user logs in and the next run completes.+Runtime upload starts at the beginning of the active log (`BEACON_VECTOR_READ_FROM=beginning`), so whatever part of the package install's 30-day session backfill is still in `runtime.jsonl` reaches GCS, as does everything after it. The forwarder reads only the active log, not its numbered archives, and the log rotates at 10 MiB while a backfill can write up to 24 MiB, so on a Mac with a lot of history the oldest backfilled sessions may already have rotated out by the time Step 6 runs. This applies only the first time the forwarder starts; after that Vector resumes from its checkpoint, so re-running the script uploads nothing twice. Set it to `end` to upload only what is written after the forwarder starts. Inventory always starts at the beginning so the first snapshot is not missed. When nobody is logged in, the forwarder is configured but the hook step fails, so the script reports a failure until a user logs in and the next run completes.++## When another tool rewrites the OTLP settings++Some backends run their own agent on the Mac that points Claude Code's and Codex's OTLP settings back at the backend every few minutes. Beacon and that agent then overwrite each other: the Step 6 audit fails on every run, and its remediation points the settings back at the collector until the other agent rewrites them.++Let the other agent keep the OTLP settings. Beacon still records most of what the agents do without them:++- Beacon's hooks record Claude Code sessions, prompts, tool calls, and commands as they happen. Codex's hooks record only the session start and the final reply. The audit below reinstalls the hooks if the other agent removes them.+- The [scheduled session sync](/cli/endpoint-install#scheduled-session-sync), which Steps 5 and 6 turn on with `--session-sync`, reads Claude Code's and Codex's session files every 15 minutes. It adds Claude Code's per-request token usage and complete replies, and Codex's prompts, tool calls, and token usage, up to 15 minutes after the agent writes them.++Some records exist only in the OTLP export, so they stop reaching Beacon, and GCS, while the other agent owns the settings: Claude Code's runtime-reported cost, Claude Code's tool approval decisions, and Codex's approval events. The other backend still receives them.++Keep the OTLP forward. A package upgrade, and the remediation when it runs, point the settings at the collector until the other agent rewrites them, and the forward keeps the backend's data flowing in that window.++Then have the audit check the session sync and the hooks instead of where the settings point. Replace the end of the Step 6 audit script, from the `if [ -d "$home/.claude" ]` line, with:++```bash+echo "$status" | /usr/bin/grep -Eq '"session_sync":\{"enabled":true,[^}]*"loaded":true' || exit 1+if [ -d "$home/.claude" ]; then+ /usr/bin/grep -q 'beacon-hooks' "$home/.claude/settings.json" 2>/dev/null || exit 1+fi+if [ -d "$home/.codex" ]; then+ /usr/bin/grep -q 'beacon-hooks' "$home/.codex/hooks.json" 2>/dev/null || exit 1+fi+exit 0+```++On a Mac that already runs Beacon, the session sync starts the next time the remediation runs, or right away with `sudo /opt/beacon/bin/beacon endpoint sessions enable --system`. Session-file data reaches the bucket up to 15 minutes after the agent writes it.## Validate a pilot Mac@@ -391,7 +419,7 @@ sudo grep -c "$MARKER" /var/log/beacon-agent/runtime.jsonl1. Is the forwarder running? `sudo launchctl print system/com.beacon.endpoint.gcs-forwarder`. If not, read the remediation's log, `/var/root/Library/Logs/Beacon/kandji-gcs-reconcile.log`.2. Vector's own errors: `sudo tail -n 100 /Library/Logs/Beacon/com.beacon.endpoint.gcs-forwarder.err`. A `403` means the key belongs to the wrong service account, the writer lacks `roles/storage.objectCreator` on the bucket, or (with CMEK) cannot use the key.3. The key: `sudo stat -f 'owner=%Su mode=%Lp' "<key path>"` should show `owner=root` and mode `400` or `600`. If the key Custom App has not installed, the remediation reports "GCS writer key not delivered yet".-4. Runtime upload starts at the end of the log. Generate new activity (or `beacon endpoint gcs validate --system`) and wait up to five minutes.+4. Generate new activity (or `beacon endpoint gcs validate --system`) and wait up to five minutes. After its first start, the forwarder uploads only what is written after its checkpoint.5. Listing with the writer fails by design; use the reader.### The remediation fails with no console user