# 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](https://docs.dbnl.com/v0.27.x/configuration/data-connections/otel-trace-ingestion) ensure that your spans adhere to this semantic convention.

If you are using [SDK Log Ingestion](https://docs.dbnl.com/v0.27.x/configuration/data-connections/sdk-log-ingestion) or [SQL Integration Ingestion](https://docs.dbnl.com/v0.27.x/configuration/data-connections/sql-integration-ingestion) you need provide a spans column and 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                                      | Description                                                                       |
| -------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
| `input` (**Required**)     | `string`                                       | The input to the AI app invocation.                                               |
| `output` (**Required**)    | `string`                                       | The output from the AI app invocation.                                            |
| `timestamp` (**Required**) | `timestamptz`                                  | The timestamp of the AI app invocation.                                           |
| `spans`                    | `list<SpanType>` ([see below](#spans-example)) | The spans representing operations within the AI app invocation.                   |
| `status`                   | `category`                                     | The status of the AI app invocation (e.g., Ok, Error).                            |
| `duration_ms`              | `int`                                          | The duration of the AI app invocation in milliseconds.                            |
| `session_id`               | `string`                                       | The session ID associated with the AI app invocation.                             |
| `trace_id`                 | `string`                                       | The trace ID associated with the AI app invocation.                               |
| `user_id`                  | `string`                                       | The user ID associated with the AI app invocation.                                |
| `total_token_count`        | `int`                                          | The total number of tokens used in the AI app invocation.                         |
| `prompt_token_count`       | `int`                                          | The number of prompt tokens used in the AI app invocation.                        |
| `completion_token_count`   | `int`                                          | The number of completion tokens used in the AI app invocation.                    |
| `total_cost`               | `float`                                        | The total cost of the AI app invocation.                                          |
| `prompt_cost`              | `float`                                        | The cost of the prompt tokens in the AI app invocation.                           |
| `completion_cost`          | `float`                                        | The cost of the completion tokens in the AI app invocation.                       |
| `tool_call_count`          | `int`                                          | The number of tool calls made during the AI app invocation.                       |
| `tool_call_error_count`    | `int`                                          | The number of tool call errors during the AI app invocation.                      |
| `tool_call_name_counts`    | `map<string, int>`                             | A map of tool call names to their respective counts during the AI app invocation. |
| `llm_call_count`           | `int`                                          | The number of LLM calls made during the AI app invocation.                        |
| `llm_call_error_count`     | `int`                                          | The number of LLM call errors during the AI app invocation.                       |
| `llm_call_model_counts`    | `map<string, int>`                             | A map of LLM models to their respective call counts during the AI app invocation. |
| `feedback_score`           | `float`                                        | The feedback score for the AI app invocation.                                     |
| `feedback_text`            | `string`                                       | The feedback text for the AI app invocation.                                      |
| `call_sequence`            | `list<string>`                                 | The sequence of calls (e.g. tools, llms) made during the AI app invocation.       |

{% 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
  >
>
```