Skip to main content
This guide shows you how to capture user feedback (thumbs up/down, ratings, comments) and associate it with your traces.
User feedback is evaluation data. This page covers the how - capturing feedback via trace enrichment. To understand what to do with this data (building datasets, comparing against automated evals, running experiments), see Experiments.

​
Quick Start

Use enrich_session() to add feedback to the entire trace, or enrich_span() to add feedback to a specific operation.

​
On the Session

Add feedback that applies to the entire user interaction: 
from honeyhive import HoneyHiveTracer
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

# ... your application logic ...

# Capture feedback on the entire trace
tracer.enrich_session(feedback={
    "rating": True,  # boolean: thumbs up/down
    "comment": "The response was helpful",
    "ground_truth": "Expected answer here",  # optional
})

​
On a Span

Add feedback to a specific function or operation: 
from honeyhive import HoneyHiveTracer, trace
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

@trace
def generate_response(query: str, user_id: str):
    # ... your function logic ...
    
    # Capture feedback on this specific span
    tracer.enrich_span(feedback={
        "rating": True,
        "comment": "The model hallucinated the capital",
        "user_id": user_id,
        "ground_truth": "The capital of New York is Albany",
    })
    
    return response
Distributed systems: When feedback is submitted from a different service than where the trace originated, pass the session_id to link them. See distributed tracing for details.

​
Concepts

​
What is User Feedback?

Any feedback that the end-user provides about their experience. Two types:
  1. Explicit Feedback: User-provided ratings in your app - thumbs up/down, star ratings (1-5), written comments
  2. Implicit Feedback: User actions that signal intent - clicking “Copy”, “Regenerate”, editing the response
User Feedback vs Human Evaluator: The feedback field tracks feedback from end-users. Feedback from domain experts or internal team members should use the metrics field instead.

​
Feedback Schema

The feedback object accepts any structure. Common patterns: 
{
  "rating": true,                    // boolean: thumbs up/down
  "score": 4,                        // number: star rating
  "comment": "Great response",       // string: user comment
  "ground_truth": "Expected answer", // string: for comparison (reserved field)
  "actions": {
    "copied": true,
    "regenerated": false
  }
}

​
Data Types

TypeAvailable MeasurementsUse Case
BooleanTrue/False percentageThumbs up/down
NumberSum, Avg, Median, Min, Max, P95, P98, P99Star ratings, scores
StringFilters and group byCategories, comments

​
Nested Data

You can drill down into nested fields when charting: 
{
  "rating": 5,
  "step1": { "retry": true },
  "edits": [{ "value": "New York" }]
}
Access as feedback.step1.retry (boolean) or feedback.edits.0.value (string).
Nesting limits: Max 5 levels of nested objects, max 2 levels of nested arrays.

​
Reserved Fields

FieldPurpose
ground_truthExpected output for comparison. Rendered specially in the UI.

​
Learn More

Analyzing feedback

Chart and analyze user feedback in dashboards

Enriching Traces

Full guide to trace enrichment

​
SDK Reference