---
title: "Configure attribute mappers"
description: "Map incoming OpenTelemetry attributes onto Judgment's structured trace fields at ingest."
seo:
  title: "Configure Attribute Mappers | Judgment Docs"
  description: "Copy custom and OpenTelemetry GenAI attributes onto public Judgment trace keys during ingestion."
---

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](/documentation/tracing/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

1. Open the intended project in Judgment.
2. Go to **Settings → Mappers**.
3. Select **New Mapper** and give it a descriptive name.
4. Add one or more source-to-target mapping rules.
5. Keep **Enabled** on.
6. 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. |

7. Save the mapper and send a new trace. Mappers apply during ingestion and do
   not rewrite spans that were already stored.

> **Info**
>
> Only public Judgment keys can be targets. Project-scoped mappers are available
> in the selected project. Organization-wide mappers can be created only by a
> Judgment administrator.

## 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](/documentation/mcp-and-agent-tools) for connection instructions and the
[MCP tools](/documentation/mcp-and-agent-tools/mcp-tools#attribute-mappers)
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:

1. The target field contains the copied value.
2. Existing target values were preserved or replaced according to
   **Override**.
3. The source key was kept or removed according to **Remove Source**.
4. 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](/documentation/tracing/attribute-keys) list. |

## Related pages

- [Add attributes and context](/documentation/tracing/attributes)
- [Attribute keys](/documentation/tracing/attribute-keys)
- [Direct OTEL](/documentation/integrations/tracing-providers/direct-otel)