> For the complete documentation index, see [llms.txt](https://docs.dbnl.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnl.com/v0.26.x/configuration/dbnl-semantic-convention.md).

# DBNL Semantic Convention

## Mapping Fields to Semantically Understood Columns

DBNL ingests data using traces produced using telemetry frameworks with different semantic conventions as well as tabular logs with a user defined format.

To compute metrics and derive insights consistently across different data ingestion formats, we define a semantic convention for the data as stored within DBNL.

If you are using [OTEL Trace Ingestion](/v0.26.x/configuration/data-connections/otel-trace-ingestion.md) and the [OpenInference](https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md) semantic convention, this happens automatically, see the table below for how data maps from one convention to another.

If you are using [SDK Log Ingestion](/v0.26.x/configuration/data-connections/sdk-log-ingestion.md) or [SQL Integration Ingestion](/v0.26.x/configuration/data-connections/sql-integration-ingestion.md) you need to ensure that your column names adhere to our semantic convention for best results.

## Required Fields

The following fields are required regardless of which ingestion method you are using:

* `input`: The text input to the LLM as a `string`.
* `output`: The text response from the LLM as a `string`.
* `timestamp`: The UTC timecode associated with the LLM call as a `timestamptz`.

## DBNL Semantic Convention

The DBNL Semantic Convention is a mapping from well known formats into types and names that DBNL can recognize.

| DBNL SemConv               | DBNL Type                                      | [OpenInference SemConv](https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md) |
| -------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **`input` (required)**     | `string`                                       | `ROOT:input.value`                                                                                        |
| **`output` (required)**    | `string`                                       | `ROOT:output.value`                                                                                       |
| **`timestamp` (required)** | `timestamptz`                                  | `ROOT:start_time`                                                                                         |
| `spans`                    | `list<SpanType>` ([see below](#spans-example)) | Raw list of spans                                                                                         |
| `status`                   | `category`                                     | `ROOT:status.code`                                                                                        |
| `duration_ms`              | `int`                                          | `ROOT:end_time - ROOT:start_time`                                                                         |
| `session_id`               | `string`                                       | `ROOT:session.id`                                                                                         |
| `trace_id`                 | `string`                                       | `ROOT:trace_id`                                                                                           |
| `total_token_count`        | `int`                                          | `sum(*:llm.token_count.total)`                                                                            |
| `prompt_token_count`       | `int`                                          | `sum(*:llm.token_count.prompt)`                                                                           |
| `completion_token_count`   | `int`                                          | `sum(*:llm.token_count.completion)`                                                                       |
| `total_cost`               | `float` (USD)                                  | `sum(*:llm.cost.total)`                                                                                   |
| `prompt_cost`              | `float` (USD)                                  | `sum(*:llm.cost.prompt)`                                                                                  |
| `completion_cost`          | `float` (USD)                                  | `sum(*:llm.cost.completion)`                                                                              |
| `tool_call_count`          | `int`                                          | `count(*) WHERE kind = "TOOL"`                                                                            |
| `tool_call_name_counts`    | `map<string, int>`                             | `count(*:tool.name)`                                                                                      |
| `tool_call_error_count`    | `int`                                          | `count(*:status.code = "ERROR") WHERE kind = "TOOL"`                                                      |
| `llm_call_count`           | `int`                                          | `count(*:openinference.span.kind == "LLM")`                                                               |
| `llm_call_model_counts`    | `map<string, int>`                             | `count(*:llm.model_name)`                                                                                 |
| `llm_call_error_count`     | `int`                                          | `count(*:status.code = "ERROR") WHERE kind = "LLM"`                                                       |

{% hint style="warning" %}
Note: `ROOT`, `FIRST`, `LAST` and `ANY` are used as aliases for certain spans in a trace.
{% endhint %}

### Spans Example

```
struct<
  trace_id: string, 
  span_id: string,
  trace_state: string,
  parent_span_id: string,
  name: string,
  kind: string,
  start_time: timestamptz,
  end_time: timestamptz,
  attributes: map<string, string>,
  events: list<
    struct<
      timestamp: timestamptz, 
      name: string, 
      attributes: map<string, string>
    >
  >, 
  links: list<
    struct<
      trace_id: string, 
      span_id: string, 
      trace_state: string, 
      attributes: map<string, string>
    >
  >, 
  status: struct<
    code: string, 
    message: string
  >
>
```