> ## 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 and guardrail results computed in your application

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"),
    project=os.getenv("HH_PROJECT"),
)

# ... 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"),
    project=os.getenv("HH_PROJECT"),
)

@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()`