Guide: Adding custom metadata to Claw spans for our CRM

Everyone talks about enriching LLM traces with business context, but most guides stop at user ID or session number. For those of us in CRM workflows, that's useless. I needed to attach CRM-specific metadata to spans in Claw—think lead stage, opportunity amount, even the sales rep's territory—to actually trace why a support agent's LLM summary took 12 seconds or why a lead scoring model anomaly occurred.

Here’s what I figured out after the Claw UI update last month broke the previous tag injection method. You now have to do this at the span creation level, not in post-processing.

First, define your key metadata points. Mine were:
- `crm.object_type`: e.g., "lead", "contact", "account"
- `crm.object_id`: the internal GUID
- `crm.workflow_stage`: e.g., "qualification", "proposal", "closed-won"
- `crm.assigned_rep_id`: for cost attribution per salesperson

The trick is to use the Claw SDK's span attributes, not the generic tags. The old `claw.add_tags()` method is deprecated for custom fields. Now you set it on the span at start.

```python
from claw_sdk import Claw
claw = Claw()

with claw.start_span(name="crm_lead_score", type="llm") as span:
span.set_attributes({
"crm.object_type": "lead",
"crm.object_id": lead.id,
"crm.workflow_stage": lead.stage,
"crm.assigned_rep_id": lead.owner_id
})
# Your LLM call here
score = llm_client.generate(prompt)
```

This ensures the metadata is baked into the span from the outset and shows up correctly in the trace breakdown views. Without this, trying to filter traces for "all LLM calls on leads in 'proposal' stage" is impossible.

A couple of gotchas:
* Attribute keys must be strings, and values must be strings, booleans, or numbers. Don't try to dump a whole object.
* If you're using the auto-instrumentation wrappers, you'll need to use span processors or middleware to inject this. It's more verbose.
* The Claw dashboard won't show these in the main trace list by default. You have to configure the trace list view to add these as columns.

Doing this finally let me correlate LLM latency spikes with complex opportunity records. Turns out the summarization model was choking on accounts with >50 activity logs, not the dollar amount like we assumed.

-- CRM Surfer