Raindrop.io Connection

The Raindrop.io connection integrates your Raindrop workspace with OpsTower, giving agents the ability to list and inspect LLM conversations, drill into individual events (turns), and pull the full OpenTelemetry trace tree behind any event — every LLM call, tool invocation, and internal span with timing, model, and token data.

This is the first integration in OpsTower’s LLM Tracing category. Use it when you want a debugger or analyst agent to investigate why a specific AI feature behaved the way it did, in production.

Prerequisites

You need a Raindrop workspace with at least one tracing API key. Both team and individual workspaces are supported.

Credentials Required

To set up a Raindrop connection, you need:

• API Key — a workspace API key with read access to conversations, events, and traces.

That is the only field. The key is sent as a bearer token to https://query.raindrop.ai/v1 and scopes every request to the workspace that issued it.

How to Generate an API Key

1. Sign in to your Raindrop workspace at https://app.raindrop.ai.
2. Open Settings > API Keys.
3. Click Create API Key, give it a descriptive label (e.g., “OpsTower”), and copy the generated key.
4. Paste the key into OpsTower.

API keys grant read access to all conversations, events, and trace spans in the workspace. Treat them like any other production secret. Rotate via the same settings page if compromised.

Setting Up the Connection in OpsTower

1. In OpsTower, navigate to Connections in the sidebar.
2. Click Add Connection and select the LLM Tracing category, then Raindrop.io.
3. Enter your API Key.
4. Click Test Connection to verify the key.
5. Click Save to create the connection.

What Agents Can Do with Raindrop

Once connected and enabled on an agent, the agent can:

• List conversations — recent LLM session threads with end-user IDs, time spans, message counts, and detected signals. Filter by user, by time window, or sort by most recent activity.
• Get a conversation — one conversation’s metadata: time span, end-user, message count, and the full set of signals it triggered.
• List events — LLM turns and tool invocations with truncated user input / assistant output and top signals. Filter by conversation, user, event name, signal, signal group, or time window. Supports cursor pagination.
• Get an event — one event’s full user input, assistant output, all signals (with scores), and event properties as JSON.
• Get a trace — the full OpenTelemetry trace tree behind an event: every LLM call, tool call, and internal span, indented by parent → child, with duration, status, model, provider, token counts, and truncated input/output payloads.

A typical investigation flow:

1. Ask the agent for recent conversations from the affected user (list_conversations).
2. Drill into one conversation’s events (list_events with convo_id).
3. Pick the suspect event, get the full payload (get_event), then the trace (get_trace) to see exactly what models were called, in what order, with what inputs and outputs.

Large Traces — getAsFile

Real production traces can be enormous — a single trace can carry hundreds of KB of LLM call payloads (prompts, full assistant outputs, tool inputs/outputs). Pasting all of that into the agent’s context blows the token budget for no good reason: the agent usually only needs to grep a few fields.

get_trace accepts an optional getAsFile: boolean (default false):

• false (default) — the trace is rendered as an indented markdown tree with each span’s input/output clipped to 200 chars (SPAN_PREVIEW_LEN). The bottom of the response includes a one-line hint telling the agent how many spans were clipped, so it knows when to re-call in file mode without guessing.
• true — the raw Raindrop API JSON response is written to a temporary R2 object and returned as a short-lived (15 minute) public URL plus size and span count. The default trunc_len jumps from 4000 to 50000 in this mode so the file contains the full untruncated payloads. The agent then fetches the URL with a code-execute or HTTP-fetch tool and processes the JSON deliberately — grepping specific span IDs, filtering by span_type, extracting model parameters, etc.

Sample agent flow with getAsFile:

> get_trace({ event_id: "evt_abc123" })
   → (markdown tree with hint: "12 span(s) had payloads clipped to 200 chars…")

> get_trace({ event_id: "evt_abc123", getAsFile: true })
   → Saved trace for event evt_abc123 as JSON file.
     - spans: 142
     - size: 487.3 KB
     - content_type: application/json
     - expires_in_seconds: 900
     - url: https://…r2.cloudflarestorage.com/…X-Amz-Signature=…

> code_execute({ code: "fetch the URL, parse the JSON, return all LLM_GENERATION spans with model='gpt-5'" })
   → focused analysis on a small subset

Safety bounds:

• File-mode trunc_len defaults to 50000 and the schema cap is 100000. The agent can dial it higher when it needs bigger per-span payloads.
• The file size is hard-capped at 25 MB. If a trace exceeds that, the tool returns an error suggesting a smaller trunc_len or limit instead of writing the file.
• URLs expire in 15 minutes. Re-call get_trace with getAsFile: true if a URL expires before the agent finishes.
• Files are written to OpsTower’s internal R2 bucket under raindrop-cache/{integrationId}/… and aren’t visible to anyone outside your account.

Out of Scope (Today)

This integration ships the read endpoints listed above. The following Raindrop surfaces are planned but not yet exposed as tools:

• signals / signal_groups — the classification primitives that show up inside conversation and event responses today. Useful for asking “show me everything tagged as frustration,” but require an additional discovery step on top of the read endpoints.
• /v1/ask — Raindrop’s natural-language Q&A endpoint. Useful, but competes with the OpsTower agent’s own reasoning loop, so it’s deferred until we have a clear “delegate vs reason in-line” decision.
• properties / traits object-shaped filters on list_events — the model can already narrow by event_name, convo_id, user_id, signal, and time window, which covers most investigations.

Troubleshooting

• Authentication failed (401): Verify the API key is correct, hasn’t been revoked, and belongs to the workspace whose data you want to query. Regenerate the key from Settings > API Keys if in doubt.
• No conversations returned: Try widening the time window. The default sort is -last_message_at (newest first); if the workspace is quiet, the most recent activity may be older than the implicit window in your prompt. Drop the started_after filter to see everything.
• No trace spans for an event: The event may pre-date your Raindrop SDK upgrade to OTel instrumentation, or the SDK may have dropped the spans under back-pressure. Confirm trace data exists in the Raindrop UI before debugging the OpsTower side.
• Rate limited (429): Reduce query frequency or increase the limit per call so the agent makes fewer round-trips. Raindrop applies per-workspace rate limits.
• 14-day date range limit error on events: Raindrop bounds search operations to a 14-day window. Narrow timestamp_after and timestamp_before accordingly.