DBNL Semantic Convention

How DBNL understands the structure and semantics of your data

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 and the OpenInference 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 or SQL Integration Ingestion 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
input (required)	string	ROOT:input.value
output (required)	string	ROOT:output.value
timestamp (required)	timestamptz	ROOT:start_time
spans	list<SpanType> (see below)	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"

Note: ROOT, FIRST, LAST and ANY are used as aliases for certain spans in a trace.

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
  >
>