Skip to content

How LLMInspect Uniquely Identifies Users in Tap Mode

Overview

LLMInspect offers powerful observability and traceability features, designed to help teams monitor and analyze API client interactions in real-time. When deployed in Tap Mode, LLMInspect mirrors requests from an API Gateway (like Kong) and logs detailed insights for each incoming request.

All logs and user activity traces are available in the API Client Observability dashboard within Grafana. These insights help teams understand who made a request, from where, and under what identity—supporting auditing, debugging, and usage analysis.

Why User Identification Matters

To enable complete traceability and user-level observability, LLMInspect attempts to bind each incoming request to a uniquely identifiable user. This allows administrators to view per-user activity, filter requests by user identity, and detect suspicious or unusual usage patterns.

How User Identification Works

LLMInspect uses a multi-layered strategy to identify users from the incoming request. It follows a precedence-based protocol, where the most reliable source of user identity is used when available.

Precedence Order

LLMInspect evaluates the following sources to identify a user (in order of precedence):

  1. JWT Token (Authorization: Bearer) If the request includes a JWT token in the Authorization header, LLMInspect attempts to decode it using OpenID Connect standards. The value of the preferred_username field (if present) is used as the user identifier.

  2. Explicit Header (X-User-Name) If the JWT token is not present or invalid, and the request includes an X-User-Name header, LLMInspect uses the value of this header as the user's identity.

  3. Public IP from Gateway (X-Forwarded-For) If neither JWT nor X-User-Name is provided, LLMInspect uses the client’s public IP address as seen in the X-Forwarded-For (XFF) header. This is typically set by the gateway (like Kong or APISIX) and represents the origin IP of the request.

  4. Fallback (ApiClient) If all else fails, and no identifying information is available, LLMInspect groups such requests under a generic identity named ApiClient.

Summary of Identification Sources

Source Used As User Identity Notes
Authorization: Bearer <jwt> preferred_username claim in token Must follow OpenID Connect standard
X-User-Name header Header value Useful for explicit third-party integrations
X-Forwarded-For header IP address Set by Kong/APISIX Gateway; used when no user headers are provided
None available ApiClient Default fallback

Practical Example in Tap Mode

When Kong is integrated with LLMInspect in Tap Mode, all API traffic is mirrored to LLMInspect for inspection. Here’s how the identification process works in practice:

  • A user sends a request to your API Gateway.
  • Kong mirrors the request to LLMInspect using the installed plugin.
  • LLMInspect checks for a JWT token or X-User-Name in the request.
  • If not found, it checks the X-Forwarded-For header.
  • The user identity is resolved using the precedence rules.
  • The request and user identity are logged to the API Client Observability dashboard in Grafana.

Tips for Accurate User Tracing

  • Use X-User-Name when integrating with services or scripts that don’t use JWT.
  • Prefer JWT tokens for authentication to enable standardized user tracking.
  • Monitor unidentified users labeled as ApiClient to improve integration fidelity.

Where to See User Data

Visit the API Client Observability Grafana dashboard to:

  • View requests grouped by user
  • Analyze traffic volume per user
  • Track usage trends over time
  • Spot unusual behavior or spikes in activity

Conclusion

LLMInspect makes it easy to trace each request back to a specific user—even in mirrored Tap Mode setups. This layered identification approach ensures reliable attribution and actionable insights into how your APIs are being used.

If you have any questions or want to improve how user identity is passed in mirrored requests, please reach out to our support team.