Add basic Ramen telemetry and EIS attribution

[vigneshshanmugam]

Summary

We need a lightweight telemetry plan for Elastic Ramen so we can understand real usage beyond npm downloads.

The main goals are:

• Track whether users are using Ramen at all.
• Distinguish users coming from Ramen -> EIS versus the regular EIS flow.
• Make the signal usable in Kibana for product usage, adoption, and billing attribution.
• Keep telemetry basic, privacy-conscious, and documented.

[github-actions]

tl;dr: The best path is to treat existing Kibana conversation sync as the baseline telemetry channel and add a minimal, privacy-safe usage event at the same busy→idle hook, while using existing RAMEN: title + agent_id for Ramen→EIS attribution.

Recommendation

Use the current conversation sync pipeline as the canonical signal, then add one lightweight aggregate telemetry emission at the same trigger point (busy → idle) rather than introducing a parallel instrumentation surface.

Concretely:

1. Keep attribution dimensions already in use: agent_id: "elastic-ai-agent" and title: "RAMEN: ...".
2. Add a minimal event payload (session/turn counters, timestamps, flow/source label) at the existing sync boundary.
3. Do not include raw user/assistant text, tool params/results, or reasoning in the new telemetry event payload.

Findings

• packages/opencode/src/cli/cmd/tui/app.tsx:441-446 already has a reliable lifecycle boundary (last === "busy" && status.type === "idle") and calls Handover.sync(...).
• packages/opencode/src/elastic/handover.ts:74-85 already writes a strong attribution marker to Kibana:
  • title: \\RAMEN: ${title}\``
  • agent_id: "elastic-ai-agent"
  • conversation_rounds: ...
• packages/opencode/src/elastic/client.ts:215-225 sends this data to /internal/elastic_ramen/conversations (POST/PUT) and supports filtering by agent_id.
• README.md:261-267 documents that sessions are synced to Kibana on busy→idle transitions.
• packages/opencode/src/cli/cmd/tui/app.tsx:405-419 shows current round building includes potentially sensitive content (tool params/results, reasoning, message text), so any new telemetry event should be aggregate-only.
• Related issue discovery was partially blocked by policy-integrity filtering for #53 and #57, so I could not validate those discussions.

Verification

I validated the concrete hooks and payload fields with repository commands:

$ grep -nE 'last === "busy" && status.type === "idle"|Handover\.sync\(|RAMEN:|agent_id: "elastic-ai-agent"|internal/elastic_ramen/conversations|conversation_rounds' \
  packages/opencode/src/cli/cmd/tui/app.tsx \
  packages/opencode/src/elastic/handover.ts \
  packages/opencode/src/elastic/client.ts README.md
packages/opencode/src/cli/cmd/tui/app.tsx:441:      if (last === "busy" && status.type === "idle") {
packages/opencode/src/cli/cmd/tui/app.tsx:445:        Handover.sync(sessionID, session.title, rounds).catch((err) => {
packages/opencode/src/elastic/handover.ts:74:        title: `RAMEN: ${title}`,
packages/opencode/src/elastic/handover.ts:82:      agent_id: "elastic-ai-agent",
packages/opencode/src/elastic/client.ts:215:        return request(api("/internal/elastic_ramen/conversations", qs ? "?" + qs : "", space))
README.md:261:Sessions are automatically synced to Kibana as conversations...

$ grep -RIn "Handover\.|elastic_ramen/conversations|conversation_rounds" packages/opencode/test || true
# (no matches)

Detailed Action Plan

1. Define telemetry contract (aggregate-only)

   • Add a small schema near packages/opencode/src/elastic/handover.ts (or adjacent telemetry module) with fields like:
     • source: ramen_tui / ramen_headless
     • session_id_hash (or stable non-PII surrogate)
     • turn_count, tool_call_count, sync_time
     • attribution: agent_id, title_prefix_present
   • Exclude message/tool/reasoning bodies.

2. Emit event at existing lifecycle hook

   • In packages/opencode/src/cli/cmd/tui/app.tsx:441-446, where Handover.sync(...) runs, emit the new telemetry event in the same transition path.
   • Keep event emission best-effort and non-blocking for UX.

3. Keep existing attribution dimensions and codify queryability

   • Continue using agent_id: "elastic-ai-agent" and title prefix in packages/opencode/src/elastic/handover.ts:74-85.
   • Document recommended Kibana aggregations/filters by these fields.

4. Cover non-TUI entrypoints for adoption accuracy

   • Audit headless path (packages/opencode/src/cli/cmd/run.ts) and ensure equivalent telemetry event emission so usage counts are not TUI-only.

5. Add tests + docs

   • Add unit tests around payload redaction/field set and emission trigger behavior.
   • Update docs near README.md:259-267 with telemetry purpose, payload policy, and attribution fields.

Related Items

Type	Link	Relevance
Issue	#71	Current request for basic telemetry + attribution
File	packages/opencode/src/cli/cmd/tui/app.tsx:389-446	Busy→idle trigger and round construction
File	packages/opencode/src/elastic/handover.ts:67-87	Existing Kibana sync + RAMEN:/agent_id attribution markers
File	packages/opencode/src/elastic/client.ts:209-225	Conversations API endpoints and payload shapes
File	README.md:259-267	Documented conversation sync behavior
Issue	#53, #57	Potentially related, but content access was blocked by integrity policy in this workflow

Note

🔒 Integrity filter blocked 11 items

The following items were blocked because they don't meet the GitHub integrity level.

• #57 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #53 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #67 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #65 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #69 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #64 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #34 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #33 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #58 search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #57 issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #53 issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

---

What is this? | From workflow: Triage Issue

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.