> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getfoil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals

> Track custom metrics and user feedback with Foil signals

# Signals

**Signals** are custom metrics and feedback tied to your traces. Use them to track user satisfaction, quality scores, and any custom metrics relevant to your AI application.

## What Are Signals?

Signals let you record:

* **User feedback** - Thumbs up/down, star ratings
* **Quality metrics** - Relevance, accuracy, helpfulness scores
* **Custom metrics** - Any numeric, boolean, or categorical value

Signals are linked to traces, allowing you to correlate feedback with specific AI interactions.

## Signal Types

| Type         | Description          | Example Values              |
| ------------ | -------------------- | --------------------------- |
| `feedback`   | Direct user feedback | thumbs up, thumbs down      |
| `rating`     | Numeric ratings      | 1-5 stars, 1-10 score       |
| `sentiment`  | Sentiment analysis   | positive, negative, neutral |
| `quality`    | Quality assessment   | 0.0-1.0 score               |
| `completion` | Goal completion      | true/false                  |
| `custom`     | Any custom metric    | varies                      |

## Signal Properties

| Property     | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `signalName` | string | Yes      | Name of the signal          |
| `value`      | any    | Yes      | Signal value                |
| `traceId`    | string | No       | Links to a trace            |
| `spanId`     | string | No       | Links to specific span      |
| `agentName`  | string | No       | Agent that generated signal |
| `signalType` | string | No       | Type categorization         |
| `source`     | string | No       | `user`, `system`, or `llm`  |
| `confidence` | number | No       | Confidence score (0-1)      |
| `reasoning`  | string | No       | Explanation for the value   |
| `metadata`   | object | No       | Additional context          |

## Recording Signals

```javascript theme={null}
await foil.trace(async (ctx) => {
  // Do AI work...

  // Record user feedback
  await ctx.recordFeedback(true); // thumbs up

  // Record star rating
  await ctx.recordRating(4); // 4 out of 5 stars

  // Record custom signal
  await ctx.recordSignal('response_quality', 0.85, {
    signalType: 'quality',
    source: 'llm',
    confidence: 0.92
  });
});
```

## Signal Sources

| Source   | Description              |
| -------- | ------------------------ |
| `user`   | Direct user feedback     |
| `system` | Automated system metrics |
| `llm`    | LLM-based evaluation     |

<Accordion title="Batch recording">
  Record multiple signals at once to reduce API calls:

  ```javascript theme={null}
  await foil.recordSignalBatch([
    { signalName: 'relevance', value: 0.9, traceId: 'trace-123', signalType: 'quality' },
    { signalName: 'helpfulness', value: 0.85, traceId: 'trace-123', signalType: 'quality' },
    { signalName: 'goal_completed', value: true, traceId: 'trace-123', signalType: 'completion' }
  ]);
  ```
</Accordion>

<Tip>
  **Full example**: [customer-support-agent](https://github.com/getfoil/foil-examples/tree/main/customer-support-agent) — records feedback signals (thumbs up/down) on every conversation trace.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Use consistent signal names">
    Standardize names across your application for better aggregation:

    * `user_rating` not `rating`, `stars`, `score`
    * `response_quality` not `quality`, `resp_qual`
  </Accordion>

  <Accordion title="Include confidence for LLM signals">
    When using LLMs to evaluate, always include a confidence score.
  </Accordion>

  <Accordion title="Link signals to traces">
    Always include `traceId` to correlate signals with the AI interaction that generated them.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/concepts/agents">
    Organize by agent
  </Card>

  <Card title="Analytics" icon="chart-line" href="/features/analytics">
    Analyze signal trends
  </Card>
</CardGroup>