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 ensure that your spans adhere to this semantic convention.

If you are using SDK Log Ingestion or 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)	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.

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