Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/gemini-cli-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: Gemini CLI collector privacy

on:
pull_request:
paths:
- 'src/pages/docs/integrations/coding-agents/gemini-cli.mdx'
- 'examples/coding-agents/gemini-cli/**'
- 'scripts/gemini-cli-page.test.mjs'
- '.github/workflows/gemini-cli-docs.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
collector-privacy:
name: Gemini CLI collector privacy
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Download released Collector Contrib
shell: bash
run: |
set -euo pipefail
mkdir "$RUNNER_TEMP/gemini-collector"
cd "$RUNNER_TEMP/gemini-collector"
archive=otelcol-contrib_0.162.0_linux_amd64.tar.gz
curl -fLsS "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.162.0/$archive" -o "$archive"
echo "fcc063749f730f8c21fe29f2d340ff174f5f1c5885bd3156fb6c985a3036fcc3 $archive" | sha256sum --check
tar -xzf "$archive" otelcol-contrib
test -x otelcol-contrib
- name: Check default and opt-in exports with loopback-only networking
shell: bash
run: |
sudo unshare --net -- bash -c '
set -euo pipefail
ip link set lo up
exec env OTELCOL_BIN="$1" "$2" -I -m unittest discover -s "$3" -v
' bash "$RUNNER_TEMP/gemini-collector/otelcol-contrib" "$(command -v python)" "$PWD/examples/coding-agents/gemini-cli/tests"
130 changes: 130 additions & 0 deletions examples/coding-agents/gemini-cli/otel-collector.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# OpenTelemetry Collector between Gemini CLI and Future AGI.
#
# Gemini CLI exports OTLP traces, logs and metrics to this collector. The
# collector keeps the traces, removes prompt-shaped attributes, labels the span
# kinds Future AGI shows, and forwards the traces with your Future AGI keys.
# Logs and metrics are dropped: the Future AGI collector accepts traces only.
#
# FI_API_KEY=... FI_SECRET_KEY=... otelcol-contrib --config otel-collector.yaml
#
# Environment:
# FI_API_KEY, FI_SECRET_KEY required
# FI_BASE_URL default https://api.futureagi.com (traces go to $FI_BASE_URL/tracer/v1/traces)
# FI_PROJECT_NAME default gemini-cli
# GEMINI_OTLP_LISTEN default 127.0.0.1:4318 (Gemini CLI's otlpEndpoint must match)
#
# The collector's own metrics endpoint (port 8888) is turned off at the end of
# this file, so it does not collide with Jupyter or another collector.

receivers:
otlp:
protocols:
http:
endpoint: ${env:GEMINI_OTLP_LISTEN:-127.0.0.1:4318}

