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

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

2.6 KiB Raw Blame History