Entities

Documentation Index

Fetch the complete documentation index at: https://docs.esperr.com/llms.txt

Use this file to discover all available pages before exploring further.

Esper encodes traffic automatically, but the tenant still needs to define what counts as an entity for their property. New tenants are bootstrapped with bundled system entity definitions so the workspace is immediately usable before you author your own custom identity rules. If you are unsure which fields you can use, open the Field Reference. It explains the field list shown in the builder in non-technical language. Examples:

• Example: client_ip + request_header_user_agent
• Example: cookie + path pattern
• Example: ip + referer + action

​

System starter entities

Esper currently seeds new tenants with these system-defined entity definitions:

• ip-user-agent: client_ip + user_agent
• bot-crawlers: user_agent when the request matches known crawler tokens from OpenAI, Anthropic, Google, Apple, Meta, and Cloudflare

These starter definitions are bundled with the product itself and loaded from a versioned asset, so the backend and CLI use the same default entity shapes.

​

What you define for an entity

When creating an entity definition, you usually choose:

• name: A clear label for the identity rule.
• description: Optional context about what the entity represents.
• key_fields: The fields Esper should combine to identify the same actor, device, account, or session across requests.
• match_expression: An optional condition that limits when this entity definition applies.

​

Why this matters

Entity definitions tell Esper how to:

• Group related traffic.
• Accumulate state.
• Analyze repeated behavior.
• Bind policies to the right identity semantics.

​

Choosing key fields

Key fields tell Esper which values should stay stable when two requests belong to the same real-world actor, device, session, or account. In the builder, you are usually choosing from the tenant’s available field catalog directly. For match expressions, you may also use request-oriented conditions such as method, header, query parameter, cookie, or body data reference. Examples of strong key fields:

• Account or customer identifiers.
• Stable device identifiers.
• Source identifier plus browser identity.
• Client IP plus user agent when you need a practical edge-oriented fallback.
• Well-defined session fields.

Examples of weak key fields:

• Request timestamps.
• Values that are often blank.
• Values that change on every request.
• Fields that are too broad on their own, such as only the request path.

​

Where the field list comes from

The field list in the Entities builder is tenant-specific. Esper shows the fields currently available for this tenant, including:

• Captured fields.
• Derived fields.
• Action fields.

If a field you expect is missing, contact your Esper administrator or support team.