processors:
transform/gemini-cli:
error_mode: ignore
trace_statements:
- context: resource
statements:
- set(attributes["project_name"], "${env:FI_PROJECT_NAME:-gemini-cli}")
# Node's default resource detectors record the full command line
# (for `gemini -p "..."` it contains the prompt), local paths, the
# OS user name and the machine name. Keep only runtime and arch.
- delete_key(attributes, "process.command_args")
- delete_key(attributes, "process.command")
- delete_key(attributes, "process.executable.path")
- delete_key(attributes, "process.executable.name")
- delete_key(attributes, "process.owner")
- delete_key(attributes, "host.name")
- delete_key(attributes, "host.id")
- context: span
statements:
# Gemini CLI names its operations llm_call, tool_call, agent_call,
# schedule_tool_calls, and in interactive mode user_prompt (one turn,
# the root of its model and tool spans) and system_prompt (the
# follow-up turn that sends tool results back to the model). Map them
# to the span kinds Future AGI uses.
- set(attributes["gen_ai.span.kind"], "LLM") where attributes["gen_ai.operation.name"] == "llm_call"
- set(attributes["gen_ai.span.kind"], "TOOL") where attributes["gen_ai.operation.name"] == "tool_call"
- set(attributes["gen_ai.span.kind"], "AGENT") where attributes["gen_ai.operation.name"] == "agent_call"
- set(attributes["gen_ai.span.kind"], "CHAIN") where attributes["gen_ai.operation.name"] == "schedule_tool_calls"
- set(attributes["gen_ai.span.kind"], "CHAIN") where attributes["gen_ai.operation.name"] == "user_prompt"
- set(attributes["gen_ai.span.kind"], "CHAIN") where attributes["gen_ai.operation.name"] == "system_prompt"
# Name tool spans after the tool instead of "tool_call".
- set(name, attributes["gen_ai.tool.name"]) where name == "tool_call" and attributes["gen_ai.tool.name"] != nil
# Every span carries the Gemini CLI session id; as session.id it groups
# the session's traces into one Future AGI session.
- set(attributes["session.id"], attributes["gen_ai.conversation.id"]) where attributes["gen_ai.conversation.id"] != nil
# Only present with the content opt-in (logPrompts: true): show the
# messages as the span's input and output in Future AGI.
- set(attributes["input.value"], attributes["gen_ai.input.messages"]) where attributes["gen_ai.input.messages"] != nil
- set(attributes["output.value"], attributes["gen_ai.output.messages"]) where attributes["gen_ai.output.messages"] != nil
- context: spanevent
statements:
# Gemini CLI records every error as an "exception" event. Its stack
# trace lists file:// paths of your Gemini CLI install (home
# directory, OS user name) and no content, so it is dropped even
# with the content opt-in.
- delete_key(attributes, "exception.stacktrace")

# Privacy default. With logPrompts false Gemini CLI already leaves out the
# message attributes; this also drops the system prompt (it embeds your
# GEMINI.md memory), the tool schemas and error text. Remove this processor
# from the pipeline below only to opt in to content.
transform/strip-content:
error_mode: ignore
trace_statements:
- context: span
statements:
- delete_key(attributes, "gen_ai.input.messages")
- delete_key(attributes, "gen_ai.output.messages")
- delete_key(attributes, "input.value")
- delete_key(attributes, "output.value")
- delete_key(attributes, "gen_ai.system_instructions")
- delete_key(attributes, "gen_ai.tool.definitions")
# The status message of a failed span is the raw error text: an API
# error body, or for a tool that throws, file paths and command
# output. Keep the ERROR status, replace the text (refined from the
# exception event below).
- set(status.message, "error") where status.code == STATUS_CODE_ERROR
- set(status.message, "") where status.code != STATUS_CODE_ERROR
- context: spanevent
statements:
# Status message = the error class or code (ApiError, ENOENT, ...),
# plus the HTTP status for Gemini API errors ("ApiError HTTP 429").
- set(span.status.message, attributes["exception.type"]) where name == "exception" and span.status.code == STATUS_CODE_ERROR and IsMatch(attributes["exception.type"], "^[A-Za-z0-9_.:-]{1,80}$")
- set(span.status.message, Concat([attributes["exception.type"], ExtractPatterns(attributes["exception.message"], "\"code\\\\?\":\\s*(?P<code>[1-5][0-9][0-9])")["code"]], " HTTP ")) where name == "exception" and span.status.code == STATUS_CODE_ERROR and attributes["exception.type"] == "ApiError" and IsMatch(attributes["exception.message"], "\"code\\\\?\":\\s*[1-5][0-9][0-9]")
- delete_key(attributes, "exception.type") where not IsMatch(attributes["exception.type"], "^[A-Za-z0-9_.:-]{1,80}$")
- delete_key(attributes, "exception.message")

batch:
timeout: 2s

