Skip to main content
Beyond numeric scores, you can annotate traces with tags, comments, expected values, and metadata to provide context and build better datasets. These annotations flow between logs, datasets, and experiments. After reviewing and scoring traces, use tags, comments, and corrections to further organize and enrich your data for dataset creation.

​
Apply tags

Tags categorize and organize traces across your project. Use tags to mark traces for review, indicate status, or group related examples. Tags flow between logs, datasets, and experiments.

​
Configure tags

Set up tags at the project level:
  1. Navigate to the Configuration tab in your project.
  2. Add, modify, or delete tags with custom names, colors, and descriptions. Configure tags

​
Add tags

Select traces and apply tags from the table or trace view:

​
Add comments

Comments provide free-form context and explanations. Use comments to explain why a trace succeeded or failed, note patterns or edge cases, share insights with teammates, or document corrections.
Open any trace and add comments in the trace view:Copy links to comments to share with teammates. Comments are searchable using the filter menu.
Mention team members in comments to notify them and draw their attention to specific traces. Type @ followed by their name and select from the autocomplete dropdown. Mentioned users receive email notifications with direct links to the specific row and comment.

​
Update expected values

Expected values define the correct or ideal output for a given input. Update expected values to provide ground truth for evaluation, document user corrections, specify multiple acceptable answers, or label categorical data.
Click any expected field in a trace to edit it directly. You can:
  • Enter structured JSON data
  • Use form-based editing (if schemas are defined)
  • Write categorical labels via human review scores
  • Copy expected values from other spans Write to expected
You can also create human review scores when reviewing traces.

​
Add metadata

Metadata provides structured context for filtering and analysis. Common metadata includes user IDs and session IDs, feature flags or A/B test variants, geographic or demographic information, request source or client type, and custom business context.
Add metadata when logging or via feedback:
// When logging
span.log({
  input,
  output: result,
  metadata: {
    user_id: userId,
    feature_variant: "test-a",
    request_source: "mobile-app",
  },
});

// Via feedback
logger.logFeedback({
  id: spanId,
  metadata: {
    reviewer: "jane@company.com",
    review_date: new Date().toISOString(),
    category: "edge-case",
  },
});

​
Filter by annotations

Use filters to find annotated traces: 
WHERE tags INCLUDES "needs-review"

WHERE comment IS NOT NULL

WHERE metadata.category = "edge-case"

WHERE expected IS NOT NULL
Combine filters to build precise queries for dataset curation.

​
Next steps