Configure attribute mappers
Map incoming OpenTelemetry attributes onto Judgment's structured trace fields at ingest.
Configure an attribute mapper when incoming spans contain the right value under a key Judgment does not recognize. A mapper copies a source attribute onto a public Judgment target during trace ingestion, without changing the instrumentation that produced the span.
Judgment’s built-in mappers already normalize common OpenTelemetry GenAI
attributes, including gen_ai.system, gen_ai.response.model,
gen_ai.usage.input_tokens, and gen_ai.usage.output_tokens. Do not add a
configured mapper for those standard keys. Configure one when application- or
provider-specific source keys are not normalized automatically.
Choose mappings
Identify the incoming source keys from one real span, then pair each one with a target from Attribute keys.
| Source key | Target key |
|---|---|
app.ai.provider |
judgment.llm.provider |
app.ai.model |
judgment.llm.model |
app.ai.prompt_tokens |
judgment.usage.non_cached_input_tokens |
app.ai.completion_tokens |
judgment.usage.output_tokens |
These app.ai.* keys are illustrative application-defined attributes. Replace
them with the exact source keys from your spans. Judgment’s built-in provider
and generic mappers run first, so add a configured mapper only for values they
do not already normalize.
Create the mapper
-
Open the intended project in Judgment.
-
Go to Settings → Mappers.
-
Select New Mapper and give it a descriptive name.
-
Add one or more source-to-target mapping rules.
-
Keep Enabled on.
-
Choose how conflicts and source retention should behave:
Setting Default Effect Override Off When off, the mapper preserves a target that already has a value. Turn it on only when this source should replace values from built-in mappers. Remove Source On Deletes the source after copying it. Turn it off when both the original and normalized keys should remain searchable. -
Save the mapper and send a new trace. Mappers apply during ingestion and do not rewrite spans that were already stored.
Manage mappers with MCP
The Judgment MCP server exposes the same project-scoped configuration:
| Tool | Purpose |
|---|---|
list_mappers |
List project and organization-wide mappers that apply to a project. |
get_mapper |
Read one mapper configuration. |
create_mapper |
Create a mapper with its name, rules, enabled state, and flags. |
update_mapper |
Change a mapper’s name, rules, enabled state, or flags. |
delete_mapper |
Delete a mapper. |
Write operations require the developer role. See Connect the Judgment MCP server for connection instructions and the MCP tools reference for exact input fields and access requirements.
Verify
Send a new trace containing the source key, then open the affected span in Judgment. Confirm that:
- The target field contains the copied value.
- Existing target values were preserved or replaced according to Override.
- The source key was kept or removed according to Remove Source.
- Structured views such as model, session, input/output, or cost now use the mapped value.
Troubleshooting
| Symptom | Check |
|---|---|
| Old traces did not change | Mappers apply only to spans ingested after the configuration is active. |
| Target stays empty | Confirm the source key exists on the incoming span and the mapper is enabled for the correct project. |
| Target keeps its previous value | Override is off, so an earlier built-in or configured mapper wins. |
| Source disappeared | Remove Source is on. Turn it off when the original key should remain. |
| Target is rejected | Select a key from the public Attribute keys list. |