Skip to main content

Entities

Entities are the named AI components in your stack—models, tools, agents, guardrails, or any custom type. We map raw span data to these names so traces, conversations, and charts use language your team understands.

Why use Entities​

  • Clarity: Instantly see which model or tool handled a request and what it returned.
  • Speed: Filter traces by entity to spot regressions or failed tools faster.
  • Auditability: Prove guardrails ran and keep conversation context reviewable.
  • Consistency: One catalog you can import/export to keep staging and prod aligned.

1) Entity types​

  • Model (LLMs or other generators)
  • Tool (search, calculator, API call, retrieval step)
  • Agent (planner/orchestrator)
  • Guardrail (PII, toxicity, policy checks)
  • Embedding / Retriever / Evaluator (specialized roles)
  • Custom (anything else—routers, middleware, vector DBs, etc.)

Choose the closest fit; type controls default highlights and icons.

2) Matching logic​

We recognize an entity by matching a span attribute against a rule you define.

  • Attribute: the key in your span, e.g., gen_ai.request.model.
  • Rule: exact value or regex. First match wins, so order matters—put the most specific entities first.

Example
Attribute: gen_ai.request.model
Rule (regex): gpt-4.*

3) Highlights​

Highlights are the top-level stats that surface on a span card so you don’t have to open the payload.

  • Standard examples: latency, token count, error flag.
  • Custom examples: user.tier, retrieved_docs.count, guardrail.triggered.

Tips: promote only what speeds triage; keep the list short and meaningful.

4) Message reconstruction (models)​

Turn raw span attributes into readable chat threads in both Trace view and Conversations.

What it shows

  • In Trace view: the input history the model saw plus the model’s output for that span.
  • In Conversations: stitches model spans across traces with the same session so you can replay the whole journey.

How it extracts messages

  • Canonical: point to one attribute containing a JSON array of messages (role + content).
  • Flat: provide patterns for role/content/tool fields in flattened attributes (e.g., msgs.0.role, msgs.0.content); matching indices are grouped into messages.

Quality-of-life behavior

  • De-duplicates overlapping prefixes (if Span A has msgs 1–2 and Span B has 1–3, you see 1–3 once).
  • Uses span timestamps to order messages; better clock sync → cleaner threads.

Benefits

  • Non-technical reviewers can read conversations without digging into spans.
  • Easier to debug missing context, hallucinations, or tool choices span by span.

5) Import / export​

Export your entity catalog as YAML to back it up or import into another project (e.g., staging → prod).

Quick Start (Start from Source)​

If you use OpenInference, OpenLLMetry, OpenLIT, or OpenTelemetry, use Start from Source to import pre-configured entities in one click. Re-importing updates entities that have an externalId instead of creating duplicates.

externalId and updates​

Entities with an externalId field are updated when re-imported, rather than duplicated. Use this to keep entity definitions in sync across environments or to pull in template updates.

Quick start (5 minutes)​

  1. Go to Configurations → Entities. If you use OpenInference, OpenLLMetry, OpenLIT, or OpenTelemetry, click Start from Source and select your library to import pre-configured entities. Otherwise, click New Entity and choose a type (e.g., Model).
  2. Set the matching rule: pick the span attribute and enter the value or regex.
  3. Add highlights you care about (latency, token count, error flag, user tier).
  4. For models, configure message matching (canonical if you have a messages array; flat if fields are split).
  5. Save, then open a trace to confirm the badge, highlights, and chat view appear.

Example setups​

  • RAG pipeline: Entities for “Vector DB Retriever” and “LLM Generator” to see if context or generation caused the issue.
  • Agent tool use: Entities for “Search Tool”, “Calculator”, “Code Interpreter” to visualize the agent’s decision path and tool failures.
  • Guardrails: Entities for “Input Guardrail” and “Output Guardrail” to audit where safety checks ran or were skipped.

FAQs​

  • Do I need to change code? Ensure spans emit the attributes you reference in matching and message reconstruction; no SDK swap is required.
  • What if a span matches nothing? It stays unlabelled; add or adjust a rule and recheck.
  • Can I track vendor vs. in-house models? Yes—create separate entities with different match rules (e.g., gpt-4.* vs internal-llama.*).
  • Can I recover conversations later? Yes, as long as spans carry the message attributes you configured.