mats/go-otel
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve agent-facing history endpoints (Phase 1)

Browse Source 
- Fix /api/history/{type} to search the full persistent store instead of
  only the bounded in-memory ring buffer, so filtered history isn't
  silently truncated.
- Add structured type/since/until filters to /api/history/search and
  /api/history/wait, alongside the existing free-text query.
- Add GET /api/traces/{traceId} to fetch all entries for a trace in one
  call instead of relying on substring search.
- Rate-limit /api/history/wait per client IP.
- Add docs/PLAN.md tracking the phased improvement plan; update README
  and agents_example.md for the new/changed endpoints.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
developerandClaude Sonnet 5 committed 2026-09-17 09:30:18 +00:00
1 parent 0ed1cb4355
commit f77b89a779
13 files changed
+473 -88
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

agents_example.md
+11 -7
View File
@@ -5,14 +5,18 @@ This document provides instructions for AI agents on how to utilize the OTEL Col
## Base Configuration
- **Base URL**: `https://otel.k6n.net`
- **Endpoints**:
- `GET /api/history/search?q={query}&limit={limit}`: Search all historical telemetry data.
- `GET /api/history/search?q={query}&type={type}&since={ns}&until={ns}&limit={limit}`: Search all historical telemetry data.
- **Default Limit**: 50 (max 100 recommended for context).
- **Ordering**: Latest entries first.
- **Match Scope**: Case-insensitive substring match on raw JSON (covers service name, span body, attributes, etc.).
- `GET /api/history/wait?q={query}&timeout={seconds}`: **Wait** for a specific signal to arrive.
- **Match Scope**: Case-insensitive substring match on raw JSON (covers service name, span body, attributes, etc.), combinable with structured filters.
- **type**: optional, one of `traces`, `metrics`, `logs`.
- **since / until**: optional, unix nanosecond timestamps to bound the time range.
- `GET /api/history/wait?q={query}&type={type}&timeout={seconds}`: **Wait** for a specific signal to arrive.
- **Blocking**: This call blocks until a match is found or the timeout (default 30s) is reached.
- **Ideal for Automation**: Use this after triggering an action to wait for the exact result.
- `GET /api/history`: Fetch the recent in-memory history of all telemetry.
- **Rate limited**: capped per client IP; back off if you receive `429`.
- `GET /api/traces/{traceId}`: Fetch every stored entry (spans and correlated logs) referencing a specific trace id in one call. Prefer this over substring-searching for a trace id.
- `GET /api/history`: Fetch recent history of all telemetry (searches the full persistent store, not just recent in-memory entries).
- `GET /api/history/traces`: Fetch recent traces.
- `GET /api/history/logs`: Fetch recent logs.
- `GET /api/history/metrics`: Fetch recent metrics.
@@ -38,12 +42,12 @@ curl "https://otel.k6n.net/api/history/wait?q=5682138e4a9b4629852899d45e542456&t
```
### 3. Identifying Trace Chains
If you find a log entry with a `traceId`, use the search endpoint to find all spans and logs associated with that specific trace to understand the full request flow.
If you find a log entry with a `traceId`, use the dedicated trace endpoint to fetch all spans and logs associated with that specific trace and understand the full request flow.
**Example Request:**
```bash
# Search for all activity related to a specific trace
curl "https://otel.k6n.net/api/history/search?q=5682138e4a9b4629852899d45e542456&limit=100"
# Fetch all activity related to a specific trace
curl "https://otel.k6n.net/api/traces/5682138e4a9b4629852899d45e542456"
```
### 3. Fetching Recent Telemetry