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

# Custom Metrics

> Log evaluation scores, guardrail results, and custom numeric metrics from your application code onto HoneyHive traces for monitoring and analysis.

This guide shows you how to log metrics (evaluation scores, guardrail results) computed in your application code.

<Tip>
  **When to use client-side metrics:** Guardrails (format validation, safety checks, PII detection) are ideal to compute client-side at execution time rather than server-side post-ingestion.
</Tip>

## Quick Start

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

### On the Session

Add metrics that apply to the entire trace:

```python theme={null}
from honeyhive import HoneyHiveTracer
import os

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

# ... your application logic ...

tracer.enrich_session(metrics={
    "json_valid": True,
    "response_length": 150,
    "safety_score": 0.98,
})
```

### On a Span

Add metrics to a specific function or operation:

```python theme={null}
from honeyhive import HoneyHiveTracer, trace
import os

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

@trace
def generate_response(query: str):
    response = call_llm(query)
    
    # Compute metrics
    tracer.enrich_span(metrics={
        "contains_pii": check_pii(response),
        "relevance_score": compute_relevance(query, response),
        "word_count": len(response.split()),
    })
    
    return response
```

***

## Concepts

### Client-Side vs Server-Side Evaluations

| Aspect       | Client-Side               | Server-Side                 |
| ------------ | ------------------------- | --------------------------- |
| **When**     | During execution          | After ingestion             |
| **Latency**  | Adds to request time      | No impact on request        |
| **Best for** | Guardrails, format checks | LLM-as-judge, complex evals |
| **Setup**    | Code in your app          | Configure in HoneyHive      |

<Note>
  Client-side metrics are **not overwritten** by server-side evaluators with the same name.
</Note>

### Metrics Schema

The `metrics` object accepts any structure:

```json theme={null}
{
  "json_valid": true,
  "relevance_score": 0.85,
  "latency_ms": 250,
  "step_evals": [
    { "step": 1, "passed": true },
    { "step": 2, "passed": false }
  ]
}
```

### Data Types

| Type    | Available Measurements                    | Use Case          |
| ------- | ----------------------------------------- | ----------------- |
| Boolean | True/False percentage                     | Pass/fail checks  |
| Number  | Sum, Avg, Median, Min, Max, P95, P98, P99 | Scores, latencies |
| String  | Filters and group by                      | Classifications   |

### Nested Data

Access nested fields when charting: `metrics.step_evals.0.passed`

<Note>
  **Nesting limits:** Max 5 levels of nested objects, max 2 levels of nested arrays.
</Note>

***

## Learn More

<CardGroup cols={2}>
  <Card title="Chart metrics" icon="chart-line" href="/v2/monitoring/charts">
    Visualize metrics in dashboards
  </Card>

  <Card title="Server-side evaluators" icon="server" href="/v2/evaluators/python">
    Run evaluations post-ingestion
  </Card>

  <Card title="LLM evaluators" icon="brain" href="/v2/evaluators/llm">
    Use LLMs to evaluate outputs
  </Card>

  <Card title="Human annotations" icon="user-check" href="/v2/evaluators/human">
    Set up expert review queues
  </Card>
</CardGroup>

## SDK Reference

* [Python SDK Reference](https://honeyhiveai.github.io/python-sdk/) - `enrich_session()`, `enrich_span()`