exporters:
otlphttp/futureagi:
traces_endpoint: ${env:FI_BASE_URL:-https://api.futureagi.com}/tracer/v1/traces
# The Future AGI collector reads the request body as-is; the exporter's
# default gzip encoding is answered with HTTP 400.
compression: none
headers:
X-Api-Key: ${env:FI_API_KEY}
X-Secret-Key: ${env:FI_SECRET_KEY}
nop: {}

service:
telemetry:
metrics:
level: none
pipelines:
traces:
receivers: [otlp]
processors: [transform/gemini-cli, transform/strip-content, batch]
exporters: [otlphttp/futureagi]
logs:
receivers: [otlp]
exporters: [nop]
metrics:
receivers: [otlp]
exporters: [nop]
132 changes: 132 additions & 0 deletions examples/coding-agents/gemini-cli/run_e2e.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
#!/usr/bin/env bash
# One real Gemini CLI session, exported through otel-collector.yaml to Future AGI.
#
# FI_API_KEY=... FI_SECRET_KEY=... GEMINI_API_KEY=... ./run_e2e.sh
#
# Optional: FI_BASE_URL (default https://api.futureagi.com), FI_PROJECT_NAME
# (default gemini-cli), GEMINI_MODEL (default gemini-3.8-flash),
# GEMINI_OTLP_PORT (port the collector listens on, default 24318),
# GEMINI_BIN / OTELCOL_BIN (default: gemini / otelcol-contrib on PATH),
# CAPTURE_CONTENT=1 to run the documented content opt-in instead.
#
# Gemini CLI runs with a throwaway HOME and project directory, so your own
# ~/.gemini settings and sessions are not read or changed. The prompt asks for
# a directory listing and a file read, so the session has tool calls. The
# collector also writes what it forwards to a local file, which the script
# checks: by default the marker string from the prompt, your user name, home
# directory and machine name must not be in it; with CAPTURE_CONTENT=1 the
# marker must be. It also fails if the port is already taken by another process
# or the collector forwarded no spans. The script exits non-zero if a check
# fails and then keeps its work directory for inspection; on success it deletes
# it. It runs Gemini CLI non-interactively (-p), so there is no user_prompt turn
# span; see the page for the interactive trace shape.
set -euo pipefail

HERE="$(cd "$(dirname "$0")" && pwd)"
: "${FI_API_KEY:?set FI_API_KEY}" "${FI_SECRET_KEY:?set FI_SECRET_KEY}"
: "${GEMINI_API_KEY:?set GEMINI_API_KEY}"
GEMINI_BIN="${GEMINI_BIN:-gemini}"
OTELCOL_BIN="${OTELCOL_BIN:-otelcol-contrib}"
PORT="${GEMINI_OTLP_PORT:-24318}"
export FI_PROJECT_NAME="${FI_PROJECT_NAME:-gemini-cli}"
export GEMINI_OTLP_LISTEN="127.0.0.1:$PORT"

# Another process on the port would receive Gemini CLI's spans instead of this
# collector, and the checks below would run on an empty capture.
if (exec 3<>"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null; then
echo "FAIL: port $PORT is already in use by another process; set GEMINI_OTLP_PORT to a free port" >&2
exit 1
fi

WORK="$(mktemp -d)"
fail() {
echo "FAIL: $*" >&2
echo "work directory kept: $WORK" >&2
exit 1
}
COLLECTOR_ARGS=(--config "$HERE/otel-collector.yaml"
--set "exporters.file/e2e.path=$WORK/forwarded.json"
--set "service.pipelines.traces.exporters=[otlphttp/futureagi,file/e2e]")
LOG_PROMPTS=false
if [ "${CAPTURE_CONTENT:-0}" = "1" ]; then
LOG_PROMPTS=true
COLLECTOR_ARGS+=(--set "service.pipelines.traces.processors=[transform/gemini-cli,batch]")
fi

"$OTELCOL_BIN" "${COLLECTOR_ARGS[@]}" > "$WORK/collector.log" 2>&1 &
COLLECTOR_PID=$!
trap 'kill "$COLLECTOR_PID" 2>/dev/null || true' EXIT
listening=0
for _ in $(seq 1 50); do
if (exec 3<>"/dev/tcp/127.0.0.1/$PORT") 2>/dev/null; then listening=1; break; fi
kill -0 "$COLLECTOR_PID" 2>/dev/null || break
sleep 0.2
done
if [ "$listening" != 1 ] || ! kill -0 "$COLLECTOR_PID" 2>/dev/null; then
tail -5 "$WORK/collector.log" >&2
if grep -q "address already in use" "$WORK/collector.log"; then
fail "port $PORT is already in use by another process; set GEMINI_OTLP_PORT to a free port"
fi
fail "the collector is not listening on 127.0.0.1:$PORT (see $WORK/collector.log)"
fi

mkdir -p "$WORK/home/.gemini" "$WORK/project"
python3 - "$HERE/settings.json" "$WORK/home/.gemini/settings.json" "$PORT" "$LOG_PROMPTS" <<'EOF'
import json, sys
src, dst, port, log_prompts = sys.argv[1:]
settings = json.load(open(src))
settings["telemetry"]["otlpEndpoint"] = "http://127.0.0.1:" + port
settings["telemetry"]["logPrompts"] = log_prompts == "true"
settings["security"] = {"auth": {"selectedType": "gemini-api-key"}}
json.dump(settings, open(dst, "w"), indent=2)
EOF
printf '# Gemini CLI E2E fixture\n\nA throwaway project for the Future AGI recipe.\n' > "$WORK/project/README.md"

SESSION_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
MARKER="FI-E2E-MARKER-$(date +%s)"
(
cd "$WORK/project"
HOME="$WORK/home" GEMINI_CLI_TRUST_WORKSPACE=true OTEL_NODE_RESOURCE_DETECTORS=env \
"$GEMINI_BIN" -m "${GEMINI_MODEL:-gemini-3.8-flash}" --session-id "$SESSION_ID" \
-p "List the files in this folder and read README.md. Reply with its first heading. $MARKER" \
< /dev/null
) || echo "gemini exited non-zero; checking what was exported anyway" >&2

# Gemini CLI flushes on exit; give the collector's batch processor time to send.
sleep 5
kill "$COLLECTOR_PID"
wait "$COLLECTOR_PID" 2>/dev/null || true
trap - EXIT
if grep -q -E $'\terror\t|Exporting failed' "$WORK/collector.log"; then
echo "collector log has errors:" >&2
grep -E $'\terror\t|Exporting failed' "$WORK/collector.log" | tail -5 >&2
fi

echo "session_id=$SESSION_ID"
echo "marker=$MARKER"
echo "project=$FI_PROJECT_NAME"
touch "$WORK/forwarded.json"
SPANS_FORWARDED="$(python3 - "$WORK/forwarded.json" <<'EOF'
import json, sys
spans = [s for line in open(sys.argv[1]) if line.strip()
for rs in json.loads(line)["resourceSpans"] for ss in rs["scopeSpans"] for s in ss["spans"]]
print(len(spans))
print("span_names=%s" % ",".join(sorted({s["name"] for s in spans})), file=sys.stderr)
EOF
)"
echo "spans_forwarded=$SPANS_FORWARDED"
# Zero spans would make the privacy checks below pass on nothing.
[ "$SPANS_FORWARDED" -gt 0 ] || fail "the collector forwarded no spans (see $WORK/collector.log)"
if [ "$LOG_PROMPTS" = true ]; then
grep -q -F "$MARKER" "$WORK/forwarded.json" || fail "content opt-in: the marker was not forwarded"
echo "privacy: content opt-in, marker forwarded"
else
if grep -q -F "$MARKER" "$WORK/forwarded.json"; then fail "the prompt marker was forwarded"; fi
for needle in "$HOME" "/$(id -un)/" "$(hostname)" "$(hostname -s)"; do
if grep -q -F "$needle" "$WORK/forwarded.json"; then
fail "forwarded spans contain a local identity string"
fi
done
echo "privacy: marker, home directory, user name and machine name not forwarded"
fi
rm -rf "$WORK"
10 changes: 10 additions & 0 deletions examples/coding-agents/gemini-cli/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "http://127.0.0.1:4318",
"otlpProtocol": "http",
"traces": true,
"logPrompts": false
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Test-only overlay for otel-collector.yaml: write forwarded traces to a file
# instead of sending them to Future AGI.
exporters:
file/test:
path: ${env:TEST_OUT}
flush_interval: 100ms
processors:
batch:
timeout: 100ms
service:
pipelines:
traces:
exporters: [file/test]
Loading
Loading