Session Keeping

• Sticky Load Balancing – ein virtuelles Modell mit Load Balancing routet jeden Request einer Session an das Ziel, das sie zuerst bedient hat. Das hält die Prompt-Caches des Providers warm und das Modellverhalten innerhalb einer Unterhaltung konsistent.
• Sticky API-Key-Auswahl – hat ein Provider mehrere Keys, verwendet jeder Request einer erkannten Session denselben Key, wodurch die Prompt-Cache-Affinität beim Provider erhalten bleibt.
• Gruppierte Audit-Logs – die Seite „Audit Logs“ im Dashboard fasst die Requests einer Session zu einem Thread zusammen: Der neueste Request bildet die Zeile, und ein Aufklapp-Element zeigt die älteren Requests darunter an.
• Nutzung und Kosten pro Session – Nutzungsdatensätze tragen dieselbe gescopte Session-ID, sodass Dashboard und Admin API die Requests, Tokens und Provider-Ausgaben für eine Unterhaltung oder Agent-Aufgabe ausweisen können.

​

Wie eine Session identifiziert wird

1. Session-Header – eine eingebaute Registry deckt die Header ab, die bekannte Tools senden, sowie Gateway-Konventionen:

   Header	Gesendet von
   X-Session-Id	OpenCode, Kilo Code, generische Clients
   X-Opencode-Session	OpenCode, pi und andere Clients, die den Dialekt von OpenCode Zen sprechen
   X-Claude-Code-Session-Id	Claude Code (für Gateways dokumentiert)
   Session-Id / Session_id	Codex CLI (aktuell / älter), Roo Code
   X-Litellm-Session-Id	LiteLLM-Konvention
   Helicone-Session-Id	Helicone-Konvention
   Agent-Session-Id	Goose

2. Body-Felder – für Clients, die Sessions im Request-Body kennzeichnen: Anthropic metadata.user_id (Claude Code bettet dort seine Session-UUID ein; sowohl das aktuelle als auch das ältere Format werden geparst), session_id (OpenRouter-Konvention), litellm_session_id, prompt_cache_key (Zed und andere OpenAI-Clients, die pro Unterhaltung einen Cache-Key wiederverwenden) sowie conversation-Referenzen in /v1/responses.
3. Automatische Erkennung – Chat- und Responses-Requests ohne explizites Signal werden anhand ihres Unterhaltungsbeginns gruppiert: Modell, Systemkontext, Tools und die Nachrichten bis einschließlich des ersten User-Turns. Folge-Requests senden dieses Präfix unverändert erneut, daher erhält ein Agent, der einfach seinen Verlauf wiederholt (Aider, Cline, Continue, …), ohne Änderungen am Client trotzdem eine stabile Session-ID (auto-…).

​

Sticky Load Balancing

virtual_models:
  - source: "smart"
    strategy: round_robin
    session_affinity: false   # Standard: true
    targets:
      - model: "openai/gpt-4o"
      - model: "anthropic/claude-sonnet-5"

​

Gruppierte Audit-Logs

​

Nutzung und Kosten pro Session

curl -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  "http://localhost:8080/admin/usage/sessions?days=7&limit=50&offset=0"

{
  "entries": [
    {
      "session_id": "scoped-0123456789abcdef0123456789abcdef",
      "user_path": "/team/alpha",
      "requests": 8,
      "input_tokens": 24000,
      "output_tokens": 4100,
      "total_tokens": 28100,
      "input_cost": 0.42,
      "output_cost": 0.16,
      "total_cost": 0.58
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​

Konfiguration

# Hauptschalter für die Session-Identifikation
SESSION_KEEPING_ENABLED=true
# Inhaltsbasierte Erkennung für Requests ohne explizites Signal
SESSION_AUTO_DETECT=true
# Die eingebaute Registry für Header/Body-Felder
SESSION_BUILTIN_RULES=true
# Zusätzliche Session-Header (ab 1 nummeriert), über die eingebauten gelegt.
# Die optionale Transformation "session-uuid" extrahiert einen session_<uuid>-Wert.
SESSION_HEADER_1=X-My-Session
SESSION_HEADER_1_TRANSFORM=

session:
  enabled: true
  auto_detect: true
  builtin_rules: true
  headers:
    - header: X-My-Session