This document details Gentrace’s support for receiving spans via the OpenTelemetry Protocol (OTLP) and outlines the expected span attributes and events. For more details on setting up Gentrace to receive spans, see the OpenTelemetry guide.
For a complete working example of using GenAI semantic conventions with Gentrace, see our GenAI semantic conventions example in the Gentrace Node.js SDK repository.

​
OTLP endpoint

Gentrace ingests OpenTelemetry spans via HTTP. 
POST /api/otel/v1/traces
Content-Type: application/x-protobuf
  • Endpoint: /api/otel/v1/traces (Relative to your Gentrace instance base URL)
  • Method: POST
  • Format: OTLP/HTTP (protobuf)

​
Gentrace attributes and events

Spans may have the following gentrace attributes in order to be ingested by Gentrace. If a trace has at least one span with a gentrace attribute, the entire trace will be retained by Gentrace. Otherwise, the trace is assumed to irrelevant and is discarded.

​
Interaction/Traced spans

If using the Gentrace SDK, the interaction(), traced(), eval() / evalOnce(), and eval_dataset() / evalDataset() functions automatically set these attributes for you.

​
Attributes

​
gentrace.pipeline_id
string
Used to route the span to a Gentrace pipeline in the traces tab. Use default to route to the default pipeline.
​
gentrace.experiment_id
string
Used to route the span to a Gentrace experiment.
​
gentrace.test_case_name
string
required
The descriptive name of the test case. Automatically set by eval() or evalDataset().
​
gentrace.test_case_id
string
The ID of a persisted Gentrace Test Case. Automatically set by evalDataset() if the underlying data provides an ID that corresponds to a TestCase in Gentrace.
​
gentrace.sample
string
Set to "true" to indicate this span (and its children) should be sampled and sent to Gentrace. Automatically set by SDK wrapper functions like interaction() and eval().
​
gentrace.in_experiment
string
Set to "true" to indicate this span was created during an experiment. This prevents your production evaluations from running on test spans. Automatically set on test spans and all downstream spans when using experiment(), eval(), or evalDataset().

​
Events

​
gentrace.fn.args
event
Used to capture the arguments passed to the function. Should be set when the function is called.
​
gentrace.fn.output
event
Used to capture the output of the function. Should be set when the function returns.
​
span.name
string
required
The name of the span, typically set to the test case name.

​
GenAI semantic conventions

Spans following the OpenTelemetry GenAI semantic conventions for AI/LLM operations.

​
Attributes

​
gen_ai.system
string
required
The AI system used (e.g., “openai”, “anthropic”).
​
gen_ai.request.model
string
required
The specific model requested (e.g., “o3”).
​
gen_ai.operation.name
string
required
The specific operation performed by the LLM (e.g., “chat”, “completion”, “embedding”). Note: The server also looks for operation.name for backward compatibility with older Traceloop conventions.
​
service.name
string
required
Identifies the service generating the span (e.g., “my-chat-service”).
​
span.name
string
required
The name of the span, often the function or operation name being traced.

​
Events

GenAI LLM spans use events to capture prompt and completion data. See the OpenTelemetry GenAI Events Specification for complete documentation.
​
gen_ai.message
event
Represents a single message in a prompt or completion sequence. Can also use system-specific variants like gen_ai.openai.message.
​
gen_ai.choice
event
Represents a choice or completion generated by an LLM, particularly when multiple completions are generated.

​
Standard OpenTelemetry events

Both span types can include standard OpenTelemetry events:
​
exception
event
Indicates an error or exception occurred during the span’s execution. See OpenTelemetry exception recording for more details.
This documentation provides a concise overview. For more in-depth information on OpenTelemetry concepts, refer to the official OpenTelemetry Specification.

​
See also