77 lines
2.6 KiB
Markdown
77 lines
2.6 KiB
Markdown
# Super Search v2.4.0 -- Client-ID Metrics Tracking
|
|
|
|
**Created:** 2026-08-08
|
|
**Service:** Super Search MCP (Core, port 8899)
|
|
**Feature:** Client-ID tracking via Prometheus metrics + Grafana dashboard
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Super Search v2.4.0 adds per-client usage tracking. A Starlette middleware intercepts the `X-Client-Id` header on every MCP call and increments Prometheus counters per client and per tool. Metrics are exposed at `:8899/metrics` and scraped by Prometheus every 30s. A Grafana dashboard visualizes usage.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Client (hermes/intelsight/dre-osint/verdicttank)
|
|
-> X-Client-Id header
|
|
-> Super Search Middleware (intercepts, increments Prometheus counter)
|
|
-> MCP tool handler
|
|
-> :8899/metrics (Prometheus endpoint)
|
|
-> Prometheus (Docker, scrapes 172.17.0.1:8899/metrics every 30s)
|
|
-> Grafana (Dashboard: "Super Search - Client Tracking" at /d/ffuktvmgcpkhse)
|
|
```
|
|
|
|
## Clients Tracked
|
|
|
|
| Client | Purpose |
|
|
|--------|---------|
|
|
| `hermes` | Hermes Agent's own Super Search usage |
|
|
| `intelsight` | IntelSight product backend |
|
|
| `dre-osint` | Debt Recovery Experts skip tracing |
|
|
| `verdicttank` | VerdictTank research |
|
|
|
|
Fallback: calls without `X-Client-Id` header are logged as `anonymous`.
|
|
|
|
## Key Changes
|
|
|
|
### Super Search (server.py)
|
|
- Middleware added: intercepts `X-Client-Id` header on `/mcp` POST
|
|
- Prometheus counters: `ss_tool_calls_total{client, tool}`, `ss_tool_duration_seconds{client, tool}`
|
|
- `/metrics` endpoint exposed on port 8899
|
|
|
|
### Prometheus (prometheus.yml)
|
|
- Job: `super-search`
|
|
- Target: `172.17.0.1:8899` (Docker bridge to host)
|
|
- Scrape interval: 30s
|
|
- Config: `/root/docker/monitoring/prometheus/prometheus.yml`
|
|
|
|
### Grafana
|
|
- Dashboard UID: `ffuktvmgcpkhse`
|
|
- Title: "Super Search - Client Tracking"
|
|
- Access: `https://core:3002/d/ffuktvmgcpkhse`
|
|
- Panels: tool calls per client, duration distribution, top tools
|
|
|
|
### Firewall (UFW)
|
|
- Rule: allow 172.17.0.0/16 to port 8899/tcp
|
|
- Reason: Prometheus Docker container needs host access
|
|
|
|
### Super Search Binding
|
|
- Changed from `127.0.0.1:8899` to `0.0.0.0:8899`
|
|
- Required because Docker containers (Prometheus) cannot reach 127.0.0.1 on the host
|
|
|
|
## Verification
|
|
|
|
```
|
|
ss -tlnp | grep 8899 -> 0.0.0.0:8899 (bound to all interfaces)
|
|
curl -s 172.17.0.1:8899/metrics | grep ss_tool -> counters present
|
|
ufw status | grep 8899 -> ALLOW 172.17.0.0/16
|
|
```
|
|
|
|
## Related Docs
|
|
|
|
- Super Search Enhancement Plan: `/root/projects/itpp-infrastructure/docs/super-search-enhancement-plan.md`
|
|
- Server: `/root/docker/super-search/server.py`
|
|
- Systemd: `super-search.service`
|
|
- Prometheus config: `/root/docker/monitoring/prometheus/prometheus.yml`
|