> ## Documentation Index
> Fetch the complete documentation index at: https://next.gentrace.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry API

> Submit trace data to Gentrace via OpenTelemetry Protocol (OTLP)

This document details Gentrace's support for receiving spans via the
[OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/)
and outlines the expected span attributes and events.

For more details on setting up Gentrace to receive spans, see the [OpenTelemetry guide](/reference/opentelemetry-guide).

<Info>
  For a complete working example of using GenAI semantic conventions
  with Gentrace, see our [GenAI semantic conventions
  example](https://github.com/gentrace/gentrace-node/blob/main/examples/genai-semantic-conventions.ts)
  in the Gentrace Node.js SDK repository.
</Info>

## OTLP endpoint

Gentrace ingests OpenTelemetry spans via HTTP.

```http theme={null}
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

<Info>
  If using the Gentrace SDK, the
  [`interaction()`](../tracing/interactions),
  [`traced()`](../tracing/traced), [`eval()` /
  `evalOnce()`](../evaluation/unit-tests), and [`eval_dataset()` /
  `evalDataset()`](../evaluation/dataset-tests) functions
  automatically set these attributes for you.
</Info>

#### Attributes

<ResponseField name="gentrace.pipeline_id" type="string">
  Used to route the span to a Gentrace pipeline in the traces tab. Use
  `default` to route to the default pipeline.
</ResponseField>

<ResponseField name="gentrace.experiment_id" type="string">
  Used to route the span to a Gentrace experiment.
</ResponseField>

<ResponseField name="gentrace.test_case_name" type="string" required>
  The descriptive name of the test case. Automatically set by
  [`eval()`](../evaluation/unit-tests) or
  [`evalDataset()`](../evaluation/dataset-tests).
</ResponseField>

<ResponseField name="gentrace.test_case_id" type="string">
  The ID of a persisted Gentrace Test Case. Automatically set by
  [`evalDataset()`](../evaluation/dataset-tests) if the underlying
  data provides an ID that corresponds to a `TestCase` in Gentrace.
</ResponseField>

<ResponseField name="gentrace.sample" type="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()`](../tracing/interactions) and
  [`eval()`](../evaluation/unit-tests).
</ResponseField>

<ResponseField name="gentrace.in_experiment" type="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()`](../evaluation/experiments),
  [`eval()`](../evaluation/unit-tests), or
  [`evalDataset()`](../evaluation/dataset-tests).
</ResponseField>

#### Events

<ResponseField name="gentrace.fn.args" type="event">
  Used to capture the arguments passed to the function. Should be set when the function is called.

  <Expandable title="Event attributes" defaultOpen>
    <ResponseField name="args" type="string" required>
      A stringified JSON array of the arguments passed to the function.

      ```javascript theme={null}
      // Example: function called with (user, "prompt", { temp: 0.7 })
      span.addEvent('gentrace.fn.args', { 
        args: JSON.stringify([user, "prompt", { temp: 0.7 }]) 
      });
      ```
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gentrace.fn.output" type="event">
  Used to capture the output of the function. Should be set when the function returns.

  <Expandable title="Event attributes" defaultOpen>
    <ResponseField name="output" type="string" required>
      A stringified JSON representation of the function's return value.

      ```javascript theme={null}
      // Example: function returns { result: "success", data: [...] }
      span.addEvent('gentrace.fn.output', { 
        output: JSON.stringify({ result: "success", data: [...] }) 
      });
      ```
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="span.name" type="string" required>
  The name of the span, typically set to the test case name.
</ResponseField>

## GenAI semantic conventions

Spans following the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) for AI/LLM operations.

### Attributes

<ResponseField name="gen_ai.system" type="string" required>
  The AI system used (e.g., "openai", "anthropic").
</ResponseField>

<ResponseField name="gen_ai.request.model" type="string" required>
  The specific model requested (e.g., "o3").
</ResponseField>

<ResponseField name="gen_ai.operation.name" type="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.
</ResponseField>

<ResponseField name="service.name" type="string" required>
  Identifies the service generating the span (e.g.,
  "my-chat-service").
</ResponseField>

<ResponseField name="span.name" type="string" required>
  The name of the span, often the function or operation name being
  traced.
</ResponseField>

### Events

GenAI LLM spans use events to capture prompt and completion data. See the [OpenTelemetry GenAI Events Specification](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/) for complete documentation.

<ResponseField name="gen_ai.message" type="event">
  Represents a single message in a prompt or completion sequence. Can also use system-specific variants like `gen_ai.openai.message`.

  <Expandable title="Event attributes" defaultOpen>
    <ResponseField name="role" type="string" required>
      The role of the message (e.g., "user", "assistant", "system", "tool").
    </ResponseField>

    <ResponseField name="content" type="string" required>
      The textual content of the message.
    </ResponseField>

    <ResponseField name="name" type="string">
      If the role is "tool", the name of the tool.
    </ResponseField>

    <ResponseField name="tool_calls" type="string">
      If the role is "assistant" and it makes tool calls, this contains a JSON array of tool call objects (e.g., `[{ "id": "call_abc", "type": "function", "function": { "name": "tool_name", "arguments": "{...}" } }]`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gen_ai.choice" type="event">
  Represents a choice or completion generated by an LLM, particularly when
  multiple completions are generated.

  <Expandable title="Event attributes" defaultOpen>
    <ResponseField name="index" type="integer" required>
      The index of this choice.
    </ResponseField>

    <ResponseField name="content" type="string" required>
      The content of this specific choice/completion.
    </ResponseField>

    <ResponseField name="role" type="string">
      The role associated with this choice (e.g., "assistant").
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason the LLM stopped generating tokens for this choice.
    </ResponseField>

    <ResponseField name="tool_calls" type="string">
      JSON-formatted tool calls associated with this specific choice.
    </ResponseField>
  </Expandable>
</ResponseField>

## Standard OpenTelemetry events

Both span types can include standard OpenTelemetry events:

<ResponseField name="exception" type="event">
  Indicates an error or exception occurred during the span's execution. See
  [OpenTelemetry exception
  recording](https://opentelemetry.io/docs/specs/otel/trace/exceptions/) for
  more details.

  <Expandable title="Event attributes" defaultOpen>
    <ResponseField name="exception.type" type="string" required>
      The type or class name of the exception (e.g., `Error`, `TypeError`).
    </ResponseField>

    <ResponseField name="exception.message" type="string" required>
      The error message.
    </ResponseField>

    <ResponseField name="exception.stacktrace" type="string">
      The stack trace associated with the exception.
    </ResponseField>
  </Expandable>
</ResponseField>

This documentation provides a concise overview. For more in-depth information on
OpenTelemetry concepts, refer to the official
[OpenTelemetry Specification](https://opentelemetry.io/docs/specs/).

## See also

* [OpenTelemetry Setup Guide](../reference/opentelemetry-guide)
* [Pipelines API Reference](../sdk-entities/pipelines)
* [Experiments API Reference](../sdk-entities/experiments)
* [Test Cases API Reference](../sdk-entities/test-cases)
* [Datasets API Reference](../sdk-entities/datasets)